1. 金融场景下的 Agent 工程化落地从“能跑”到“敢用”的完整拆解金融行业对自动化的态度一直很拧巴一边是大量重复性极高的流程——对账、报表生成、合规检查、客户尽调、交易异常排查另一边是对准确性、可追溯性、权限隔离近乎偏执的要求。过去几年 RPA 在这块吃得开但 RPA 的硬伤也很明显它只能照着写死的路径走界面一变就崩遇到非结构化数据基本歇菜。Agent 的出现让很多人看到了新可能但真正把 Agent 放进金融生产环境的人都知道从 demo 到上线之间隔着的不是一层窗户纸而是一整套工程体系。我过去一年多的时间基本都泡在金融场景的 Agent 落地项目里踩过的坑从“模型幻觉导致对账差异”到“工具调用权限失控触发风控告警”都有。这篇内容围绕financial-services这个方向把 Agent 在金融业务中的设计思路、核心实现、实操细节和排查经验完整梳理一遍。适合正在做 Agent 开发、准备把 Agent 引入金融业务流程、或者单纯想搞清楚“金融级 Agent 到底和普通 Agent 差在哪”的读者。不管你是刚接触 Agent 框架的新手还是已经写过几个 tool calling 的老手应该都能从里面找到能直接抄作业的部分。2. 金融 Agent 的整体设计与选型思路2.1 为什么金融场景不能直接套用通用 Agent 架构通用 Agent 的典型架构是“LLM 工具调用 记忆 规划”这套东西在写代码、查资料、做客服的场景里跑得挺顺但搬到金融业务里会立刻暴露三个致命问题。第一个是确定性缺失。金融业务里大量操作是有明确规则的比如“单笔超过 50 万的转账必须双人复核”“客户风险等级为 C4 以上不得推荐 R4 以上产品”。通用 Agent 依赖 LLM 自主决策同一个输入两次运行可能给出不同路径这在金融场景里是不可接受的。我的做法是把这类硬规则从 Agent 的决策空间里剥离出来做成独立的规则引擎或校验层Agent 只负责“理解意图 编排流程”规则判断交给确定性代码。第二个是审计断链。金融行业受监管约束任何影响客户资产或数据的操作都必须留痕且要能还原“谁在什么时间基于什么信息做了什么决定”。通用 Agent 的思考过程是黑盒中间步骤散落在日志里根本没法作为审计证据。所以金融 Agent 必须强制记录完整的决策链路输入是什么、检索了哪些数据、调用了哪些工具、每步的中间结果、最终输出是什么全部结构化落库。第三个是权限边界模糊。通用 Agent 往往给一个 API Key 就让它随便调但金融系统里不同角色能访问的数据和能执行的操作差异巨大。柜员能查客户基本信息但不能改风险评级风控能冻结账户但不能发起转账。Agent 必须继承调用者的权限上下文而不是用一个超级账号横冲直撞。2.2 分层架构把 Agent 拆成“大脑、手脚、护栏”三层我在实际项目里用的架构是三层分离这个设计参考了多个金融客户的合规要求后逐步收敛出来的。决策层大脑由 LLM 承担负责意图理解、任务拆解、工具选择。这一层用 Claude 系列模型比较多原因是它在长上下文和指令遵循上表现稳定尤其是涉及多步骤金融流程时不容易“跳步”。模型本身不直接接触生产数据只接收经过脱敏和裁剪的上下文。执行层手脚是一组封装好的工具函数每个工具对应一个原子操作比如query_account_balance、check_risk_level、generate_report。工具内部做参数校验、权限检查、幂等控制对外只暴露严格的输入输出 schema。Agent 只能通过工具操作数据不能直接连数据库。护栏层Guardrails独立于 Agent 运行包含规则引擎、敏感操作拦截、输出合规检查。任何工具调用前先过护栏调用后再过一遍输出检查。护栏层是纯代码实现不依赖 LLM保证确定性。这个分层的好处是模型升级或更换不影响业务逻辑工具变更不影响决策策略护栏规则调整不需要重新训练或调 prompt。每一层可以独立测试、独立部署、独立回滚。2.3 模型选型为什么在金融场景里我更倾向 Claude热词里 Claude 相关的内容占了很大比重这不是偶然。金融场景对模型的要求和通用场景有明显差异我总结下来主要是四点长上下文稳定性、指令遵循严格度、工具调用准确率、拒答合理性。长上下文这块金融文档动辄几十页的合同、年报、尽调材料需要模型在长文本里精准定位关键条款。实测下来 Claude 在 100K 以上上下文里的信息召回明显更稳不容易出现“读了后面忘了前面”的情况。指令遵循方面金融 prompt 里经常有“必须”“禁止”“仅当”这类强约束词Claude 对这类约束的遵守度更高不会自作主张扩展任务范围。工具调用准确率直接决定 Agent 能不能用。我做过一组对比测试同样是 20 个金融工具的调用场景Claude 在参数填充正确率和工具选择准确率上都领先尤其是涉及金额、日期、账户号这类格式敏感参数时出错率明显更低。拒答合理性也很关键金融场景里有些请求是必须拒绝的比如“帮我绕过风控审批”模型要能识别并拒绝而不是想办法满足。当然模型选型不是绝对的具体还要看你的部署条件、成本预算、数据合规要求。如果必须私有化部署开源模型经过金融领域微调后也能用但工程投入会大很多。3. 核心模块的细节解析与实操要点3.1 工具层设计每个工具都是一个“微型金融系统”工具层是金融 Agent 最容易出问题的地方因为它是 Agent 和真实业务系统之间的唯一通道。我见过太多项目把工具写成简单的 API wrapper结果上线后各种边界情况炸锅。一个合格的金融工具应该包含这几个部分输入校验、权限检查、业务逻辑、幂等控制、审计日志、输出脱敏。以query_account_balance为例输入校验要检查账户号格式、查询时间范围是否合法权限检查要确认调用者是否有权查看该账户业务逻辑才是真正查余额幂等控制保证重复调用不会产生副作用审计日志记录谁查了什么输出脱敏根据调用者角色决定返回完整账号还是掩码账号。# 工具定义示例伪代码展示结构 class QueryAccountBalanceTool: name query_account_balance description 查询指定账户在指定时间点的余额仅限有权限的用户调用 input_schema { type: object, properties: { account_id: {type: string, pattern: ^[0-9]{16,19}$}, query_date: {type: string, format: date}, currency: {type: string, enum: [CNY, USD, EUR]} }, required: [account_id, query_date] } def execute(self, params, context): # 1. 权限检查 if not context.user.has_permission(account:read, params[account_id]): raise PermissionDenied(无权查询该账户) # 2. 幂等检查查询类操作天然幂等但记录调用 audit_log.record(context.user, self.name, params) # 3. 业务逻辑 balance core_banking.query_balance( params[account_id], params[query_date], params.get(currency, CNY) ) # 4. 输出脱敏 if not context.user.has_permission(account:full_view): balance[account_id] mask_account(params[account_id]) return balance工具描述description的写法也有讲究。金融工具的描述要精确到“什么时候该用、什么时候不该用”而不是简单说“查询余额”。比如要写明“本工具仅用于查询历史余额实时余额请使用 query_realtime_balance”否则 Agent 很容易选错工具。3.2 记忆管理金融 Agent 的“记忆”不是越多越好Agent 记忆这块热词里讨论很多但金融场景的记忆管理和通用场景逻辑完全不同。通用场景追求“记住更多上下文”金融场景追求“记住该记的忘掉该忘的”。我把金融 Agent 的记忆分成三类。会话记忆只在单次对话内有效对话结束即销毁用于维持多轮交互的连贯性。任务记忆在单个任务生命周期内有效比如一个对账任务从发起到完成中间产生的临时数据存在任务记忆里任务结束归档。长期记忆是跨会话的但只存两类东西用户偏好比如某客户经理习惯用 Excel 导出和业务事实比如某账户的固定标签且必须加密存储、定期审计。关键原则是客户敏感数据绝不进长期记忆。账号、金额、身份证号这些信息只在会话或任务记忆里短暂存在用完即焚。我见过有项目把客户信息存进向量数据库做“长期记忆”结果被安全审计一票否决。记忆的检索也要做权限过滤。同一个 Agent 服务多个用户时A 用户的记忆不能被 B 用户检索到。实现上是在向量检索时强制加user_id过滤条件而不是靠 LLM 自觉。3.3 护栏层实现规则引擎 输出检查双保险护栏层是金融 Agent 区别于通用 Agent 的核心。我的实现是两道关卡。第一道调用前拦截。Agent 决定调用某个工具时先过规则引擎。规则引擎里配置的是硬性约束比如“转账金额超过阈值必须人工复核”“非工作时间禁止执行交易类操作”“同一账户 5 分钟内查询超过 10 次触发限流”。这些规则用配置化方式管理业务人员可以自己维护不需要改代码。第二道输出后检查。Agent 生成最终回复前过一遍输出合规检查。检查内容包括是否包含未脱敏的敏感信息、是否给出了超出权限的建议、是否包含承诺性表述金融行业对“保本”“稳赚”这类词极其敏感。检查不通过的直接拦截返回标准话术。# 护栏层配置示例 guardrail_rules [ { id: high_value_transfer, trigger: {tool: initiate_transfer, condition: amount 500000}, action: require_approval, approver_role: senior_manager }, { id: off_hours_trading, trigger: {tool: execute_trade, condition: time not in trading_hours}, action: block, message: 非交易时段无法执行交易操作 }, { id: sensitive_output, trigger: {output_check: True}, action: filter, patterns: [保本, 稳赚, 无风险, 保证收益] } ]护栏层的规则要定期 review因为业务规则会变。我建议每季度和合规部门过一遍规则库该加的加该删的删。4. 完整实操流程从零搭建一个金融 Agent 服务4.1 环境准备与依赖安装先说明一下这里以 Claude 系列模型为例如果你用的是其他模型把对应的 SDK 换掉即可。环境准备这块我踩过的坑主要集中在版本兼容和网络配置上。基础环境建议用 Python 3.10 以上Node.js 18 以上如果你要用 Claude Code 这类工具辅助开发。依赖管理用 poetry 或 pipenv别用裸 pip金融项目依赖多版本冲突会让你怀疑人生。# 创建项目环境 python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate # 安装核心依赖 pip install anthropic0.25.0 pip install pydantic2.0 pip install fastapi uvicorn pip install sqlalchemy alembic pip install redis pip install structlog如果你在 Windows 上开发可能会遇到一些环境问题。比如 Claude 的桌面版在某些 Windows 版本上需要开启虚拟机平台功能这个在“启用或关闭 Windows 功能”里勾选即可。另外命令行工具如果提示“无法将 claude 项识别为 cmdlet”说明环境变量没配好把安装路径加到 PATH 里就行。VS Code 里配置 Claude Code 的话装好插件后在设置里填 API Key 和模型版本注意别把 Key 硬编码在配置文件里用环境变量或者密钥管理服务。4.2 项目结构设计金融 Agent 项目的目录结构要清晰因为后面审计和交接的时候会经常翻代码。我用的结构是这样的financial-agent/ ├── config/ │ ├── settings.yaml # 环境配置 │ ├── guardrails.yaml # 护栏规则 │ └── tools_schema.json # 工具 schema ├── src/ │ ├── agent/ │ │ ├── core.py # Agent 主循环 │ │ ├── planner.py # 任务规划 │ │ └── memory.py # 记忆管理 │ ├── tools/ │ │ ├── base.py # 工具基类 │ │ ├── account.py # 账户相关工具 │ │ ├── transaction.py # 交易相关工具 │ │ └── report.py # 报表相关工具 │ ├── guardrails/ │ │ ├── engine.py # 规则引擎 │ │ └── output_check.py # 输出检查 │ ├── audit/ │ │ └── logger.py # 审计日志 │ └── api/ │ └── routes.py # 对外接口 ├── tests/ │ ├── unit/ │ └── integration/ ├── migrations/ # 数据库迁移 └── pyproject.toml这个结构的关键是把 agent、tools、guardrails、audit 分开每块可以独立测试。tools 目录下按业务域分文件别把所有工具塞一个文件里后面维护会疯。4.3 Agent 主循环实现Agent 主循环是整个系统的核心我把它拆成“接收输入 → 构建上下文 → 调用模型 → 解析工具调用 → 执行工具 → 判断是否继续 → 生成输出”这几个步骤。class FinancialAgent: def __init__(self, model_client, tool_registry, guardrail_engine, memory): self.model model_client self.tools tool_registry self.guardrails guardrail_engine self.memory memory self.max_iterations 10 # 防止无限循环 async def run(self, user_input, context): # 1. 构建初始消息 messages self._build_messages(user_input, context) # 2. 主循环 for i in range(self.max_iterations): # 调用模型 response await self.model.chat( messagesmessages, toolsself.tools.get_schemas(), systemself._build_system_prompt(context) ) # 3. 检查是否有工具调用 if not response.tool_calls: # 没有工具调用说明模型要给出最终回复 final_output response.content break # 4. 执行工具调用 for tool_call in response.tool_calls: # 护栏检查 guard_result self.guardrails.check_tool_call( tool_call, context ) if guard_result.blocked: tool_result {error: guard_result.message} else: tool_result await self.tools.execute( tool_call.name, tool_call.arguments, context ) # 记录审计日志 audit_log.record_tool_call( context, tool_call, tool_result ) # 把结果加回消息 messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(tool_result) }) else: # 超过最大迭代次数 final_output 任务处理超时请稍后重试或联系人工客服 # 5. 输出合规检查 final_output self.guardrails.check_output(final_output, context) # 6. 更新记忆 self.memory.update(context.session_id, user_input, final_output) return final_output这里有几个细节值得说。max_iterations一定要设我见过 Agent 陷入循环疯狂调用工具把 API 额度烧光的案例。工具执行结果要序列化成 JSON 再塞回消息别直接传对象。审计日志要在工具执行前后都记录方便排查。4.4 工具注册与 schema 生成工具注册我用的是装饰器模式写起来简洁schema 自动生成。# 工具注册 tool_registry ToolRegistry() tool_registry.register class QueryAccountBalance(BaseTool): name query_account_balance description 查询指定账户在指定日期的余额。 使用场景客户询问账户余额、对账时需要核对余额。 不适用场景查询实时余额请用 query_realtime_balance 查询交易明细请用 query_transactions。 class Input(BaseModel): account_id: str Field(..., patternr^[0-9]{16,19}$) query_date: str Field(..., description格式 YYYY-MM-DD) currency: str Field(CNY, enum[CNY, USD, EUR]) async def execute(self, params: Input, context) - dict: # 实现逻辑 ...工具描述我特意写了“使用场景”和“不适用场景”这是从实际踩坑里总结出来的。早期工具描述写得太简单Agent 经常选错工具加上这两段后准确率明显提升。4.5 审计日志与可追溯性审计日志是金融 Agent 的命脉我用的方案是结构化日志 数据库双写。结构化日志用于实时监控和告警数据库用于事后审计和追溯。class AuditLogger: def record_tool_call(self, context, tool_call, result): record { timestamp: datetime.utcnow().isoformat(), trace_id: context.trace_id, session_id: context.session_id, user_id: context.user.id, user_role: context.user.role, tool_name: tool_call.name, tool_args: self._sanitize(tool_call.arguments), tool_result_summary: self._summarize(result), guardrail_status: context.guardrail_status, duration_ms: context.last_tool_duration } # 写结构化日志 logger.info(tool_call, **record) # 写数据库 self.db.insert(audit_log, record) def _sanitize(self, args): # 脱敏处理账号只留后四位 if account_id in args: args[account_id] mask_account(args[account_id]) return args审计日志的保留期限要符合监管要求一般至少 5 年。存储上做冷热分离近 3 个月的放热存储方便查询更早的归档到冷存储。5. 常见问题与排查技巧实录5.1 工具调用类问题排查工具调用是出问题最多的地方我整理了一个速查表。问题现象可能原因排查方法解决方案Agent 不调用工具直接编造答案工具描述不清晰或 system prompt 未强调必须用工具检查工具 description 和 system prompt在 system prompt 里明确“所有数据必须通过工具获取禁止编造”调用工具但参数错误schema 定义不严谨或模型理解偏差打印模型返回的 tool_call 参数收紧 schema 约束加 pattern 和 enum在 description 里给参数示例工具调用陷入循环工具返回结果模型无法理解反复重试查看审计日志里的工具调用序列统一工具返回格式设置 max_iterations在工具返回里加明确的成功/失败标识工具执行超时底层系统响应慢或网络问题检查工具执行耗时分布加超时控制对慢查询做缓存必要时异步化权限检查误拦截权限上下文传递丢失检查 context 在各层的传递确保 context 从入口到工具执行全程透传我印象最深的一次是 Agent 反复调用同一个查询工具查了十几次还在查。排查发现是工具返回的 JSON 里有个字段名和模型预期的不一致模型以为查询失败了就重试。后来统一了所有工具的返回格式问题解决。5.2 模型输出类问题排查模型输出这块的典型问题是幻觉和格式不符。幻觉在金融场景里特别危险比如模型编造一个不存在的账户号或者利率。我的应对策略是强制引用要求模型在输出里标注每个数据的来源工具没有来源的数据不允许出现在最终回复里。实现上是在 system prompt 里加约束同时在输出检查里做校验。格式不符主要是模型不按要求的 JSON 或 Markdown 格式输出。解决办法是用 structured output 或者 function calling 的强制模式别指望模型自觉。如果模型不支持强制格式就在输出检查里做格式修复修复不了就重试。还有一个常见问题是模型“过度帮助”用户问 A模型把 B、C、D 都答了。金融场景里这可能导致信息泄露比如用户问自己的账户模型把关联账户也列出来了。解决办法是在 system prompt 里明确“只回答用户明确询问的内容不主动扩展”。5.3 性能与成本优化金融 Agent 的响应时间直接影响用户体验我做过一些优化效果比较明显。工具结果缓存查询类工具的结果可以缓存比如账户基本信息 5 分钟内不变缓存能减少 60% 以上的重复查询。缓存 key 要包含用户权限避免越权读取。上下文裁剪金融对话往往很长但模型不需要看到全部历史。我的做法是只保留最近 5 轮对话 任务相关的关键信息其余压缩成摘要。这样能显著降低 token 消耗。模型分级不是所有任务都需要用最强的模型。意图识别、简单查询用轻量模型复杂规划和推理用强模型。我实测下来成本能降 40% 左右效果基本无损。并行工具调用如果多个工具调用之间没有依赖关系并行执行。比如同时查账户余额和交易明细串行要 2 秒并行只要 1.2 秒。5.4 安全与合规避坑这块是金融 Agent 的重中之重我列几条血泪教训。永远不要相信模型的权限判断。模型可能会说“根据我的判断您有权查看这个账户”但实际权限必须由代码层校验。模型只负责发起请求权限判断在工具层做。敏感操作必须二次确认。转账、修改客户信息、冻结账户这类操作Agent 不能直接执行必须生成待确认工单由人工确认后执行。我见过 Agent 直接执行转账导致的事故虽然金额不大但性质严重。输出内容必须过合规检查。金融行业对措辞极其敏感“预期收益”和“保证收益”是两个性质完全不同的词。输出检查要覆盖这类敏感词宁可误拦不可放过。日志脱敏要彻底。审计日志里不能出现完整账号、身份证号、手机号。我用的规则是账号保留后四位身份证保留前六后四手机号保留前三后四。日志存储要加密访问要审批。定期做红队测试。找安全团队模拟恶意用户攻击 Agent比如诱导它泄露其他客户信息、绕过风控规则。我每个季度做一次每次都能发现新问题。6. 一些实操心得和后续扩展方向做金融 Agent 这一年多最大的体会是工程能力比模型能力更重要。模型再强工具层写得不严谨、护栏层有漏洞、审计链不完整照样上不了生产。反过来模型能力中等但工程扎实反而能跑得稳。另一个体会是别追求全自动。金融业务里很多环节人工介入是必要的Agent 的价值是把人从重复劳动里解放出来而不是完全取代人。我现在做的项目基本都是“Agent 处理 80% 标准场景 人工处理 20% 异常场景”的模式落地阻力小很多。后续扩展方向我看好两个。一个是多 Agent 协作比如一个 Agent 负责客户交互一个负责风控审核一个负责合规检查各司其职互相制衡。另一个是Agent 可观测性把 Agent 的决策过程可视化让业务人员能看懂 Agent 为什么这么做这对建立信任很关键。最后分享一个小技巧金融 Agent 的 prompt 里加一句“如果你不确定请明确说不知道并建议转人工”能大幅降低幻觉风险。模型在金融场景里“承认不知道”比“编一个答案”有价值得多。
