1. Agent 不是员工是实习生Agent 能规划能调用工具能连续执行。这很强。也很危险。因为模型会犯错。它可能调错工具填错参数误解返回值重复调用接口甚至尝试执行高风险动作。所以生产级 Agent 的第一原则是模型负责“想”系统负责“准不准做”。2. Agent 最容易出问题的 6 个地方普通聊天机器人答错了最多是回答不准。Agent 答错了可能会真的调用系统。这就是风险升级。Agent 常见失控点与治理方式。这里最核心的是工具。模型输出的不是“结果”而是“行动意图”。一旦行动意图被系统执行就必须有门禁。3. 源码视角一次工具调用到底经过什么从表面看Agent 只是“调用一个函数”。从源码看它其实要经过一条完整链路。Agent 工具调用的源码主链路。这条链路有三个关键角色。第一模型只负责生成 AIMessage.tool_calls。它说“我想调这个工具参数是这些。”第二ToolNode 负责调度。它把工具调用包装成 ToolCallRequest再执行工具。第三BaseTool 负责校验和执行。它会处理输入、回调、异常和输出包装。源码级理解ToolNode 是调度层BaseTool 是执行层Middleware 是治理层。4. 工具权限不让模型随便调工具不是越多越好。一次性给模型太多工具模型会更容易选错。更重要的是不同工具风险不同。查天气和删除数据绝对不能一个权限级别。工具调用必须先经过 Tool Gate。生产环境里工具至少要分三级。低风险工具自动执行。比如查知识库、查天气、读取公开数据。中风险工具人工审批。比如写文件、发邮件、执行 SQL。高风险工具直接拒绝。比如转账、删除核心数据、修改权限、自动下单。不要把“不能下单”只写进 Prompt。真正的限制要写在工具门禁里。5. 参数校验让错误在执行前暴露模型可能会填错参数。比如金额应该是数字模型给了“很多钱”。比如 SQL 只能 SELECT模型给了 UPDATE。比如股票代码应该是 6 位模型给了公司简称。这类问题不能等业务接口报错。要在工具入口拦住。LangChain 的 BaseTool 有一个关键字段args_schema。它可以用 Pydantic 描述工具参数。工具执行前_parse_input() 会根据这个 schema 做校验。class QueryStockInput(BaseModel): symbol: str Field(description6 位股票代码) days: int Field(default20, ge1, le250) tool(args_schemaQueryStockInput) def query_stock(symbol: str, days: int 20) - str: 查询股票历史行情。 ...这个示例不是重点。重点是背后的链路参数先过 schema再进业务函数。参数错了应该返回可读错误让模型有机会修正而不是让整个 Agent 崩掉。6. BaseTool.run() 的源码分流Agent 工具执行时错误不是一个类型。参数错误、业务错误、系统错误要分开处理。BaseTool.run() 中的执行链路和异常分流。源码里BaseTool.run() 大致做了这些事。先启动回调。再把输入转成 args/kwargs。再调用 _parse_input() 校验参数。最后执行 _run()。执行过程中源码会分流处理 ValidationError、ToolException 和普通 Exception。handle_validation_error 控制参数校验错误怎么返回。handle_tool_error 控制工具主动抛出的 ToolException 怎么返回。普通未知异常默认继续抛出应该交给 middleware 或外层统一兜底。源码级结论BaseTool 不是只执行函数它还负责参数校验、回调记录、异常分流和输出包装。7. Middleware专门处理横切逻辑权限、限流、重试、缓存、降级不应该散落在每个工具函数里。这些是横切逻辑。LangChain 的 middleware 可以包住工具调用。wrap_tool_call 就是工具层最重要的钩子。wrap_tool_call 可以拦截、重试、降级和返回 ToolMessage。一个可靠的工具兜底逻辑应该是这样wrap_tool_call def safe_tool_call(request, handler): if not has_permission(request): return ToolMessage( content没有权限执行该工具。, tool_call_idrequest.tool_call[id], ) try: return handler(request) except TimeoutError: return ToolMessage( content工具超时请稍后重试。, tool_call_idrequest.tool_call[id], )注意这里的关键点返回的是 ToolMessage。它不是普通字符串。它带着 tool_call_id能让模型知道这是哪一次工具调用的结果。工具失败时不要只抛异常。能恢复的错误要转换成模型能理解的 ToolMessage。8. 高危动作必须人工审批自动化不是让模型无边界执行。凡是不可逆、涉及资金、涉及隐私、影响权限的动作都必须停下来。LangChain 的 Human-in-the-loop middleware 可以让工具调用在执行前暂停。Human-in-the-loop 让高危工具在执行前等待人类决策。它的核心不是“报错”。它是“暂停”。暂停后系统把工具名和参数展示给审核人。审核人可以批准、编辑、拒绝或者直接给模型反馈。这里必须配合 checkpointer。因为图执行被暂停后状态要保存下来后面才能恢复。高危动作的正确流程模型提出动作系统暂停人类确认图再继续。9. 生产级 Agent 的安全架构不要只在 LangChain 里面做安全。企业级系统要从入口、Agent、工具、业务系统、观测系统五层一起治理。入口层做认证、限流、黑白名单。Agent 层控制模型、工具、记忆和上下文。治理层做 middleware、Tool Gate、Guardrails、人工审批。业务层做二次校验。不要相信上游一定干净。观测层做 Trace、日志、告警和回放。最稳的设计是“双重校验”Agent 工具层校验一次业务系统再校验一次。10. 这几个字段必须记住写工具时重点看 BaseTool 的这几个字段。name工具名。模型靠它选择工具。名字要短要明确。description工具说明。模型靠它判断什么时候用。描述越模糊误调越多。args_schema参数 schema。它决定参数校验是否可靠。handle_validation_error参数校验失败时是否转成可读输出。handle_tool_error工具主动抛出 ToolException 时是否转成工具输出。return_direct是否让工具结果直接返回不再让模型二次加工。response_format工具结果是普通内容还是内容加 artifact。判断一个工具是否能上线不看 Demo 能不能跑。看它有没有 schema、权限、异常、审计和降级。11. 最小落地清单最后给一个生产检查清单。第一所有工具必须有明确 name、description 和 args_schema。第二工具必须按风险分级只读、可写、高危。第三高危工具必须走 Human-in-the-loop。第四所有工具调用必须记录 requestId、userId、tool_name、args、result、耗时、错误。第五所有可恢复错误都要返回 ToolMessage不能让 Agent 直接崩。第六工具要有超时、重试、限流和降级。第七业务系统要做二次校验不能把权限完全交给模型。第八线上要能回放一次完整 Agent 执行链路。12. 总结Agent 的价值是让模型能做事。Agent 的风险也是让模型能做事。所以真正的重点不是“让 Agent 更自由”。而是让 Agent 在可控边界内行动。一句话生产级 Agent 不是靠模型自觉而是靠系统设卡。内容来源Agent 不可靠怎么办工具权限、参数校验、异常兜底与源码解析功能变化与行业影响解析_热闻岛
Agent 不可靠怎么办？工具权限、参数校验、异常兜底与源码解析
发布时间：2026/6/15 7:49:07
1. Agent 不是员工是实习生Agent 能规划能调用工具能连续执行。这很强。也很危险。因为模型会犯错。它可能调错工具填错参数误解返回值重复调用接口甚至尝试执行高风险动作。所以生产级 Agent 的第一原则是模型负责“想”系统负责“准不准做”。2. Agent 最容易出问题的 6 个地方普通聊天机器人答错了最多是回答不准。Agent 答错了可能会真的调用系统。这就是风险升级。Agent 常见失控点与治理方式。这里最核心的是工具。模型输出的不是“结果”而是“行动意图”。一旦行动意图被系统执行就必须有门禁。3. 源码视角一次工具调用到底经过什么从表面看Agent 只是“调用一个函数”。从源码看它其实要经过一条完整链路。Agent 工具调用的源码主链路。这条链路有三个关键角色。第一模型只负责生成 AIMessage.tool_calls。它说“我想调这个工具参数是这些。”第二ToolNode 负责调度。它把工具调用包装成 ToolCallRequest再执行工具。第三BaseTool 负责校验和执行。它会处理输入、回调、异常和输出包装。源码级理解ToolNode 是调度层BaseTool 是执行层Middleware 是治理层。4. 工具权限不让模型随便调工具不是越多越好。一次性给模型太多工具模型会更容易选错。更重要的是不同工具风险不同。查天气和删除数据绝对不能一个权限级别。工具调用必须先经过 Tool Gate。生产环境里工具至少要分三级。低风险工具自动执行。比如查知识库、查天气、读取公开数据。中风险工具人工审批。比如写文件、发邮件、执行 SQL。高风险工具直接拒绝。比如转账、删除核心数据、修改权限、自动下单。不要把“不能下单”只写进 Prompt。真正的限制要写在工具门禁里。5. 参数校验让错误在执行前暴露模型可能会填错参数。比如金额应该是数字模型给了“很多钱”。比如 SQL 只能 SELECT模型给了 UPDATE。比如股票代码应该是 6 位模型给了公司简称。这类问题不能等业务接口报错。要在工具入口拦住。LangChain 的 BaseTool 有一个关键字段args_schema。它可以用 Pydantic 描述工具参数。工具执行前_parse_input() 会根据这个 schema 做校验。class QueryStockInput(BaseModel): symbol: str Field(description6 位股票代码) days: int Field(default20, ge1, le250) tool(args_schemaQueryStockInput) def query_stock(symbol: str, days: int 20) - str: 查询股票历史行情。 ...这个示例不是重点。重点是背后的链路参数先过 schema再进业务函数。参数错了应该返回可读错误让模型有机会修正而不是让整个 Agent 崩掉。6. BaseTool.run() 的源码分流Agent 工具执行时错误不是一个类型。参数错误、业务错误、系统错误要分开处理。BaseTool.run() 中的执行链路和异常分流。源码里BaseTool.run() 大致做了这些事。先启动回调。再把输入转成 args/kwargs。再调用 _parse_input() 校验参数。最后执行 _run()。执行过程中源码会分流处理 ValidationError、ToolException 和普通 Exception。handle_validation_error 控制参数校验错误怎么返回。handle_tool_error 控制工具主动抛出的 ToolException 怎么返回。普通未知异常默认继续抛出应该交给 middleware 或外层统一兜底。源码级结论BaseTool 不是只执行函数它还负责参数校验、回调记录、异常分流和输出包装。7. Middleware专门处理横切逻辑权限、限流、重试、缓存、降级不应该散落在每个工具函数里。这些是横切逻辑。LangChain 的 middleware 可以包住工具调用。wrap_tool_call 就是工具层最重要的钩子。wrap_tool_call 可以拦截、重试、降级和返回 ToolMessage。一个可靠的工具兜底逻辑应该是这样wrap_tool_call def safe_tool_call(request, handler): if not has_permission(request): return ToolMessage( content没有权限执行该工具。, tool_call_idrequest.tool_call[id], ) try: return handler(request) except TimeoutError: return ToolMessage( content工具超时请稍后重试。, tool_call_idrequest.tool_call[id], )注意这里的关键点返回的是 ToolMessage。它不是普通字符串。它带着 tool_call_id能让模型知道这是哪一次工具调用的结果。工具失败时不要只抛异常。能恢复的错误要转换成模型能理解的 ToolMessage。8. 高危动作必须人工审批自动化不是让模型无边界执行。凡是不可逆、涉及资金、涉及隐私、影响权限的动作都必须停下来。LangChain 的 Human-in-the-loop middleware 可以让工具调用在执行前暂停。Human-in-the-loop 让高危工具在执行前等待人类决策。它的核心不是“报错”。它是“暂停”。暂停后系统把工具名和参数展示给审核人。审核人可以批准、编辑、拒绝或者直接给模型反馈。这里必须配合 checkpointer。因为图执行被暂停后状态要保存下来后面才能恢复。高危动作的正确流程模型提出动作系统暂停人类确认图再继续。9. 生产级 Agent 的安全架构不要只在 LangChain 里面做安全。企业级系统要从入口、Agent、工具、业务系统、观测系统五层一起治理。入口层做认证、限流、黑白名单。Agent 层控制模型、工具、记忆和上下文。治理层做 middleware、Tool Gate、Guardrails、人工审批。业务层做二次校验。不要相信上游一定干净。观测层做 Trace、日志、告警和回放。最稳的设计是“双重校验”Agent 工具层校验一次业务系统再校验一次。10. 这几个字段必须记住写工具时重点看 BaseTool 的这几个字段。name工具名。模型靠它选择工具。名字要短要明确。description工具说明。模型靠它判断什么时候用。描述越模糊误调越多。args_schema参数 schema。它决定参数校验是否可靠。handle_validation_error参数校验失败时是否转成可读输出。handle_tool_error工具主动抛出 ToolException 时是否转成工具输出。return_direct是否让工具结果直接返回不再让模型二次加工。response_format工具结果是普通内容还是内容加 artifact。判断一个工具是否能上线不看 Demo 能不能跑。看它有没有 schema、权限、异常、审计和降级。11. 最小落地清单最后给一个生产检查清单。第一所有工具必须有明确 name、description 和 args_schema。第二工具必须按风险分级只读、可写、高危。第三高危工具必须走 Human-in-the-loop。第四所有工具调用必须记录 requestId、userId、tool_name、args、result、耗时、错误。第五所有可恢复错误都要返回 ToolMessage不能让 Agent 直接崩。第六工具要有超时、重试、限流和降级。第七业务系统要做二次校验不能把权限完全交给模型。第八线上要能回放一次完整 Agent 执行链路。12. 总结Agent 的价值是让模型能做事。Agent 的风险也是让模型能做事。所以真正的重点不是“让 Agent 更自由”。而是让 Agent 在可控边界内行动。一句话生产级 Agent 不是靠模型自觉而是靠系统设卡。内容来源Agent 不可靠怎么办工具权限、参数校验、异常兜底与源码解析功能变化与行业影响解析_热闻岛
