一、引言
LLM 接收上下文并预测下一个 Token,它擅长理解自然语言,却不会因为生成了下面这段内容,就真的调用天气服务:
1{ 2 "name": "get_weather", 3 "arguments": { 4 "city": "上海" 5 } 6} 7
这只是模型输出的数据。真正发起网络请求、访问数据库或修改业务状态的主体,仍然是应用程序。
因此,一个完整的 Agent 至少包含两类组件:
1┌──────────────────── 概率世界 ────────────────────┐ 2│ │ 3│ 用户输入 ──> Prompt/上下文 ──> LLM │ 4│ │ │ 5│ │ 生成调用意图 │ 6│ ▼ │ 7│ tool_call(name, arguments) │ 8└──────────────────────────┬────────────────────────┘ 9 │ 协议边界 10 ▼ 11┌──────────────────── 确定性世界 ──────────────────┐ 12│ │ 13│ Schema 校验 ──> 权限检查 ──> 工具执行 │ 14│ │ │ │ 15│ └──失败信息 └──执行结果 │ 16│ \ / │ 17│ └──> 写回模型上下文 ───────────────┘ 18│ │ 19└───────────────────────────────────────────────────┘ 20
Function Calling 是一个多阶段过程:应用向模型提供工具定义,模型返回工具调用请求,应用执行工具,再把执行结果交还模型。Function Calling 是模型与程序之间的调用协议,不是模型获得了直接执行代码的权限。理解这一点,后续的安全控制、错误处理和状态管理才有正确的落点。
二、六项底层能力如何组成一个闭环
1 Agent 与程序世界的交互管道 2 3 ┌─────────────── 输入侧 ───────────────┐ 4 │ │ 5 │ Prompt │ 6 │ 规定目标、上下文、决策规则和边界 │ 7 │ │ │ 8 │ ▼ │ 9 │ Tool Definition + JSON Schema │ 10 │ 定义有哪些工具,以及参数契约 │ 11 └──────────────────┬───────────────────┘ 12 ▼ 13 Function/Tool Call 14 模型提出结构化调用 15 │ 16 ▼ 17 ┌────────────── 运行时边界 ─────────────┐ 18 │ 解析 → Schema 校验 → 鉴权 → 执行 │ 19 │ │ │ 20 │ ┌──────────┴──────────┐ │ 21 │ ▼ ▼ │ 22 │ 成功结果 失败结果 │ 23 └──────────┬─────────────────────┬──────┘ 24 │ │ 25 ▼ ▼ 26 结构化输出约束 分类重试/降级 27 │ │ 28 └──────────┬──────────┘ 29 ▼ 30 最终回答 31
各部分分别解决不同问题:
| 能力 | 解决的问题 | 不能解决的问题 |
|---|---|---|
| Prompt 设计 | 模型应该做什么、何时调用工具 | 无法替代程序鉴权与运行时校验 |
| JSON Schema | 参数有哪些、类型和结构是什么 | 无法证明参数符合业务语义 |
| Function Calling | 让模型生成机器可处理的函数调用请求 | 不会自动执行本地函数 |
| Tool Calling | 把函数、自带工具、MCP 等能力纳入调用循环 | 不天然保证工具可信或无副作用 |
| 输出约束 | 让最终输出符合可解析结构 | 不保证字段内容在事实层面正确 |
| 失败重试 | 处理暂时性故障或可修正输出 | 无法修复权限不足和永久业务错误 |
三、Prompt 设计:把它当作决策说明书,而不是咒语
Prompt 在 Agent 中主要负责两件事:说明任务目标、规定模型如何选择和使用工具。一个适合工具调用的 Prompt 可以拆成以下结构:
1<role> 2你是订单售后助手。 3</role> 4 5<objective> 6帮助用户查询订单状态或提交退款申请。 7</objective> 8 9<tool_policy> 101. 查询实时订单状态时必须调用 order_get。 112. 未获得用户明确确认时,不得调用 refund_create。 123. 缺少 order_id 时先向用户询问,不得猜测。 134. 工具失败时,根据错误码解释原因,不得编造执行结果。 14</tool_policy> 15 16<output_policy> 17调用写操作前先总结即将执行的动作。 18最终回答需要区分“已执行”和“建议执行”。 19</output_policy> 20 21<untrusted_input> 22{{user_input}} 23</untrusted_input> 24
1.有效 Prompt 的四个组成部分
- 目标
目标要描述结果,而不是堆叠人格形容词。
较弱的写法:
1你是一个专业、智能、严谨的订单助手。 2
更可执行的写法:
1你负责查询订单状态,并在满足退款条件且用户明确确认后提交退款。 2
- 工具选择规则
当多个工具语义接近时,模型容易选错。Prompt 和工具描述应说明:什么时候调用、什么时候不调用、调用前需要哪些信息、工具是否产生副作用、多个工具有何边界。
- 缺失信息处理
如果模型缺少参数,它可能选择猜测。应明确要求:缺少必填参数时向用户询问,不得从无关上下文推断。
需要注意:这只能降低猜测概率,程序仍需执行 Schema 和业务校验。
- 失败行为
不要只写“如果失败,请重试”。应告诉模型根据错误类型做出什么决策:
1VALIDATION_ERROR:修正参数后最多重试一次。 2NOT_FOUND:向用户确认标识,不自动重试。 3PERMISSION_DENIED:停止调用并说明所需权限。 4RATE_LIMITED:遵循 retry_after,等待后重试。 5
2.Prompt 版本必须接受评测
Prompt 并不是一次写完的静态文案。生产环境至少要测试:
- 是否调用了正确工具;
- 是否遗漏必填参数;
- 是否在不需要时调用工具;
- 是否在写操作前取得确认;
- 工具失败后是否编造成功结果;
- 恶意工具返回是否改变系统指令;
- 模型或 Prompt 版本变化是否导致行为回归。
因此,Prompt 的可靠性应该由评测数据证明,而不是由“看起来写得很完整”来判断。
四、JSON Schema:Agent 与程序之间的数据合同
JSON 只是一种数据格式,JSON Schema 才负责描述数据结构和验证规则。
使用 JSON Schema 可以定义:
1{ 2 "type": "object", 3 "properties": { 4 "order_id": { 5 "type": "string", 6 "description": "订单唯一标识,例如 ord_20261027_001" 7 }, 8 "amount": { 9 "type": "number", 10 "exclusiveMinimum": 0, 11 "description": "退款金额,单位由 currency 指定" 12 }, 13 "currency": { 14 "type": "string", 15 "enum": ["CNY", "USD"] 16 }, 17 "reason": { 18 "type": "string", 19 "minLength": 1, 20 "maxLength": 200 21 } 22 }, 23 "required": ["order_id", "amount", "currency", "reason"], 24 "additionalProperties": false 25} 26
- properties 不代表必填,必须配合required进行使用校验。
- additionalProperties: false 用于封闭对象边界,如果不禁止额外字段,模型可能生成未定义参数。对于工具参数,封闭对象通常比开放对象更安全。
- enum 比自然语言约束更稳定,用于把实例值限制在给定集合中。
Schema 校验和业务校验必须分层:
1模型参数 2 │ 3 ▼ 4[语法解析] 5 │ JSON 是否能解析? 6 ▼ 7[Schema 校验] 8 │ 类型、必填项、枚举、结构是否合法? 9 ▼ 10[业务校验] 11 │ 订单存在吗?金额可退吗?状态允许吗? 12 ▼ 13[授权校验] 14 │ 当前用户可以操作这个订单吗? 15 ▼ 16[执行] 17
Schema 是第一道门,不是最后一道门。
五、Function Calling:模型提出调用,程序掌握执行权
Function Calling 的典型流程可以概括为五步:
1(1) 应用把工具定义发给模型 2 │ 3 ▼ 4(2) 模型返回 function/tool call 5 │ 6 ▼ 7(3) 应用验证参数并执行函数 8 │ 9 ▼ 10(4) 应用把执行结果关联到 call_id 11 │ 12 ▼ 13(5) 模型生成最终答案或继续调用工具 14
一个工具的核心结构大致如下:
1{ 2 "name": "order_get", 3 "description": "查询当前用户拥有的单个订单。仅在需要实时订单状态时调用。", 4 "input_schema": { 5 "type": "object", 6 "properties": { 7 "order_id": { 8 "type": "string", 9 "description": "订单唯一标识,不要使用商品编号或支付流水号" 10 } 11 }, 12 "required": ["order_id"], 13 "additionalProperties": false 14 } 15} 16
工具描述也是模型输入的一部分,建议详细说明工具用途、适用时机、参数含义和限制,并指出描述质量是影响工具调用效果的重要因素。
一个合格的工具定义应让模型知道:工具做什么?什么时候用?什么时候不用?每个参数代表什么?调用有什么副作用或限制?
例如,下面的描述过于模糊:
1创建退款。 2
更清晰的版本是:
1为当前用户拥有且处于可退款状态的订单创建退款。 2仅在用户明确确认退款金额和原因后调用。 3该工具会产生不可忽略的业务副作用。 4查询退款资格时不要调用,应使用 refund_eligibility_get。 5
Schema 决定参数形状,描述决定模型如何理解工具语义,两者缺一不可。
六、Tool Calling:Function Calling 的上位概念
在许多 API 和框架中,Function Calling 与 Tool Calling 会被混用。工程上可以这样区分:
1Tool Calling 2├── Function Tool 3│ └── 由应用实现的本地函数或远程 API 包装 4├── Built-in Tool 5│ ├── Web Search 6│ ├── Code Execution 7│ └── File Search 8├── MCP Tool 9│ └── 由 MCP Server 暴露的外部能力 10└── UI / Computer Tool 11 └── 浏览器、桌面或界面操作 12
Function Calling 是 Tool Calling 的一种常见形式。前者强调“以函数和参数的形式表达调用”,后者强调“模型可以使用外部能力”。
工具按执行位置还可以分为以下几类:
| 类型 | 执行方 | 应用责任 |
|---|---|---|
| 客户端工具 | 业务应用 | 参数校验、鉴权、执行、结果回传 |
| 服务端工具 | 模型服务商 | 应用配置工具,服务商负责执行 |
| MCP/远程工具 | MCP 服务或第三方服务 | 需要处理信任、权限和结果隔离 |
客户端工具返回 tool_use 后由应用执行,再以关联 ID 返回 tool_result ;服务端工具由平台执行。
Tool Calling 是状态机,不是一次请求。一个 Agent 可能:
- 不调用工具,直接回答;
- 调用一个工具后回答;
- 并行调用多个独立工具;
- 根据第一个结果决定第二个工具;
- 工具失败后修正参数再调用;
- 达到循环上限后停止。
因此,Agent Runtime 更接近有限状态机:
1 ┌──────────────┐ 2 │ START │ 3 └──────┬───────┘ 4 ▼ 5 ┌──────────────┐ 6 ┌────>│ MODEL_CALL │<────────────┐ 7 │ └───┬──────┬───┘ │ 8 │ │ │ │ 9 │ final │ │ tool_call │ 10 │ ▼ ▼ │ 11 │ ┌──────┐ ┌──────────────┐ │ 12 │ │ DONE │ │ VALIDATE │ │ 13 │ └──────┘ └──┬────────┬──┘ │ 14 │ │ │ │ 15 │ valid│ │error │ 16 │ ▼ ▼ │ 17 │ ┌─────────┐ ┌───────┐ │ 18 │ │ EXECUTE │ │ REPAIR│─┘ 19 │ └────┬────┘ └───────┘ 20 │ │ 21 │ ┌───────┴────────┐ 22 │ │ │ 23 │ success failure 24 │ │ │ 25 └──────────┴──── result ────┘ 26
运行时必须设置:
- 最大模型轮次;
- 最大工具调用数;
- 单工具超时;
- 总任务截止时间;
- 最大参数修复次数;
- 最大暂时性错误重试次数;
- 取消信号。
否则,“继续调用直到完成”可能变成无限循环和失控账单。
七、输出约束:合法 JSON、Schema 合法与内容正确是三件事
结构化输出存在三个可靠性层级:
1Level 1:自然语言要求 2“请返回 JSON” 3 │ 4 ▼ 5可能附带 Markdown、解释文字或语法错误 6 7Level 2:JSON Mode 8保证输出可解析为 JSON 9 │ 10 ▼ 11字段仍可能缺失、类型错误、枚举越界 12 13Level 3:Structured Outputs 14输出满足指定 Schema 15 │ 16 ▼ 17字段内容仍可能存在事实或业务错误 18
Function Calling 与 Structured Output都可能使用 JSON Schema,前者约束“模型要程序做什么”,后者约束“模型最终对程序说什么”。
即使输出完全符合 Schema,它仍可能是错的,Schema 只能证明类型格式,不能证明真实存在,所以业务代码不能把“Schema 校验通过”当成“事实核验通过”。
另外,结构化输出之外还存在控制信号:
- 安全拒答;
- 输出达到 Token 上限;
- 请求被取消;
- 内容过滤;
- 工具调用未完成;
- 流式输出中断。
消费者不应只做:
1JSON.parse(response) 2
而应先判断:
1响应状态 2├── completed → 解析并校验 3├── refusal → 进入拒答流程 4├── incomplete → 判断是否可续写或重试 5├── tool_call → 执行工具循环 6└── transport_error → 按网络策略处理 7
八、失败重试:先分类,再决定是否重试
| 错误 | 是否重试 | 处理方式 |
|---|---|---|
| 网络超时 | 是 | 指数退避,受总截止时间限制 |
| HTTP 429 | 是 | 优先遵循 Retry-After |
| HTTP 5xx | 视情况 | 有上限地重试 |
| JSON 解析失败 | 是 | 把解析错误反馈给模型,少量修复 |
| Schema 校验失败 | 是 | 返回字段级错误,少量修复 |
| 参数缺失 | 视情况 | 可从用户获得时先询问用户 |
| 资源不存在 | 否 | 确认标识或结束 |
| 权限不足 | 否 | 说明权限需求并审计 |
| 业务规则拒绝 | 否 | 返回可执行的替代方案 |
| 写操作结果未知 | 谨慎 | 先查询状态,禁止直接重复写入 |
写操作必须具备幂等性。读取天气失败后重试,最坏情况通常是多一次查询。创建退款、发送邮件或扣款重试,可能产生重复副作用。
写工具应接收幂等键:
1{ 2 "order_id": "ord_123", 3 "amount": 100, 4 "currency": "CNY", 5 "idempotency_key": "agent_run_abc:refund:ord_123" 6} 7
服务端保存幂等键与执行结果:
1首次请求 2idempotency_key 不存在 3 │ 4 ▼ 5执行写操作 ──> 保存结果 ──> 返回成功 6 7重复请求 8idempotency_key 已存在 9 │ 10 ▼ 11不重复执行 ──> 返回首次结果 12
幂等键应该由可信应用生成,而不是让模型自由生成。否则模型可能在每次重试时产生新键,失去去重作用。
另外,“结果未知”比“明确失败”更危险。假设退款接口在执行后连接超时:
1Agent ──创建退款──> 退款服务 2Agent <──连接超时──X 3
此时存在两种可能:服务端没有执行退款、服务端已执行退款,但响应丢失。如果立即重试,可能重复退款。正确流程是:
1写操作超时 2 │ 3 ▼ 4使用幂等键或业务流水号查询状态 5 │ 6 ├── 已成功 → 返回原结果 7 ├── 明确失败 → 评估是否重试 8 └── 状态未知 → 人工介入或异步对账 9
因此,Agent Runtime 需要区分 FAILED 和 UNKNOWN 。把两者都映射为异常,会掩盖最棘手的一类一致性问题。
九、一个可落地的 Agent 工具调用循环
1type ToolError = { 2 code: string; 3 message: string; 4 retryable: boolean; 5}; 6 7async function runAgent(userInput: string) { 8 const messages = [ 9 { role: "user", content: userInput } 10 ]; 11 12 const maxTurns = 8; 13 14 for (let turn = 0; turn < maxTurns; turn++) { 15 const response = await callModel({ 16 messages, 17 tools: toolDefinitions 18 }); 19 20 if (response.type === "final") { 21 return validateFinalOutput(response.output); 22 } 23 24 if (response.type !== "tool_calls") { 25 throw new Error(`Unsupported response type: ${response.type}`); 26 } 27 28 messages.push(response.assistantMessage); 29 30 for (const call of response.calls) { 31 const tool = toolRegistry.get(call.name); 32 33 if (!tool) { 34 messages.push(toolErrorResult(call.id, { 35 code: "UNKNOWN_TOOL", 36 message: `Tool ${call.name} is not available`, 37 retryable: false 38 })); 39 continue; 40 } 41 42 const validation = tool.schema.safeParse(call.arguments); 43 44 if (!validation.success) { 45 messages.push(toolErrorResult(call.id, { 46 code: "VALIDATION_ERROR", 47 message: formatValidationError(validation.error), 48 retryable: true 49 })); 50 continue; 51 } 52 53 const authorization = await authorize( 54 currentUser, 55 tool, 56 validation.data 57 ); 58 59 if (!authorization.allowed) { 60 messages.push(toolErrorResult(call.id, { 61 code: "PERMISSION_DENIED", 62 message: authorization.reason, 63 retryable: false 64 })); 65 continue; 66 } 67 68 try { 69 const result = await executeWithPolicy(tool, validation.data, { 70 timeoutMs: 5000, 71 idempotencyKey: buildIdempotencyKey(call, currentUser) 72 }); 73 74 messages.push(toolSuccessResult(call.id, result)); 75 } catch (error) { 76 messages.push( 77 toolErrorResult(call.id, classifyToolError(error)) 78 ); 79 } 80 } 81 } 82 83 throw new Error("Agent exceeded maximum turns"); 84} 85
- 模型只负责提出调用;
- 工具名必须经过允许列表匹配;
- 参数必须经过本地 Schema 校验;
- 鉴权发生在工具执行前;
- 写操作由应用注入幂等键;
- 错误经过分类后再反馈给模型;
- 循环存在明确上限;
- 最终输出仍需独立校验。
十、小结
Agent 连接程序世界的过程,本质上是一套跨越概率系统与确定性系统的协议。
其中:
- Prompt 表达目标和决策规则;
- JSON Schema 定义参数与输出的数据边界;
- Function Calling 让模型提出结构化调用请求;
- Tool Calling 把外部能力纳入多轮执行循环;
- Structured Outputs 让最终结果可被程序稳定消费;
- 校验、鉴权、幂等、错误分类和有限重试共同守住运行时边界。
生产级 Agent 不应依赖模型“自觉地做对”。应用必须掌握执行权,用代码检查模型请求,用最小权限约束工具,用结构化错误帮助模型恢复,并在无法确认执行结果时停止自动动作。