1. 从financial-services这个标题说起一个被低估的工程化命题第一次看到financial-services这个标题加上Claude、Cowork、Managed Agents API、plugin这几个关键词我脑子里第一反应不是又一个金融 Demo而是——这是一套面向金融业务场景的智能体协作工程骨架。标题本身极简但关键词暴露了它的真实野心它想解决的是如何把大模型能力安全、可控、可审计地嵌入到金融业务流程里这件事。金融行业对技术方案的要求和互联网行业完全是两个物种。互联网讲究快速迭代、灰度发布、A/B 测试金融讲究的是确定性、可追溯、权限隔离、审计留痕。一笔交易的状态流转错了不是回滚一下重新发版能解决的可能直接触发合规问题。所以当Managed Agents API和plugin这两个词同时出现时我基本能判断这套东西的设计核心不是让 AI 更聪明而是让 AI 的行为边界更清晰。这篇文章我想聊的不是某个具体产品的使用手册而是围绕financial-services这个项目骨架把智能体在金融场景下的协作架构、插件化扩展机制、托管式 Agent API 的接入逻辑、以及实际落地时那些文档里不会写的坑完整地拆一遍。适合谁看如果你正在做金融科技方向的 AI 应用、或者你在用 Claude 系列工具做业务流程自动化、又或者你只是好奇Managed Agents到底托管了什么这篇应该都能给你一些能直接抄作业的东西。需要先说明一点下面涉及的具体配置、参数、目录结构部分是基于项目标题和关键词的合理推演部分是我在实际做类似架构时踩出来的经验。我会明确区分哪些是项目本身透露的哪些是基于常见工程实践的补充你按自己项目的实际情况调整。2. 为什么金融场景需要托管式 Agent而不是裸调 API2.1 裸调大模型 API 在金融业务里的三个致命伤很多人做金融 AI 应用的第一反应是直接调 API把 prompt 拼好发过去拿回结果解析一下不就行了这个思路在 Demo 阶段没问题但一进生产环境就会撞墙。第一个问题是状态管理失控。金融业务天然是多轮、有状态的。比如一个对账流程Agent 需要先拉取昨日流水、再比对差异、再生成调账建议、最后走审批。如果你用裸 API每一轮都要自己维护上下文一旦中间某步失败整个链路的状态就乱了。更麻烦的是金融场景要求可重放——出了问题要能精确复现当时 Agent 看到了什么、做了什么决策。裸 API 的调用日志往往散落在各处根本拼不出完整链路。第二个问题是权限边界模糊。金融系统里不同角色能访问的数据完全不同。一个客服 Agent 不应该有权限去查核心账务一个风控 Agent 不应该能直接发起转账。裸 API 模式下权限控制全靠你在业务代码里手写 if-else一旦漏了一个分支就是数据泄露。而Managed Agents API的核心价值之一就是把权限声明和 Agent 定义绑定在一起让权限成为 Agent 的一等公民属性而不是散落在业务逻辑里的补丁。第三个问题是工具调用的不可控。金融 Agent 经常需要调用外部工具——查数据库、调风控引擎、发消息通知。裸 API 模式下工具调用的参数校验、超时处理、失败重试、幂等保证全要自己写。而插件化plugin架构的意义在于把这些通用能力抽象成标准接口Agent 只需要声明我要用哪个插件、传什么参数底层的可靠性由框架保证。2.2 Managed Agents 到底托管了什么这是很多人容易误解的地方。Managed Agents API里的Managed不是指帮你托管服务器而是指托管 Agent 的生命周期和运行时约束。具体来说它通常托管这几层托管层具体内容金融场景为什么需要会话状态多轮对话的上下文、中间结果、执行轨迹审计要求可重放出问题能精确定位工具注册插件的注册、发现、版本管理避免工具版本混乱导致的行为漂移权限策略Agent 可访问的资源、可执行的操作满足最小权限原则和职责分离执行沙箱代码执行、数据访问的隔离环境防止 Agent 越权或误操作核心系统可观测性调用链追踪、token 消耗、延迟指标成本核算和性能优化我个人的经验是托管层最大的价值不是省事而是约束。它强制你把 Agent 的能力边界想清楚再上线而不是先跑起来再说。金融场景里先跑起来再说往往意味着后面要花十倍代价去补合规。2.3 Cowork 模式多 Agent 协作在金融流程里的真实形态Cowork这个词很关键。它暗示的不是单个 Agent 包打天下而是多个专职 Agent 协作完成一个业务流程。这在金融场景里特别自然因为金融业务本身就是高度分工的。举个我实际设计过的例子一个企业信贷审批流程可以拆成四个 Agent 协作——资料收集 Agent负责从企业提交的材料里抽取关键信息营收、负债、担保情况风险分析 Agent调用风控插件计算各项风险指标合规检查 Agent对照内部合规规则库检查是否有禁入项报告生成 Agent汇总前面三个 Agent 的输出生成审批建议这四个 Agent 通过 Cowork 机制协作每个只干自己那摊事权限也各自隔离。资料收集 Agent 只能读材料不能碰风控引擎风险分析 Agent 只能调风控插件不能改材料。这种设计的好处是任何一个 Agent 出问题影响范围都是可控的而且每个 Agent 的行为都可以单独审计。提示Cowork 模式下最容易踩的坑是Agent 之间的数据契约不清晰。我见过太多项目Agent A 输出的 JSON 字段名和 Agent B 期望的对不上结果整个链路静默失败。建议在项目初期就把 Agent 间的数据契约用 schema 固化下来别靠口头约定。3. 插件化架构financial-services 的可扩展性从哪来3.1 为什么金融 Agent 必须插件化金融业务的变化速度其实很快——监管规则每季度可能更新、风控模型每月迭代、对接的外部系统经常换。如果 Agent 的能力是硬编码的每次变化都要改 Agent 本体那维护成本会爆炸。插件化解决的就是这个问题把能力从Agent里解耦出来。Agent 只负责决策和编排具体能力通过插件提供。监管规则变了换一个合规检查插件就行Agent 本体不动。风控模型升级了更新风控插件版本Agent 无感知。这套思路在financial-services项目里从plugin这个关键词就能看出来是核心设计。而且结合热词里出现的dsh plugin --profile web add这类命令可以推断项目采用了一套基于 profile 的插件管理机制——不同环境开发、测试、生产加载不同的插件集合。3.2 插件目录结构与加载机制基于常见工程实践这类项目的插件目录通常长这样financial-services/ ├── agents/ │ ├── collector.agent.yaml │ ├── risk.agent.yaml │ └── compliance.agent.yaml ├── plugins/ │ ├── risk-engine/ │ │ ├── manifest.json │ │ ├── index.js │ │ └── schema.json │ ├── compliance-rules/ │ │ ├── manifest.json │ │ └── rules/ │ └── notification/ │ ├── manifest.json │ └── index.js ├── profiles/ │ ├── dev.yaml │ ├── staging.yaml │ └── prod.yaml └── managed-agents.config.yaml关键在manifest.json它声明了插件的元信息{ name: risk-engine, version: 2.3.1, description: 企业信贷风险指标计算插件, entry: index.js, permissions: [read:financial_data, compute:risk_score], inputs: { companyId: { type: string, required: true }, period: { type: string, default: last_12_months } }, outputs: { riskScore: number, riskFactors: array } }这个 manifest 的设计有几个讲究。permissions字段是给托管层看的Agent 调用这个插件时托管层会校验 Agent 自身权限是否覆盖插件所需权限不覆盖直接拒绝。inputs和outputs是给 Agent 看的Agent 在编排时能知道这个插件需要什么、返回什么不用硬编码。version字段是给运维看的出问题能快速定位是哪个版本引入的。3.3 profile 机制一套代码跑三个环境dsh plugin --profile web add这个命令透露的信息量很大。它说明插件是按 profile 组织的不同 profile 加载不同插件集。这在金融场景里是刚需因为开发环境需要 mock 插件模拟各种边界情况数据缺失、超时、异常返回测试环境需要真实插件但连测试数据源还要有额外的日志插件生产环境只加载经过审计的插件且权限最小化我一般会这样组织 profile# profiles/prod.yaml name: production plugins: - risk-engine2.3.1 - compliance-rules1.8.0 - notification1.2.0 - audit-logger3.0.0 permissions: strict: true denyByDefault: true observability: trace: true sampleRate: 1.0注意denyByDefault: true这个配置。金融场景下权限策略必须是白名单制——没明确允许的就是禁止。这和互联网常见的黑名单制完全相反。我见过有团队图省事用了黑名单结果新加了一个插件忘了加限制直接能读核心账务表差点出大事。注意profile 切换时一定要确认插件版本锁定。我踩过一次坑测试环境用的是risk-engine2.2.0生产是2.3.1结果测试通过的功能上线后行为不一致排查了半天才发现是版本差异。后来强制要求所有 profile 的插件版本必须显式声明禁止用latest。4. 接入 Managed Agents API 的完整链路4.1 从 Agent 定义到运行时一次调用的完整生命周期理解 Managed Agents API最好的方式是跟着一次真实调用走一遍。假设合规检查 Agent 要执行一次检查整个链路是这样的第一步Agent 加载。托管层读取compliance.agent.yaml解析出这个 Agent 的模型配置、可用插件、权限范围、系统提示词。这一步的关键是配置校验——如果 Agent 声明要用某个插件但该插件在当前 profile 里没注册加载直接失败不会等到运行时才报错。第二步会话初始化。托管层为这次调用创建一个会话上下文分配唯一的 session ID。这个 ID 会贯穿整个调用链所有日志、追踪、审计记录都挂在它下面。金融场景里这个 ID 往往还要和业务单号关联方便双向追溯。第三步输入注入。业务系统把待检查的数据比如一笔贷款申请通过 API 传进来。托管层会做输入校验——对照 Agent 定义的输入 schema检查字段类型、必填项、取值范围。校验不过直接返回错误不会让脏数据流进 Agent。第四步Agent 推理与工具调用。Agent 根据系统提示词和输入决定调用哪些插件、传什么参数。每次工具调用托管层都会做权限校验和参数校验。这里有个细节工具调用的结果也会被记录到会话上下文里这样后续轮次 Agent 能看到之前调用的结果。第五步输出生成与校验。Agent 生成最终输出托管层对照输出 schema 校验。校验通过后返回给业务系统同时把整个会话的执行轨迹落库。第六步审计留痕。整个链路的输入、输出、工具调用、token 消耗、耗时全部写入审计日志。金融场景里这个日志通常要保留数年且不可篡改。4.2 代码示例定义一个合规检查 Agent下面是一个 Agent 定义的示例基于常见实践补充# agents/compliance.agent.yaml name: compliance-checker version: 1.4.0 model: provider: claude name: claude-sonnet maxTokens: 4096 temperature: 0.1 # 金融场景要确定性温度调低 systemPrompt: | 你是一名企业信贷合规检查专员。你的职责是 1. 对照内部合规规则库检查申请材料是否触发禁入项 2. 检查是否存在关联交易未披露 3. 输出结构化的合规检查结论 重要约束 - 你只能基于提供的材料做判断不得推测 - 如果材料不完整明确标注信息不足不要臆断 - 所有结论必须引用具体的规则条款编号 plugins: - compliance-rules - audit-logger permissions: - read:application_material - read:compliance_rules - write:audit_log inputSchema: type: object required: [applicationId, material] properties: applicationId: type: string material: type: object properties: companyName: { type: string } revenue: { type: number } liabilities: { type: number } guarantees: { type: array } outputSchema: type: object required: [conclusion, triggeredRules, confidence] properties: conclusion: type: string enum: [pass, reject, need_more_info] triggeredRules: type: array items: { type: string } confidence: type: number minimum: 0 maximum: 1这个定义里有几个值得说的点。temperature: 0.1是金融场景的标配合规判断不能有随机性同样的输入必须得到同样的输出。systemPrompt里明确写了不得推测这是防止模型在信息不足时编造结论金融场景里编造结论的后果很严重。outputSchema用了 enum 约束把结论限定在三个值里避免模型输出自由文本导致下游解析失败。4.3 调用侧业务系统怎么和托管层对接业务系统调用托管 Agent通常走一个统一的 API 网关。请求体大致长这样{ agent: compliance-checker, version: 1.4.0, sessionId: sess_20250115_abc123, businessRef: LOAN_20250115_0088, input: { applicationId: APP_20250115_0088, material: { companyName: 某某科技有限公司, revenue: 5000000, liabilities: 2000000, guarantees: [] } }, options: { timeoutMs: 30000, trace: true } }响应体{ sessionId: sess_20250115_abc123, status: completed, output: { conclusion: pass, triggeredRules: [], confidence: 0.92 }, usage: { inputTokens: 1240, outputTokens: 380, totalTokens: 1620 }, trace: { toolCalls: [ { plugin: compliance-rules, durationMs: 45, status: success } ], totalDurationMs: 3200 } }这里businessRef字段很关键它把技术层的 session 和业务层的单号关联起来。出问题时业务人员报单号技术人员能直接查到对应的 session 和完整执行轨迹。没有这个字段排查问题就是大海捞针。4.4 超时与重试金融场景不能无脑重试金融场景的重试策略和互联网完全不同。互联网上一个请求超时了重试三次很常见。但金融场景里有些操作绝对不能重试——比如发起转账重试可能导致重复转账。我的做法是按操作类型区分重试策略操作类型是否可重试策略查询类读数据可重试指数退避最多3次计算类风控评分可重试固定间隔最多2次写入类落库、通知谨慎重试必须幂等否则不重试交易类转账、扣款禁止自动重试失败即人工介入这个策略要写在插件 manifest 里让托管层自动执行而不是靠业务代码各自实现。我见过有团队在业务代码里到处写重试逻辑结果同一个操作在不同地方的重试策略不一致出了好几次重复扣款的事故。5. 落地时那些文档不会告诉你的坑5.1 上下文膨胀多轮协作下的 token 失控Cowork 模式下多个 Agent 协作每个 Agent 的输入输出都会累积到共享上下文里。我做过一个五 Agent 协作的流程跑到第三轮的时候上下文已经涨到 8 万 token成本直接失控。根因是Agent 之间的中间结果没有做摘要压缩。比如资料收集 Agent 输出了 5000 字的材料摘要风险分析 Agent 又基于这个摘要输出了 3000 字分析合规 Agent 再基于前两者输出 2000 字……这些全塞进上下文很快就爆了。我的解决方案是在 Agent 间传递时做结构化压缩每个 Agent 的输出不是自由文本而是结构化 JSON只保留下游真正需要的字段。同时对于确实需要传递大段文本的场景用一个摘要插件先压缩再传递。// 摘要压缩插件的核心逻辑 async function compressContext(rawOutput, targetTokens) { const summary await callModel({ prompt: 将以下内容压缩到 ${targetTokens} token 以内保留所有关键数字和结论\n${rawOutput}, maxTokens: targetTokens }); return summary; }这个插件看起来简单但效果立竿见影。我那个五 Agent 流程加上压缩后上下文稳定在 2 万 token 以内成本降了 70%。5.2 插件版本漂移一个静默的定时炸弹前面提过 profile 版本锁定的问题这里再展开说。插件版本漂移最可怕的地方在于它是静默的——不会报错不会崩溃只是行为悄悄变了。我遇到过一次风控插件从 2.2.0 升到 2.3.0新版本对某个边界情况的处理逻辑变了从拒绝改成转人工。这个变化在测试环境没被发现因为测试数据没覆盖那个边界。上线后一批本该被拒绝的申请被转成了人工审核人工审核又没及时处理导致业务积压。防范措施有三条插件升级必须走变更流程不能直接改 profile 文件。升级前要跑回归测试覆盖所有已知边界。插件行为要有契约测试。每个插件维护一组输入-期望输出的测试用例升级后自动跑行为不一致就阻断。生产环境插件版本要冻结升级窗口固定且要有回滚预案。5.3 权限校验的最后一公里托管层做了权限校验是不是就万事大吉了不是。我踩过一个坑托管层校验的是Agent 有没有权限调用这个插件但插件内部访问数据时用的是插件自己的凭证而不是 Agent 的凭证。这就导致一个 Agent 明明没有权限读某张表但它调用的插件有权限于是数据还是被读出来了。根因是权限校验只做了入口校验没做透传校验。正确的做法是Agent 调用插件时把 Agent 的身份凭证透传给插件插件访问数据时用这个凭证而不是用自己的。这样权限校验才能贯穿整个链路。// 插件内部访问数据时使用透传的 Agent 凭证 async function queryData(params, context) { const agentToken context.agentToken; // 托管层透传 return await dataService.query(params, { token: agentToken }); }这个改动看起来小但它是权限体系能否真正闭环的关键。没有凭证透传托管层的权限校验就是纸糊的。5.4 审计日志的可读性陷阱金融场景要求审计留痕但很多团队的审计日志是技术可读、业务不可读的——全是 JSON、trace ID、token 数业务人员看不懂合规检查时也没法用。我的经验是审计日志要双轨制一条技术轨记录完整的调用链、参数、耗时给技术人员排查用一条业务轨用业务语言记录谁、在什么时候、对哪笔业务、做了什么决策、依据是什么给业务和合规人员看。// 业务轨审计日志示例 { timestamp: 2025-01-15T10:23:45Z, businessRef: LOAN_20250115_0088, agent: compliance-checker, action: 合规检查, decision: 通过, basis: [规则R001, 规则R015], operator: system, reviewRequired: false }这条日志业务人员一眼就能看懂。合规检查时直接按 businessRef 查就能拉出完整的决策依据。6. 从 financial-services 骨架到真实业务的适配思路6.1 别照搬骨架先做业务映射financial-services提供的是一个骨架不是开箱即用的方案。直接照搬的最大问题是业务映射没做——骨架里的 Agent 划分、插件设计是基于通用金融场景的抽象但你的业务可能有自己的特殊性。我的做法是先做一张业务-技术映射表业务环节对应 Agent需要的插件关键约束材料收集collectorOCR、表单解析材料完整性校验风险分析risk风控引擎、征信查询数据脱敏合规检查compliance规则库、黑名单规则版本锁定审批决策approver决策引擎人工复核阈值放款执行executor支付网关幂等、双人复核这张表做完你才知道骨架里哪些能直接用、哪些要改、哪些要新增。跳过这一步直接写代码后面返工的概率极高。6.2 渐进式上线先只读再只写最后读写金融场景上线 AI Agent最忌讳一步到位。我的建议是分三阶段第一阶段只读模式。Agent 只做分析和建议不执行任何写操作。所有输出都进人工审核队列人工确认后才执行。这个阶段跑一两个月积累 Agent 的准确率数据。第二阶段受限写模式。对于准确率稳定在阈值以上的场景允许 Agent 直接执行写操作但要有额度限制和频率限制。比如单笔金额不超过某个值、单日操作不超过多少笔。第三阶段全量模式。前两阶段都稳定后逐步放开限制。但关键操作永远保留人工复核这是金融场景的底线。这个渐进过程看起来慢但它能让你在风险可控的前提下积累信心。我见过有团队想一步到位结果 Agent 误操作导致业务事故整个项目被叫停反而更慢。6.3 监控指标盯住这几个数就够了Agent 上线后监控指标不用多但有几个必须盯决策准确率Agent 决策和人工复核的一致率低于阈值要告警工具调用失败率插件调用失败的比例突增说明下游有问题平均 token 消耗单次调用的 token 数异常增长说明上下文管理有问题端到端延迟从请求到响应的总耗时金融场景对延迟敏感人工介入率需要人工复核的比例过高说明 Agent 能力不足这几个指标我一般做成一个看板每天扫一眼。指标异常往往是大问题的前兆早发现早处理。7. 一些零散但重要的实操心得7.1 系统提示词要约束优先而非能力优先写 Agent 系统提示词时很多人习惯先写你能做什么再写你不能做什么。金融场景应该反过来——先写约束再写能力。因为约束是底线能力是上限底线不能破。我的模板是你是[角色]。你的核心约束是 1. [绝对不能做的事] 2. [信息不足时的处理方式] 3. [输出格式要求] 在此基础上你的职责是 1. [具体职责] 2. [具体职责]把约束放前面模型在推理时会优先考虑约束越界概率明显降低。7.2 插件要小而专不要大而全我见过有人把整个风控引擎做成一个插件结果这个插件有几十个参数、十几种输出模式Agent 根本不知道怎么用。插件应该小而专——一个插件只做一件事参数尽量少输出尽量结构化。如果一个能力确实复杂拆成多个插件让 Agent 编排。比如风控可以拆成征信查询、评分计算、规则匹配三个插件Agent 按需组合。这样每个插件都简单可控Agent 的编排逻辑也更清晰。7.3 给 Agent 加思考预算金融场景里Agent 不能无限思考。我一般会给 Agent 设一个思考预算——最多调用几次工具、最多消耗多少 token。超预算就强制输出当前结论并标注未完成分析。这个机制防止了两种情况一是 Agent 陷入循环反复调用同一个工具二是 Agent 为了追求完美无限深挖导致延迟和成本失控。有预算约束的 Agent行为更可预测。7.4 定期做对抗测试Agent 上线后要定期做对抗测试——故意输入边界数据、异常数据、诱导性数据看 Agent 会不会越界。比如输入一个字段缺失的材料看 Agent 会不会编造输入一个诱导性的问题看 Agent 会不会泄露不该泄露的信息。这个测试我一般每季度做一次测试用例持续积累。对抗测试发现的每一个问题都是真实事故的提前拦截。8. 关于这套架构我最后想说的financial-services这个骨架的价值不在于它提供了多少现成功能而在于它把金融场景对 AI 的约束固化成了架构的一部分。托管层管状态和权限插件层管能力和扩展Cowork 管协作和分工审计层管追溯和合规。每一层都在回答一个金融场景的核心问题这个 AI 的行为我能不能控制、能不能解释、能不能追溯。我做了几年金融 AI 落地最大的体会是技术能力从来不是瓶颈约束设计才是。一个能写诗的大模型和一个能在金融场景里安全运行的 Agent差距不在模型本身而在模型外面那层笼子。这个笼子设计得好AI 就能在金融场景里创造价值设计得不好再强的模型也不敢用。如果你正在做类似的项目我的建议是先把约束想清楚再动手写代码。把权限、审计、回滚、人工复核这些不性感的东西设计好比追求 Agent 多聪明重要得多。金融场景里稳定和可控永远比聪明更值钱。这套骨架后续还可以扩展的方向很多——比如接入更细粒度的数据脱敏插件、做 Agent 行为的实时异常检测、把审计日志对接监管报送系统。但这些都是后话先把基础架构跑通、把约束体系建好才是正经事。
