1. 从financial-services这个标题说起一个被低估的工程化命题第一次看到financial-services这个项目名很多人会下意识觉得它是个业务系统——账户、交易、风控、报表那一套。但结合关键词里的 Claude、Cowork、Managed Agents API、plugin 来看这个标题指向的其实是另一件事用 Claude 的 Agent 能力去承载金融场景下的协作与自动化任务。换句话说它不是教你写一个银行核心系统而是教你搭一套能干活、能协作、能托管的智能体工作流并且把它落到金融这种对准确性、可追溯性、权限边界要求极高的领域里。我之所以对这个方向感兴趣是因为金融场景和通用场景有个本质区别通用场景里 Agent 答错一句话用户笑一笑就过去了金融场景里 Agent 算错一个数、调错一个接口、把不该给的数据给了不该看的人后果是实打实的。所以financial-services这个项目真正要解决的不是能不能跑起来而是跑起来之后怎么保证它不出事、出了事怎么查、查到了怎么改。这篇文章适合三类人看一是已经在用 Claude Code / Claude Desktop 做开发想把它往业务系统里塞的工程师二是做金融科技产品、需要评估 Agent 落地可行性的技术负责人三是单纯对 Managed Agents API 和 plugin 机制好奇、想搞明白这套东西到底怎么组装起来的开发者。我会从架构拆解、plugin 机制、协作模式、权限与审计、实操踩坑几个角度把这类项目从头到尾讲透尽量给到能直接抄的配置和能直接避的坑。需要先说明一点下面涉及的具体实现细节有一部分是基于这类项目的常见工程实践做的合理补全因为原始项目正文是空的我只能从标题和关键词反推它最可能的技术形态。如果你手上的项目结构和我的推断有出入把思路拿走、把参数按你的实际情况改就行。2. 拆解 financial-services 的技术骨架Agent、Cowork 与 Managed API 各管什么2.1 为什么金融场景不能只靠一个大 Agent包打天下很多人做 Agent 的第一反应是写一个超级 prompt把所有能力塞进去让它自己判断该干嘛。这个思路在 demo 阶段很爽一上生产就崩。原因很简单——金融业务天然是分角色、分权限、分流程的。一个负责查余额的 Agent 和一个负责发起转账的 Agent它们能碰的数据、能调的接口、能触发的下游动作完全不同。你把它们揉成一个等于把权限边界也揉没了。financial-services这类项目的正确姿势是多 Agent 协作也就是关键词里的 Cowork 所指向的方向。Cowork 的核心思想是把一个大任务拆成若干子任务每个子任务交给一个职责单一的 AgentAgent 之间通过结构化的消息而不是自由文本传递结果。这样做的好处有三个第一每个 Agent 的 prompt 可以写得非常聚焦准确率显著提升第二权限可以按 Agent 粒度下发查余额的 Agent 拿不到转账的 token第三出问题时能精确定位是哪个环节的哪个 Agent 出的错而不是面对一坨黑盒输出干瞪眼。我实测下来的经验是一个金融类工作流拆成 3 到 7 个 Agent 是比较舒服的区间。少于 3 个职责还是混的多于 7 个编排复杂度飙升调试成本比收益还高。具体怎么拆后面第 4 节会展开讲。2.2 Managed Agents API 解决的到底是哪个痛点自己搭 Agent 框架的人都经历过这个阶段本地跑得好好的一上服务器就各种超时、状态丢失、并发打架。Managed Agents API 的价值就在于它把会话状态管理、工具调用编排、重试与超时这些脏活接过去了你只需要定义这个 Agent 能干什么、能调哪些工具剩下的运行时它帮你扛。对金融场景来说这一点尤其关键。金融任务往往是有状态的——比如一个对账流程第一步拉取流水、第二步比对、第三步生成差异报告中间任何一步断了整个流程就得从头来。Managed API 帮你把会话上下文持久化断点续跑就变成了配置问题而不是架构问题。不过要注意托管不等于免责。API 帮你管的是运行时业务逻辑的正确性、数据的合规性、权限的边界还是得你自己兜。我见过有人以为用了托管 API 就万事大吉结果 Agent 把一个测试环境的接口调到了生产上这种锅 API 可不背。2.3 plugin 机制能力扩展的入口也是风险的高发区关键词里的 plugin 是这套体系里最灵活、也最容易出事的部分。plugin 本质上是给 Agent 挂载外部能力的插槽——你可以挂一个查数据库的 plugin、一个调内部风控服务的 plugin、一个生成报表的 plugin。挂载方式通常是通过配置文件声明Agent 在需要时按名字调用。灵活的另一面是风险。plugin 一旦挂上去Agent 就有了调用它的能力而 Agent 的判断是基于概率的它可能在你没预期的时候调用某个 plugin。所以在金融场景里我的原则是能不给的 plugin 坚决不给必须给的 plugin 一定要加参数校验和调用审计。一个查余额的 plugin就应该只接受账户 ID 这一个参数并且对返回结果做脱敏绝不能让它变成一个万能查询接口。下面这张表是我在实际项目里总结的 plugin 分类和对应的管控策略可以直接拿去对照你的项目plugin 类型典型能力风险等级管控策略只读查询类查余额、查流水、查汇率中参数白名单 结果脱敏 调用日志计算类利息计算、汇率换算、对账比对低输入输出格式校验写入类发起转账、修改状态、提交工单高二次确认 人工审批 幂等设计外部通信类发通知、调第三方接口高频率限制 内容审核 失败告警这张表的核心逻辑是风险等级决定管控强度而不是所有 plugin 一视同仁。把写入类 plugin 和查询类 plugin 用同一套管控要么是查询类被过度限制影响效率要么是写入类管控不足埋下隐患。3. 把 Claude Code 接进金融工作流环境、配置与第一个能跑的 Agent3.1 环境准备里那些文档不会告诉你的细节Claude Code 的安装本身不复杂但金融类项目往往跑在受控环境里这就带来一堆额外问题。我按踩坑顺序列一下第一网络出口。很多金融机构的内网是白名单制Claude Code 需要访问的域名得提前报备。这个环节最容易卡住因为报备流程往往比技术配置还慢建议项目启动第一天就去走流程。第二Node 版本。Claude Code 对 Node 版本有要求太老的版本会直接报错。我建议统一用 LTS 版本并且在项目根目录放一个.nvmrc把版本锁死避免我本地能跑、CI 上跑不了这种经典问题。第三凭证管理。API Key 绝对不能硬编码在代码里也不能提交到仓库。金融项目的做法通常是走内部的密钥管理服务本地开发用环境变量CI/CD 用注入的 secret。这一点没有商量余地。第四Windows 环境的坑。如果你在 Windows 上跑可能会遇到虚拟化平台相关的报错这通常是因为系统没启用对应的虚拟化功能。解决办法是在系统设置里开启然后重启。这个报错信息看起来吓人其实处理起来很简单但不知道的人能卡半天。3.2 一份可以直接抄的 Claude Code 配置下面这份配置是我在一个类似项目里实际用过的做了脱敏你可以按自己的环境改{ model: claude-sonnet-4-5, maxTokens: 8192, temperature: 0.2, tools: [ { name: query_account_balance, description: 查询指定账户的余额仅返回脱敏后的金额区间, inputSchema: { type: object, properties: { accountId: { type: string, pattern: ^ACC[0-9]{10}$ } }, required: [accountId] } } ], permissions: { allowFileWrite: false, allowShellExec: false, allowedDomains: [internal-api.example.com] } }这份配置里有几个点值得单独说。temperature设成 0.2 而不是 0是因为金融场景虽然要稳定但完全不保留一点灵活性会导致 Agent 在遇到边界情况时过于死板0.2 是我试下来在稳定性和适应性之间比较平衡的值。allowFileWrite和allowShellExec都关掉是因为金融 Agent 不应该有直接操作文件系统和执行命令的能力所有动作都应该通过受控的 tool 走。allowedDomains是网络层面的兜底防止 Agent 被诱导去访问不该访问的地址。3.3 第一个能跑的 Agent从查余额这种最小闭环开始新手最容易犯的错是一上来就搭一个复杂的多 Agent 系统结果调不通也不知道是哪一层的问题。我的建议是从最小闭环开始一个 Agent一个 tool一个明确的输入输出。比如先做一个查余额的 Agent。输入是账户 ID输出是脱敏后的余额区间。这个闭环跑通了你就验证了模型能正确理解意图、能正确调用 tool、能正确处理返回结果、能按格式输出。这四件事任何一件不通后面加再多 Agent 都是空中楼阁。跑通最小闭环之后再逐步加复杂度加第二个 tool、加第二个 Agent、加 Agent 之间的消息传递。每加一层都验证一次这样出问题时你永远知道是新加的那一层的问题而不是在一堆可能性里大海捞针。提示最小闭环阶段一定要把日志打全包括模型的原始输出、tool 的调用参数、tool 的返回结果。这些日志在后期调试时的价值远超你当时的想象。4. 多 Agent 协作的编排设计怎么拆、怎么连、怎么兜底4.1 按职责边界而不是功能点来拆 Agent拆 Agent 最常见的错误是按功能点拆——查余额一个、查流水一个、算利息一个。这样拆出来的 Agent 数量爆炸而且每个都太薄编排成本远大于收益。正确的拆法是按职责边界拆。什么是职责边界就是这个 Agent 对什么负责、它的输出对下游意味着什么。比如一个对账场景我会拆成三个 Agent数据采集 Agent负责从各个来源拉取数据输出标准化的数据结构。它不关心数据对不对只关心拉全了没有、格式对不对。比对分析 Agent负责拿标准化数据做比对输出差异列表。它不关心数据从哪来只关心比对逻辑对不对。报告生成 Agent负责把差异列表转成人能看懂的报告输出最终结果。它不关心比对怎么做的只关心表达清不清楚。这样拆的好处是每个 Agent 的输入输出都是明确的契约任何一个环节出问题你都能快速定位。而且这三个 Agent 可以独立测试、独立替换比如数据源换了只需要改数据采集 Agent另外两个不受影响。4.2 Agent 之间怎么传递消息结构化优先自由文本兜底Agent 之间传消息有两种方式一种是自由文本让下游 Agent 自己理解一种是结构化数据用固定的 schema。金融场景我强烈建议结构化优先。原因很直接自由文本传递会引入不确定性。上游 Agent 说余额大概是五万左右下游 Agent 理解成 50000 还是 55000这种模糊性在金融场景里是不可接受的。结构化传递就是定义好 schema上游必须按 schema 输出下游按 schema 解析中间没有解释空间。{ taskId: recon-20240115-001, source: data-collection-agent, status: success, payload: { records: [ { accountId: ACC0000000001, amount: 50000.00, currency: CNY, timestamp: 2024-01-15T10:30:00Z } ] }, errors: [] }这个 schema 里status字段是关键——它让下游 Agent 能明确知道上游是成功了还是失败了而不是靠猜。errors字段即使为空也要保留这样下游的处理逻辑可以统一不用写如果有 errors 字段就处理、没有就跳过这种分支。当然完全结构化也有代价——灵活性差。所以我的做法是核心数据走结构化辅助信息走自由文本。比如上面这个 schema 里可以加一个notes字段放自由文本用于传递一些非关键的上下文但下游 Agent 不能依赖这个字段做关键决策。4.3 失败重试与降级金融场景的兜底设计金融场景对失败的容忍度极低所以兜底设计必须做在前面。我的经验是分三层第一层是自动重试。对于网络抖动、临时超时这类瞬时故障自动重试 2 到 3 次每次间隔递增。这一层由 Managed API 或框架层处理业务代码不用管。第二层是降级处理。如果重试还是失败就要走降级逻辑。比如查余额失败是返回暂时无法查询还是返回上一次的缓存值这个决策取决于业务——如果是用户主动查询返回暂时无法查询更诚实如果是后台对账用缓存值继续跑、标记异常更合理。第三层是人工介入。对于关键流程的失败必须有人工介入的通道。比如转账失败不能就这么算了要触发告警、生成工单、通知相关人员。这一层的设计原则是宁可多打扰人也不能让问题静默。下面这张表是我总结的失败处理决策矩阵失败类型重试策略降级策略是否告警网络超时重试 3 次间隔 1s/2s/4s返回缓存值否接口返回错误码不重试标记异常继续流程是数据校验失败不重试中止流程是权限校验失败不重试中止流程是高优先级这张表的关键在于区分可恢复和不可恢复的失败。网络超时是可恢复的重试有意义权限校验失败是不可恢复的重试只会浪费时间还可能触发风控。5. 权限、审计与合规金融 Agent 不能绕开的三道关5.1 权限最小化每个 Agent 只拿它必须的那把钥匙权限最小化说起来简单做起来难。难在哪难在你很难提前知道一个 Agent 到底需要哪些权限。开发阶段为了方便往往给得比较宽上线前又不敢收怕收出问题。我的做法是从最严开始按需放开。新 Agent 上线时只给它跑通核心流程的最小权限然后观察日志看它实际调用了哪些 tool、访问了哪些数据。观察一到两周确认没有遗漏再固化权限。这个过程比先给宽再收紧要安全得多因为收紧权限时你永远不知道会不会有隐藏的调用路径被切断。具体到实现权限控制通常有三个层次Agent 级别这个 Agent 能调哪些 tool、参数级别调用 tool 时参数有什么限制、数据级别返回的数据怎么脱敏。三个层次都要做缺一不可。只做 Agent 级别Agent 可能用一个合法 tool 传非法参数只做参数级别Agent 可能用一个合法参数拿到不该拿的数据。5.2 审计日志出事时能还原现场的唯一依靠审计日志的价值平时体现不出来出事时是救命的。金融场景的审计日志我建议至少记录这几项谁哪个 Agent在什么时间、用什么参数、调用了什么 tool、得到了什么结果、耗时多久。这里有个细节容易被忽略日志要记录模型的原始输出而不只是解析后的结构化结果。因为出问题时你往往需要知道模型为什么这么决策而解析后的结果丢失了这个信息。原始输出可能很长但金融场景的存储成本相对于排查成本来说不值一提。另外日志的不可篡改性很重要。金融审计要求日志不能被事后修改所以日志应该写到只追加的存储里而不是普通文件。这一点在合规检查时经常被问到。5.3 数据脱敏Agent 看到的和用户看到的不该是同一份数据Agent 处理金融数据时很多字段是不需要看到明文的。比如账户 IDAgent 只需要一个能唯一标识的 token不需要知道真实账号比如金额很多场景下只需要区间不需要精确值。脱敏的时机很关键——在数据进入 Agent 之前脱敏而不是在 Agent 输出之后脱敏。因为一旦明文数据进了 Agent 的上下文它就可能出现在模型的输出里、日志里、甚至被诱导泄露。在入口脱敏是从根上杜绝这个问题。我常用的脱敏策略是格式保留脱敏保持数据的格式特征长度、类型但替换真实值。比如账号6222021234567890脱敏成6222****7890既保留了可识别性用于对账匹配又隐藏了敏感信息。6. 实操中真正会卡住你的那些坑6.1 模型自作聪明地扩展任务范围这是我在实际项目里遇到最多的坑。你让 Agent 查余额它查完余额顺手把最近的流水也拉出来了理由是用户可能想知道。在通用场景里这叫贴心在金融场景里这叫越权。解决办法有两个层面。Prompt 层面明确写清楚只做被要求的事不要扩展任务范围并且给出反例。架构层面用 tool 的权限限制兜底——即使 Agent 想查流水它没有查流水的 tool也就查不了。两层结合效果最好。6.2 上下文长度导致的记忆丢失多 Agent 协作时上下文会快速膨胀。一个跑了十几轮的流程上下文可能已经几万 token模型开始忘记前面的关键信息输出质量下降。我的应对策略是主动压缩上下文。每完成一个阶段就把该阶段的关键结论提取出来丢弃中间过程。比如数据采集阶段跑完只保留采集了 N 条记录、有 M 条异常这个结论具体的采集过程日志不进下一阶段的上下文。这样上下文始终保持在可控范围内。6.3 plugin 加载失败的排查链路plugin 加载失败是高频问题报错信息往往很模糊。我总结的排查顺序是看 plugin 声明文件路径对不对、格式对不对、必填字段有没有漏。看依赖plugin 依赖的库或服务是否可用。看权限运行 plugin 的进程有没有访问所需资源的权限。看版本plugin 版本和宿主版本是否兼容。看日志宿主加载 plugin 时的详细日志通常在 debug 级别。这个顺序的逻辑是从外到内、从简到繁。大部分问题在前两步就能定位不用一上来就怀疑版本兼容这种复杂问题。6.4 跨平台环境差异带来的玄学问题同一个项目在 Mac 上跑得好好的到 Windows 或 Linux 上就出问题。这类问题通常出在路径分隔符、换行符、环境变量、文件权限这几个地方。我的建议是开发环境尽量统一用容器或虚拟机把环境固化下来。如果实在统一不了就在代码里做兼容处理比如路径拼接一律用语言提供的 API 而不是手写字符串。这些看起来是小事但在多 Agent 协作的项目里一个环境差异可能导致某个 Agent 在某个平台上静默失败排查起来非常痛苦。7. 从能跑到好用性能与成本的平衡术7.1 模型选型不是越强越好而是越合适越好金融场景容易陷入用最强模型的思维定式。但实测下来不同任务用不同模型才是最优解。简单的格式转换、字段提取用小模型又快又便宜复杂的推理、多步决策才需要上大模型。我的做法是给每个 Agent 单独配模型。数据采集 Agent 用轻量模型比对分析 Agent 用中等模型报告生成 Agent 用中等模型。这样整体成本能降下来一大截而质量损失很小。关键是每个 Agent 的模型选择要基于实测而不是拍脑袋。7.2 缓存省钱的同时还能提速金融场景有很多重复查询——同一个账户在短时间内被查多次、同一份汇率被多个 Agent 引用。这些都可以缓存。缓存的粒度要设计好。太粗缓存命中率低太细缓存管理成本高。我的经验是按业务语义缓存比如某账户在某时刻的余额作为一个缓存单元而不是某次 API 调用的结果。这样即使 API 调用方式变了缓存依然有效。缓存的失效策略也很关键。金融数据的时效性要求高缓存时间不能太长。我通常设 5 到 15 分钟具体看业务对实时性的要求。对于汇率这类变化频繁的数据缓存时间要更短甚至不缓存。7.3 并发控制别让 Agent 把下游打挂多 Agent 并行跑的时候很容易出现下游服务被瞬间打满的情况。尤其是金融核心系统往往对并发有严格限制。解决办法是在 Agent 层做限流。每个 Agent 对下游的调用要有并发上限超过就排队。这个上限要根据下游的实际承载能力来定不能拍脑袋。我一般会先压测下游拿到它的实际 QPS 上限然后按 70% 设 Agent 的并发上限留 30% 的余量应对突发。8. 这套东西后续还能怎么长把基础的多 Agent 协作跑通之后有几个方向可以继续深挖。一个是引入更细的评估机制对每个 Agent 的输出做自动打分低分的自动触发人工复核这样能在保证质量的同时减少人工介入量。另一个是把 Agent 的决策过程可视化让业务人员能看懂 Agent 为什么这么决策这在金融合规场景里价值很大。还有一个我觉得很有潜力的方向是让 Agent 从历史工单里学习。金融业务里有大量人工处理的工单这些工单记录了什么情况、怎么处理、结果如何是天然的训练和评估数据。把这些数据用起来Agent 的处理能力会有质的提升。不过这些都是后话。我的建议是先把最小闭环跑稳把权限、审计、脱敏这三道关做扎实再考虑往上加东西。金融场景里稳比快重要对比多重要。我见过太多项目功能堆了一堆结果一个权限漏洞把整个项目拖下水。慢一点稳一点反而走得远。