1. 从financial-services这个标题说起一个被低估的Agent落地场景第一次看到financial-services这个项目标题加上 Claude、Managed Agents API、Cowork、plugin、agent 这一串关键词我脑子里第一反应不是又一个金融Demo而是——终于有人把 Agent 往真正需要它的地方搬了。金融服务业是那种流程极长、规则极多、容错极低的典型场景恰恰是通用聊天机器人最不擅长、而结构化 Agent 最能发挥价值的地方。这个项目本质上是在做一件事把 Claude 的 Managed Agents API 和 plugin 机制套进金融业务的真实工作流里让 Agent 不只是能聊天而是能干活、能留痕、能审计。我先把话说在前面这篇不是官方文档的复述。官方文档讲的是 API 怎么调、参数怎么填而我想聊的是为什么金融场景要这么设计、Managed Agents 和普通 Agent 到底差在哪、plugin 在 Cowork 这种协作环境里怎么落地、以及我自己在搭类似系统时踩过的那些坑。如果你正在做 Agent 开发、正在评估 Claude 能不能进你的业务系统、或者单纯想搞清楚agent 框架和skill 和 agent 的区别这类高频搜索词背后的真实含义那这篇应该能帮你省下不少试错时间。适合谁看三类人。第一类是有一定开发基础、想把 LLM 接进实际业务流程的工程师第二类是产品或者业务侧想理解 Agent 到底能替人做什么、边界在哪第三类是刚入门 Agent 开发、被各种名词绕晕的新手。我会尽量用生活化的类比把概念讲透同时把关键参数、配置、排查思路都给到让你看完能直接动手。2. 为什么金融场景非要用 Managed Agents 而不是普通 Agent2.1 普通 Agent 在金融场景的三个致命短板先说清楚一个前提什么叫普通 Agent。通常我们说的 Agent就是一个 LLM 加上一堆工具tool通过 ReAct 或者类似的循环让模型自己决定调哪个工具、传什么参数、拿到结果后继续推理。这套东西在写代码、查资料、做简单自动化时很好用但一进金融场景就露馅。第一个短板是状态不可控。普通 Agent 的对话历史、中间推理、工具调用结果往往散落在内存或者一个简单的 session 里。金融业务要求的是每一笔操作都能回溯——谁在什么时候、基于什么数据、做了什么决策、结果如何。普通 Agent 的临时状态根本撑不起这种审计要求。第二个短板是权限边界模糊。金融系统里一个查询余额的操作和一个发起转账的操作权限等级天差地别。普通 Agent 的工具集通常是全给模型自己判断该不该调。这在 Demo 里没问题在生产环境里就是事故隐患。第三个短板是长任务容易断。金融流程动辄涉及十几个步骤、跨多个系统、耗时几分钟甚至几小时。普通 Agent 一旦中间某步失败整个链路就崩了没有断点续跑、没有重试策略、没有人工介入的接口。Managed Agents API 解决的正是这三个问题。它把 Agent 的运行时托管起来状态、权限、生命周期都由平台管理开发者只需要定义 Agent 能做什么、在什么约束下做。这就像你自己在家做饭普通 Agent和去一家有完整厨房管理系统的餐厅后厨Managed Agents的区别——后者每一步都有记录、有分工、有卫生标准。2.2 Managed Agents 的核心抽象Agent、Session、Run 三层结构理解 Managed Agents关键是理解它的三层抽象。我用一个金融客服的例子来讲。Agent 层是人设和能力的定义。比如你定义一个贷款初审助手它知道贷款政策、能查征信、能算额度但不能直接放款。这一层是静态的定义一次可以复用。Session 层是一次完整的服务过程。一个客户来咨询贷款从打招呼到最终给出初审结论这是一个 Session。Session 里包含了这个客户的所有上下文、历史消息、中间产生的数据。Session 是可以持久化的客户明天再来可以接着上次的 Session 继续。Run 层是一次具体的执行。在同一个 Session 里客户问我能贷多少触发一次 Run客户又问利率是多少触发另一次 Run。每次 Run 都有独立的执行记录、工具调用日志、耗时统计。这三层结构对应到金融业务里就是岗位职责—客户档案—单次操作的映射。我实测下来这种分层最大的好处是审计粒度刚刚好你既能看整个客户的服务全貌也能精确到某一次操作调了哪个接口、返回了什么。2.3 和 Cowork、plugin 的关系协作与扩展Cowork 这个词在热词里出现我理解它指的是多 Agent 协作或者人机协作的工作空间。金融业务很少有单打独斗的场景一笔企业贷款要经过客户经理、风控、审批、放款多个环节每个环节可能对应一个专门的 Agent。Cowork 就是让这些 Agent 在同一个工作空间里协同共享上下文但各自守好自己的职责边界。plugin 则是扩展能力的入口。Managed Agents 本身提供的是框架具体能查什么数据、能调什么系统靠 plugin 来接入。金融场景里常见的 plugin 包括核心银行系统适配器、征信查询接口、反欺诈规则引擎、报表生成器等等。plugin 的设计要点是隔离——一个 plugin 出问题不能拖垮整个 Agent这跟微服务的思路是一致的。3. 核心细节拆解从 Agent 定义到 plugin 接入的完整链路3.1 Agent 定义阶段把岗位说明书翻译成配置定义 Agent 的时候最容易犯的错是把它当成写 Prompt。其实不是。Prompt 只是其中一部分更重要的是能力边界和约束条件。我一般会按这个结构来定义角色描述这个 Agent 是谁负责什么。比如你是某银行的企业贷款初审助手负责根据客户提交的材料做初步合规检查。可用工具清单明确列出它能调哪些 plugin每个 plugin 的用途和限制。注意这里要写清楚不能做什么比如你不能直接修改客户征信记录。输出格式约束金融场景对输出格式要求极严。初审结论必须是结构化的包含通过/拒绝/需人工复核三态以及理由字段。升级策略什么情况下必须转人工。比如金额超过某个阈值、或者遇到规则未覆盖的情况。这里有个经验约束要写在系统层不要指望模型自觉。我见过太多人把不要泄露客户信息写在 Prompt 里就完事了结果模型在特定诱导下还是会漏。正确做法是在 plugin 层做数据脱敏模型根本拿不到原始敏感数据。3.2 Session 管理状态持久化与上下文裁剪Session 管理的核心矛盾是上下文要全但 token 有限。金融业务的一个 Session 可能持续几天积累几十轮对话、上百次工具调用。全塞进上下文token 直接爆炸裁得太狠又丢失关键信息。我的做法是分层存储热数据最近几轮对话、当前任务相关的工具结果放在上下文里。温数据本次 Session 的关键结论、已确认的事实做成结构化摘要定期刷新进上下文。冷数据完整历史存在 Session 存储里需要时通过检索召回。这个思路跟人脑记忆很像——你记得昨天跟客户聊了什么结论但不记得每一句话的原话需要时翻记录。具体到参数我一般把上下文预算控制在模型上限的 60% 左右留 40% 给工具返回和推理。因为金融场景的工具返回往往很长比如一份征信报告预留不足会直接导致 Run 失败。3.3 plugin 接入隔离、幂等、可观测plugin 是 Agent 的手脚接得好不好直接决定系统稳不稳。三个原则必须守住。隔离每个 plugin 独立进程或独立容器一个挂了不影响其他。我踩过的坑是早期把所有 plugin 塞在一个进程里结果征信查询接口超时把整个 Agent 卡死了。幂等金融操作最怕重复执行。一个扣款plugin 如果因为重试被调了两次就是生产事故。所以每个 plugin 的写操作必须带幂等键服务端要能识别重复请求。可观测每次 plugin 调用都要有完整的日志——入参、出参、耗时、是否成功。这些日志不只是排障用更是审计证据。我一般会把 plugin 调用日志和 Run 记录关联起来做到从一次对话能追到一次数据库操作。下面是一个 plugin 定义的简化示例用伪代码表示结构plugin: name: credit_query description: 查询企业征信报告 input_schema: type: object properties: company_id: type: string description: 企业统一社会信用代码 required: [company_id] output_schema: type: object properties: report_id: {type: string} risk_level: {type: string, enum: [low, medium, high]} details: {type: array} constraints: rate_limit: 10/min timeout: 30s idempotent: true audit: log_input: true log_output: true mask_fields: [contact_phone, legal_person_id]注意mask_fields这一项它保证敏感字段在日志里被脱敏但 Agent 在运行时能拿到完整数据用于判断。这种运行时可见、日志里不可见的设计是金融场景的标配。4. 实操过程从零搭一个贷款初审 Agent4.1 环境准备与依赖安装假设你已经有了 Claude 的访问权限和 Managed Agents API 的 key。第一步是环境准备。我习惯用 Python 做原型因为生态成熟、调试方便。python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install anthropic requests pydantic这里插一句热词里有人搜claude code安装、ubuntu安装claude code、vscode配置claude code说明很多人在配置环节卡住。我的建议是先把命令行跑通再折腾 IDE 集成。命令行能跑通说明环境没问题IDE 集成只是锦上添花。如果遇到claude : 无法将claude项识别为 cmdlet这类报错八成是 PATH 没配好检查一下安装路径有没有加进环境变量。4.2 定义 Agent 与注册 plugin先定义 Agent 的配置。我用一个 Python 字典来组织实际项目里可以放 YAML 文件。agent_config { name: loan_preliminary_reviewer, model: claude-sonnet, system_prompt: 你是企业贷款初审助手。你的职责是 1. 核对客户提交材料的完整性 2. 调用征信查询工具获取企业信用状况 3. 根据内部规则给出初审结论通过/拒绝/需人工复核 4. 任何金额超过500万的申请必须标记为需人工复核 你不能直接做出放款决定也不能修改任何客户数据。, tools: [credit_query, document_checker, rule_engine], output_format: { type: object, properties: { conclusion: {enum: [approve, reject, manual_review]}, reason: {type: string}, risk_flags: {type: array} } } }然后注册 plugin。以征信查询为例核心是定义一个符合 schema 的函数并处理好错误。def credit_query(company_id: str) - dict: try: resp requests.post( https://internal-api/credit/query, json{company_id: company_id}, timeout30 ) resp.raise_for_status() data resp.json() return { report_id: data[report_id], risk_level: data[risk_level], details: data[details] } except requests.Timeout: return {error: timeout, retryable: True} except requests.HTTPError as e: return {error: fhttp_{e.response.status_code}, retryable: False}注意错误返回里带了retryable标记。这个设计很关键——Agent 拿到结果后能判断是该重试还是该放弃。金融接口经常有临时故障无脑重试可能造成重复扣款直接放弃又可能误判。让 Agent 根据retryable决定比在代码里写死重试逻辑灵活得多。4.3 跑通第一个 Run 并观察执行链路环境搭好后跑一个最简单的 Run 验证链路。session client.sessions.create(agent_idagent_config[name]) run client.runs.create( session_idsession.id, input客户提交了营业执照和近三年财报统一社会信用代码是91310000XXXXXXXXXX申请贷款300万请做初审。 ) print(run.output)第一次跑我建议你把日志级别开到最细观察 Agent 的每一步它先调了哪个工具、传了什么参数、拿到结果后怎么推理、最后怎么组织输出。这个过程能帮你发现很多设计问题。比如我第一次跑就发现Agent 在材料不全时不会主动追问而是直接给了需人工复核。这不是 bug是 Prompt 没写清楚材料不全时应先向客户索要。后来我在 system_prompt 里补了一条行为就对了。4.4 参数选择超时、重试、并发怎么定金融场景的参数不能拍脑袋得有依据。我列一下我常用的取值和理由。参数建议值理由plugin 超时30s内部系统 P99 响应一般在 5s 内30s 留足余量单 Run 最大工具调用次数20超过说明逻辑可能死循环需人工介入重试次数2配合指数退避避免雪崩并发 Run 数按业务量定金融业务通常不需要高并发稳定优先上下文预算模型上限 60%留 40% 给工具返回和推理这些值不是绝对的但背后的逻辑是通用的给足余量、设好上限、宁可慢不可错。金融场景里一次错误的快速响应比一次正确的慢响应危害大得多。5. 常见问题与排查技巧实录5.1 Agent 不调用工具直接编答案这是最高频的问题。表现是Agent 明明有征信查询工具却直接根据用户描述编了一个风险等级。原因通常是 Prompt 里没有强制必须先查证再下结论。解决办法有三层。第一层在 system_prompt 里明确写任何结论必须基于工具返回的数据不得基于用户描述推断。第二层在输出 schema 里加一个evidence字段要求 Agent 填写结论依据的工具调用 ID。第三层在应用层做校验如果evidence为空或者指向不存在的调用直接拒绝这次输出。三层叠加基本能杜绝。5.2 plugin 调用超时导致整个 Run 失败前面提过隔离的重要性但即使隔离了超时处理也得做对。我的做法是plugin 超时后返回一个结构化的错误Agent 拿到后可以选择重试、换工具、或者转人工。关键是不要让超时变成异常抛出异常会中断整个 Run而结构化错误让 Agent 有机会优雅处理。5.3 上下文爆炸导致 Run 失败长 Session 必然遇到这个问题。除了前面说的分层存储还有一个技巧是主动摘要。当上下文接近预算上限时触发一次摘要 Run把历史压缩成结构化要点替换掉原始消息。摘要的质量很关键我一般会要求摘要保留所有已确认的事实、所有未完成的待办、所有工具调用的结论丢弃寒暄、重复确认、中间推理过程。5.4 常见报错速查表报错关键词可能原因排查方向plugin failed to loadplugin 配置格式错误或依赖缺失检查 schema、依赖、路径agent execution terminated工具调用异常未捕获看 Run 日志最后一步rate limit exceeded调用频率超限检查 rate_limit 配置、加退避context length exceeded上下文超预算启用摘要、裁剪历史invalid output format输出不符合 schema检查 schema 与 Prompt 一致性这张表是我自己排障时总结的覆盖了八成以上的常见问题。遇到新问题先往这几个方向套能省不少时间。5.5 几个只有踩过才知道的坑第一个坑不要相信模型的我记得。长 Session 里模型经常声称根据之前的信息但那个信息可能已经被裁剪掉了。解决办法是关键事实必须显式地放在上下文里不能依赖模型记忆。第二个坑plugin 的返回要控制长度。征信报告动辄几千字全塞进上下文几次调用就爆了。我的做法是 plugin 返回时做一次预处理只返回 Agent 决策需要的字段详细数据存起来需要时再按 ID 召回。第三个坑测试环境的数据分布和生产不一样。测试时用的都是正常数据上线后遇到各种边界情况Agent 行为就飘了。建议测试阶段就构造一批脏数据——缺字段的、格式错的、逻辑矛盾的提前暴露问题。6. 这套架构还能怎么扩展跑通基础链路后我一般会往三个方向扩展。多 Agent 协作。把初审、风控、审批拆成独立 Agent通过 Cowork 机制协同。每个 Agent 有自己的职责边界和工具集通过消息传递协作。好处是职责清晰、便于独立迭代坏处是链路变长、调试变难。我的建议是先从单 Agent 跑通再逐步拆分。人工介入闭环。金融场景不可能全自动必须有人工兜底。设计上要留好转人工的接口Agent 判断需要人工时把当前上下文、已收集信息、待决问题打包推给人工坐席。人工处理完结果回写 SessionAgent 可以继续后续流程。规则引擎与 Agent 的配合。纯靠 LLM 做金融决策风险太高我的做法是规则引擎管硬约束Agent 管软判断。比如金额超 500 万必须人工这种硬规则交给规则引擎Agent 不参与材料是否充分这种需要理解的判断交给 Agent。两者结合既保证了合规底线又发挥了 LLM 的灵活性。最后分享一个我自己的体会做金融 Agent慢就是快。不要追求一步到位全自动先把一个环节做扎实把审计、回滚、人工介入这些不性感但关键的能力建好再逐步扩展。我见过太多项目死在Demo 很惊艳、上线就翻车上根子都是基础设施没打牢。这个financial-services项目的价值恰恰在于它把 Agent 放进了真实的约束里而不是又一个玩具。