---
tags: [AI, agent, tool-calling]
阶段: 08-Agent与工程化
难度: ★★☆
created: 2026-10-18
related: "[[Agent工作流与编排]], [[结构化输出]], [[MCP协议]], [[Harness与Loop工程]]"
---

# AI-Agent与工具调用

## 定义

**Agent**（智能体）是由语言模型、工具集合、循环与终止条件四部分构成的计算系统：模型在每一轮读取由历史消息渲染出的上下文，输出一个动作；动作要么是对某个工具的调用，要么是最终回答；运行时执行调用并把结果作为新消息追加回上下文，直到终止条件成立。

形式化地，记环境状态为 $s_t$，则

$$
s_0=(q,\varnothing),\qquad
a_t=\pi_\theta\big(c(s_t)\big),\qquad
r_t=\mathrm{exec}(a_t),\qquad
s_{t+1}=s_t\oplus(a_t,r_t),
$$

循环在 $\tau(s_t)=\text{stop}$ 时结束，其中 $\tau$ 由最终回答、步数上限、预算上限共同判定。状态、动作与终止谓词的含义如下。

| 符号 | 含义 |
|---|---|
| $q$ | 用户任务描述，循环的初始输入 |
| $s_t$ | 第 $t$ 步结束后的状态：任务、已产生的动作与全部工具结果 |
| $c(\cdot)$ | 把状态渲染为消息序列的函数，包含系统提示、工具描述与历史 |
| $\pi_\theta$ | 策略，由参数为 $\theta$ 的模型与系统提示共同确定 |
| $\mathcal{T}$ | 工具集合，$N=\lvert\mathcal{T}\rvert$ 为工具数量 |
| $\mathcal{X}_k$ | 工具 $k$ 的参数空间，由一段 JSON Schema 定义 |
| $a_t$ | 第 $t$ 步的动作，取值于 $\bigcup_k\{(k,x):x\in\mathcal{X}_k\}\cup\mathcal{A}_{\text{final}}$ |
| $r_t$ | 工具返回的结果文本，或错误对象 |
| $\oplus$ | 把动作与结果追加为消息的操作 |
| $T$ | 最大步数，循环的硬上界 |
| $\tau$ | 终止谓词，$\tau(s_t)\in\{\text{continue},\text{stop}\}$ |

术语逐项说明。**工具**（tool）是一个具名函数，附有三项元数据：自然语言描述、参数模式、副作用级别；函数本身在模型之外执行。**工具调用**（tool call）是模型输出的结构化对象，至少包含调用标识、工具名与参数对象。**工具结果**（tool result）是运行时把函数返回值或错误序列化后的文本，必须与调用标识一一对应。**轨迹**（trajectory）是整条消息序列，用于回放、评估与故障归因。**轮**（turn）指一次模型输出的范围，一轮可以包含多个并行调用；**步**（step）指一次模型调用，因此一轮对应一步，但可能对应多个工具执行。**JSON Schema** 是描述 JSON 文档结构的声明式规范，本篇使用其 `type`、`properties`、`required`、`enum`、`additionalProperties` 等关键字。**JSON-RPC 2.0** 是以 `jsonrpc`、`id`、`method`、`params` 与 `result` 或 `error` 表达请求与响应的协议，MCP 在其上定义工具语义。

四要素缺一不可：只有模型与工具而没有循环，等价于一次函数调用；有循环而没有终止条件，系统不保证停机；有终止条件而没有工具，循环无法获得新信息。

## 为什么重要

模型的参数在训练结束后冻结，因此单次调用只能完成「输入到输出」的映射。需要实时数据、需要执行副作用、需要验证中间结果的任务，都无法由一次映射完成。工具把外部能力引入上下文，循环把单步映射扩展为多步过程，两者结合才使任务成功率不再受限于单次生成。

循环放大每一步的可靠性差异。设第 $t$ 步正确的概率为 $p_t$，各步近似独立，则完成全部 $n$ 步的概率为

$$
P_{\text{done}}=\prod_{t=1}^{n}p_t\approx p^{n}.
$$

取 $p=0.95$、$n=8$，$P_{\text{done}}=0.95^{8}\approx0.663$；取 $p=0.99$，$P_{\text{done}}\approx0.923$。单步正确率提高 4 个百分点，端到端成功率提高约 26 个百分点。这条计算解释了工程实践中的两个取舍：把任务拆成更少、更可靠的步骤；为每一步加入校验与重试，而不是只提高最终答案的质量。

循环也引入三类新成本。其一是上下文成本，工具结果不断追加，输入 token 随步数增长，推导见下一节。其二是权限成本，模型生成的参数直接进入真实系统，错误参数可能造成不可逆后果。其三是可观测性成本，失败可能发生在选择、参数、执行、回填任一环节，缺少轨迹就无法归因。

在本库中的位置：[[结构化输出]] 给出参数模式的构造与校验方法，本篇把该模式用于工具签名；[[MCP协议]] 把本篇的工具注册表与消息格式标准化为跨进程接口；[[Agent工作流与编排]] 讨论多个循环如何组织、路由与回退；[[Harness与Loop工程]] 讨论运行时如何管理上下文、预算与恢复。对应学习目标中的「能复现」与「会评估」：能实现一个带校验、超时、错误回填与步数上限的循环，能用调用正确率、参数正确率与端到端成功率三项指标度量它。

## 原理与推导

### 1 循环的状态转移与终止

把一次 Agent 执行写成状态转移序列 $s_0\to s_1\to\cdots$。每次转移由三步组成：渲染 $c(s_t)$、采样 $a_t\sim\pi_\theta(\cdot\mid c(s_t))$、执行 $r_t=\mathrm{exec}(a_t)$。由于采样带有温度，同一 $s_t$ 可能产生不同 $a_t$，因此轨迹是随机的；运行时的职责是把随机性约束在可接受范围内。

终止谓词至少要覆盖四种情况：

1. 模型输出不含工具调用，即 $a_t\in\mathcal{A}_{\text{final}}$。
2. 步数达到 $T$，无论是否完成。
3. 预算耗尽，包括累计 token、累计费用与墙钟时间。
4. 检测到重复动作，即连续两步的 $(k,x)$ 完全相同且结果未变化。

只实现第一种会导致不收敛：模型可能反复调用同一工具。只实现第二种会浪费预算：任务在第 2 步已完成，循环仍跑到第 $T$ 步。四种条件应同时存在，并各自记录触发原因，否则失败归因只能得到「超时」这一无信息量的结论。

上下文的增长可以精确估计。设系统提示与工具描述合计 $C_0$ token，每个工具结果平均 $m$ token，忽略模型输出的增长，则第 $T$ 步请求的输入长度为

$$
T_{\text{in}}(T)=T\,C_0+m\frac{T(T-1)}{2}.
$$

取 $C_0=1000$、$m=500$、$T=10$，得 $10000+22500=32500$ token，是单次调用 $1000$ token 的 32.5 倍，且增长为二次。这条式子直接给出两个设计约束：单个工具结果必须设上限，长任务必须引入摘要或外部存储，后者见 [[Agent记忆与上下文]]。

### 2 工具调用的消息协议

一次完整的工具调用包含四个阶段：声明工具、模型返回调用、运行时执行、结果回填。以下以 Chat Completions 风格的字段名为例，其他协议族的字段对照见表。

阶段一，请求中声明工具。`tools` 数组的每一项包含类型、名称、描述与参数模式：

```json
{
  "model": "example-model",
  "messages": [{"role": "user", "content": "查 10 月 25 日北京到上海的航班"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "search_flights",
      "description": "查询指定日期两城市间的航班，返回航班号、起飞时间与含税价格",
      "parameters": {
        "type": "object",
        "properties": {
          "origin": {"type": "string", "description": "出发城市中文名"},
          "destination": {"type": "string", "description": "到达城市中文名"},
          "date": {"type": "string", "description": "出发日期，格式 YYYY-MM-DD"}
        },
        "required": ["origin", "destination", "date"],
        "additionalProperties": false
      }
    }
  }],
  "tool_choice": "auto"
}
```

阶段二，模型返回调用。`finish_reason` 为 `tool_calls`，消息中 `tool_calls` 数组给出调用对象；注意 `arguments` 是一个 JSON 字符串而不是对象，模型在触达 `max_tokens` 时可能输出被截断的字符串，因此必须先确认 `finish_reason`，再解析：

```json
{
  "choices": [{
    "finish_reason": "tool_calls",
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {
          "name": "search_flights",
          "arguments": "{\"origin\":\"北京\",\"destination\":\"上海\",\"date\":\"2026-10-25\"}"
        }
      }]
    }
  }]
}
```

阶段三，运行时执行：按 `name` 查注册表，用 `parameters` 校验 `arguments`，调用函数并捕获异常。阶段四，把结果以工具消息回填，`tool_call_id` 必须等于调用对象的 `id`：

```json
{"role": "tool", "tool_call_id": "call_1",
 "content": "[{\"flight\":\"CA1831\",\"depart\":\"12:40\",\"price_cny\":980}]"}
```

一次调用的时序如下。

```mermaid
sequenceDiagram
    participant R as 运行时
    participant M as 模型
    participant T as 工具
    R->>M: 系统提示 + 用户消息 + 工具描述
    M-->>R: tool_calls（id, name, arguments）
    R->>R: 校验参数、检查权限
    R->>T: 执行函数（超时上限）
    T-->>R: 返回值或异常
    R->>M: role=tool（tool_call_id 对应）+ 下一次请求
    M-->>R: 最终回答或新的 tool_calls
```

三类协议族的字段对照如下。字段名不同，语义一致：声明、调用、结果、结束标志。

| 环节 | Chat Completions 风格 | Messages 风格（内容块） | MCP |
|---|---|---|---|
| 工具声明 | `tools[].function.parameters` | `tools[].input_schema` | `tools/list` 返回 `inputSchema` |
| 模型输出 | `tool_calls[]`，`arguments` 为 JSON 字符串 | `content[]` 中 `type` 为 `tool_use` 的块，`input` 为对象 | 客户端主动发 `tools/call` |
| 结果回填 | `role` 为 `tool`，附 `tool_call_id` | `user` 消息中的 `tool_result` 块，附 `tool_use_id` | `result.content[]` 与 `isError` |
| 结束标志 | `finish_reason` 为 `tool_calls` | `stop_reason` 为 `tool_use` | JSON-RPC 响应到达 |

消息层的五条规则需要逐条实现，任何一条缺失都会导致下一轮请求被服务端拒绝或循环读到错误状态。

1. 调用标识与结果标识一一对应。模型发出 $k$ 个调用，运行时必须在下一轮之前回填恰好 $k$ 个结果；缺失、重复、错配都是协议错误。
2. 参数先校验后执行。模型输出的参数是待验证的输入，不是可信数据；类型、范围、枚举、必填字段都必须在运行时检查。
3. 工具输出按数据对待。结果文本可能包含「忽略以上指令」之类的句子，这些句子不具有指令效力，不得进入系统提示，也不得改变权限判定。
4. 执行失败也必须回填。异常、超时、权限拒绝都要序列化为工具结果，附错误码与是否可重试，让模型有机会改变策略。
5. 并行调用必须一次回填全部结果。先在运行时侧全部执行完毕，再按调用顺序构造消息，避免模型在只看到部分结果时继续推理。

### 3 参数模式的写法

参数模式的根节点应为 `object`，属性逐个声明类型与描述，并对每个字段给出取值范围或枚举。常用关键字及其对校验行为的影响如下。

| 关键字 | 作用 | 忽略后的后果 |
|---|---|---|
| `type` | 限定 JSON 类型 | 字符串被当作数字传入，函数内部抛类型错误 |
| `properties` | 声明字段及其子模式 | 嵌套对象无法校验 |
| `required` | 声明必填字段 | 模型省略字段，函数收到缺失参数 |
| `additionalProperties` | 是否允许未声明字段 | 模型臆造字段，被函数 `**kwargs` 静默吞掉 |
| `enum` | 限定取值集合 | 单位、语言、排序方向等被写成同义词 |
| `minimum`、`maximum` | 数值边界 | 负数页码、超大 `top_k` 直达下游 |
| `pattern` | 字符串正则约束 | 日期、路径、标识符格式不受控 |
| `items` | 数组元素模式 | 数组元素类型混杂 |

四条写法约定能显著降低参数错误率。第一，单位写进字段名，例如 `timeout_ms`、`price_cny`，避免模型在描述与字段之间推断单位。第二，可选字段用 `["string", "null"]` 显式表达，而不是依赖 `default`；默认值由运行时在调用前补齐，模型省略字段属于合法输入，函数签名中的默认值不能替代校验。第三，嵌套深度控制在两层以内，深层嵌套的字段错误难以被模型定位与修正。第四，`description` 写明何时应当使用该工具、何时不应使用，这一段文字是模型选择工具的主要依据，见第 8 节。

模式与实现的一致性必须由构造保证。可行的做法是从函数签名生成模式，使二者共享同一份定义；不可行的做法是分别手写模式与函数，再用测试对齐。后者的典型失效是模式声明 `count` 为 `integer` 而函数签名是 `count: str`，校验通过、调用抛错，错误被当作内部错误重试，浪费预算且不改变结果。

部分厂商提供强约束模式，要求所有属性都列入 `required`、`additionalProperties` 为 `false`，并只支持 JSON Schema 的一个子集。跨厂商移植工具时，应先用最小模式验证目标实现是否接受，而不是假定 2020-12 草案全量可用。约束解码的机制见 [[结构化输出]]。

### 4 并行工具调用

当一轮中的多个调用之间没有数据依赖时，模型可以在一次输出中给出多个调用对象，运行时并发执行。设第 $i$ 个调用的耗时为 $\tau_i$，调度开销为 $\delta$，则串行与并行的墙钟时间分别为

$$
L_{\text{serial}}=\sum_{i=1}^{k}\tau_i,\qquad
L_{\text{parallel}}=\max_{i}\tau_i+\delta.
$$

取 $\tau=(0.3,0.4,0.5)$ 秒、$\delta=0.05$ 秒，串行 $1.2$ 秒，并行 $0.55$ 秒。收益随 $k$ 增大，但受三个约束限制：并发上限、下游系统的速率限制、单个工具的内部串行度。

并行的边界由依赖关系决定。若调用 B 的参数需要调用 A 的返回值，则二者不能同轮，模型必须先看到 A 的结果再生成 B，这要求循环至少两轮。参数模式无法表达「B 依赖 A」，因此依赖只能由模型在多轮中自然形成；运行时不能自行拆分或合并调用。

并行写操作需要额外约束。两个调用同时修改同一资源会产生丢失更新，即使每个调用单独看都是合法的。可行的规则是：同一轮内允许多个只读调用；写操作按资源键串行化；不可逆操作不参与并行。冲突检测的具体机制见 [[Agent工作流与编排]] 中关于并行写的一节。

部分失败是并行的常态。$k$ 个调用中可能有 $j$ 个失败，运行时必须返回全部 $k$ 个结果并逐个标记状态，而不是在首个失败处中断。模型看到部分成功后可以只用成功结果继续，也可以修正失败调用的参数重试。

### 5 结果截断与错误表示

工具结果直接进入上下文，因此必须设上限。设单条结果上限为 $L$ 字符、单步最多 $k$ 个调用、共 $T$ 步，则结果占用的上下文上界为 $kTL$。取 $L=2000$、$k=3$、$T=10$，上界为 60000 字符；按中文约每字符 0.6 至 1 token 估算，折合 3.6 万至 6 万 token，已超过 32k 窗口的容量，因此还需要全局预算与更小的单条上限。

截断的正确做法是保留头部与尾部，并在中间显式标注省略量。头部通常包含标识符与状态，尾部包含汇总与错误信息，中段是明细。三个细节决定截断是否安全：标注必须出现在结果文本内，使模型知道信息不完整；JSON 结果应按元素截断并附加 `"truncated": true`，不能从字符串中间切断；分页优于截断，当结果本身可枚举时，返回前 $n$ 条并给出总数与继续查询的方法。

错误必须以工具结果的形式回填，而不是以异常形式抛出。异常会中断循环，模型失去修正机会；回填则把错误转化为可观察的状态。推荐的错误对象包含四个字段：

```json
{"code": "invalid_arguments",
 "message": ["$.city: 期望 string，实际 int", "$.unit: 取值 'kelvin' 不在枚举 ['celsius', 'fahrenheit'] 内"],
 "retryable": false,
 "tool": "get_weather"}
```

错误码应当收敛到有限的集合，使模型与监控都能据此决策。

| 错误码 | 触发条件 | 是否可重试 | 模型应采取的动作 |
|---|---|---|---|
| `invalid_arguments` | 模式校验失败 | 否 | 按 `message` 修正参数 |
| `unknown_tool` | 名称不在注册表 | 否 | 从可用工具中重选 |
| `timeout` | 超过单次执行上限 | 是 | 缩小范围或改换工具 |
| `rate_limited` | 下游限流 | 是，需退避 | 等待后重试 |
| `permission_denied` | 权限不足 | 否 | 请求授权或改换路径 |
| `needs_confirmation` | 不可逆操作未确认 | 否 | 生成确认请求 |
| `internal_error` | 工具内部异常 | 视情况 | 换工具或报告失败 |

空结果与错误必须区分。查询返回空列表说明「查询成功但没有匹配」，错误说明「查询未完成」；把两者都表示为空字符串会使模型误判为无数据，从而放弃本可成功的任务。

### 6 幂等性与副作用分级

**幂等**（idempotent）指同一请求执行多次与执行一次的效果相同。工具按副作用分为三级，级别决定重试策略与确认要求。

| 级别 | 例子 | 默认策略 | 重试 |
|---|---|---|---|
| 只读 | 检索、读文件、查询天气 | 自动执行 | 可无条件重试 |
| 可逆 | 创建草稿、写临时文件、下可撤销订单 | 自动执行并记录撤销信息 | 携带幂等键重试 |
| 不可逆 | 发送邮件、支付、删除生产数据、发布 | 需人工确认 | 禁止自动重试 |

超时是最容易出错的场景。超时只说明调用方停止等待，不说明操作未执行；此时若直接重试，可能产生两次副作用。可行的做法是为每个有副作用的调用生成幂等键，服务端按键去重：

$$
k_{\text{idem}}=H(\text{tool},\ \text{arguments},\ \text{session},\ \text{intent}).
$$

重试携带同一 $k_{\text{idem}}$，服务端若已执行则返回首次结果。这实现的是「至少一次投递 + 去重」，而非「恰好一次执行」；分布式环境下后者无法在调用方单侧保证。

### 7 权限与沙箱

工具把模型输出接到真实系统，权限边界必须在运行时而非提示词中实施。可执行的约束有七项：

1. 每个工具声明所需的最小权限，会话开始时按任务授予，任务结束即回收。
2. 文件路径使用白名单前缀，解析符号链接后再判断，拒绝 `..` 穿越。
3. 网络出口限制到域名白名单，禁止访问元数据服务与内网地址。
4. 资源上限包括 CPU 时间、内存、输出字节数与墙钟时间，超限即终止并回填错误。
5. 密钥在运行时注入到工具进程，不进入上下文，不出现在轨迹中。
6. 不可逆操作进入人工确认队列，确认记录包含参数摘要与请求来源。
7. 全部调用写入审计日志，包含调用者、参数摘要、结果摘要与耗时。

提示注入是工具引入的新攻击面：工具返回的文本由外部系统控制，其中可能包含试图改变模型行为的指令。防御的原则是分层：结果文本在渲染时加上边界标记，系统提示声明边界内为数据；权限判定不读取上下文；高风险工具不接受由模型自由生成的参数，而由服务端从会话状态构造。相关攻击与对齐见 [[越狱与安全对齐]]。

### 8 工具数量与选择准确率

工具描述本身占用上下文。设第 $k$ 个工具的描述与模式合计 $d_k$ token，则每步固定开销为

$$
T_{\text{tools}}=\sum_{k=1}^{N}d_k.
$$

取 $N=30$、$d_k=120$，每步多出 3600 token；在 10 步任务中这部分被重复计入 10 次。工具数量的成本是线性的，而选择难度随语义重叠上升得更快。

工具选择可视为在 $N$ 个标签上的分类：输入是任务与历史，标签是工具名。当两个工具的描述都包含「查询」「数据」「文件」时，区分的依据只剩描述中的细节，模型只能依据这些细节做判断。因此准确率随 $N$ 与描述相似度下降，下降幅度依赖模型、描述质量与任务分布，不应引用单一经验数字，应在自有任务集上测量。

四种降低选择难度的做法按成本从低到高排列：把工具名按命名空间分组（`db.query`、`fs.read`），使相似工具在名称上即可区分；把单 Agent 的直接工具数量控制在十余个量级，超出部分交给下一层 Agent；用检索从大工具集中选出候选（工具检索），把 $N$ 降为 $k$；用规则路由按任务类型分发到不同工具子集。四种做法都要求评测集包含干扰工具，否则测不出选择错误。

### 9 评测指标

三项核心指标定义如下。设第 $i$ 条任务的金标调用集合为 $G_i$，模型产生的调用集合为 $P_i$，按「工具名与参数完全一致」做二分图最大匹配，匹配数为 $M_i$：

$$
\text{Acc}_{\text{call}}=\frac{\sum_i M_i}{\sum_i\lvert G_i\rvert},\qquad
\text{Acc}_{\text{arg}}=\frac{\sum_i M_i^{\text{arg}}}{\sum_i M_i},\qquad
\text{Succ}=\frac{\#\{\text{任务完成}\}}{\#\{\text{任务}\}}.
$$

$\text{Acc}_{\text{call}}$ 衡量是否选对工具，$\text{Acc}_{\text{arg}}$ 在选对的前提下衡量参数是否逐个字段正确，$\text{Succ}$ 衡量端到端结果。三者不可互相替代：工具选对而参数错，$\text{Acc}_{\text{call}}$ 高而 $\text{Succ}$ 低；工具选错但恰好完成任务，$\text{Succ}$ 高而 $\text{Acc}_{\text{call}}$ 低。补充指标包括多余调用率（$P_i$ 中未匹配的比例）、遗漏调用率（$G_i$ 中未匹配的比例）、平均步数、P95 延迟与单任务成本。

评测集应包含四类样本：每个工具的正例；语义相近工具的对比样本；参数非法样本，用于检验错误回填是否使模型自我修正；多步依赖样本，用于检验循环与终止。示例结果如下，数据仅用于说明口径。

| 任务集 | 调用正确率 | 参数全匹配率 | 端到端成功率 |
|---|---|---|---|
| 单工具任务 30 条 | 0.97 | 0.93 | 0.93 |
| 含干扰工具 30 条 | 0.88 | 0.84 | 0.80 |

从第一行到第二行，调用正确率下降 9 个百分点，端到端成功率下降 13 个百分点，说明干扰工具主要损害选择环节。完整的评估矩阵见 [[模型评估矩阵]]。

## 关键直觉

> [!tip] 工具调用可视为把模型的生成能力限制在「动作空间」上的分类与参数填充，循环则是以外部分派器执行动作并按标识回填结果的状态机。
>
> 与严格定义的关系：定义中的四元组正是这个状态机；模型只负责 $a_t$，$\mathrm{exec}$、校验、超时、终止都由运行时承担。因此系统的可靠性由两侧共同决定，仅提高模型能力而不加固运行时，端到端成功率受限于运行时的不变量是否被破坏。

## 例子与代码

下面用纯标准库实现一个完整的循环，包含参数校验、超时、结果截断、错误回填与最大步数。三个演示工具中，`get_weather` 的参数模式限制了城市为字符串、单位为枚举；`slow_report` 的超时设为 0.3 秒，用于触发超时分支。模型部分用脚本替代，脚本第一步故意给出非法参数（城市为整数、单位为枚举外取值），第二步给出合法调用并以超时工具收尾，用于演示两轮调用与错误回填后的继续执行。

代码分五块，逐块说明其作用。第一块是校验器：`validate` 递归检查类型、枚举、边界与必填字段，返回错误字符串列表，空列表表示通过；`bool` 是 `int` 的子类，若不显式排除，`True` 会被当作合法的整数通过。第二块是注册表：`ToolSpec` 保存模式与副作用级别，`specs()` 输出协议要求的 `tools` 数组。第三块是执行：`execute` 先查表、再校验、再检查副作用级别，最后在独立线程中调用函数并用 `future.result(timeout=...)` 限制等待时间；所有异常分支都返回 `ToolResult` 而不是抛出。第四块是循环：`run_agent` 每步调用模型，若返回调用则并行执行并逐条回填，若返回文本则结束，超过 `max_steps` 则以 `max_steps` 状态退出。第五块是脚本模型与演示。

```python
# 工具注册表与 Agent 调用循环（Python 3.10+，仅用标准库）
from __future__ import annotations

import json
import time
from concurrent.futures import ThreadPoolExecutor
from concurrent.futures import TimeoutError as FutureTimeoutError
from dataclasses import dataclass, field
from typing import Any, Callable


class ToolError(Exception):
    """工具执行期错误。code 区分错误类别，retryable 指示是否值得重试。"""

    def __init__(self, code: str, message: str, retryable: bool = False) -> None:
        super().__init__(message)
        self.code, self.message, self.retryable = code, message, retryable


# ---------- 1. JSON Schema 最小校验器 ----------
_TYPES: dict[str, tuple[type, ...]] = {
    "string": (str,), "integer": (int,), "number": (int, float),
    "boolean": (bool,), "array": (list,), "object": (dict,),
}


def validate(schema: dict[str, Any], value: Any, path: str = "$") -> list[str]:
    """返回错误列表，空列表表示通过。只覆盖本篇用到的关键字。"""
    errors: list[str] = []
    expected = schema.get("type")
    if expected is not None:
        ok = isinstance(value, _TYPES.get(expected, (object,)))
        if expected in ("integer", "number") and isinstance(value, bool):
            ok = False  # bool 是 int 的子类，必须显式排除
        if not ok:
            return [f"{path}: 期望 {expected}，实际 {type(value).__name__}"]

    if "enum" in schema and value not in schema["enum"]:
        errors.append(f"{path}: 取值 {value!r} 不在枚举 {schema['enum']} 内")
    if isinstance(value, (int, float)) and not isinstance(value, bool):
        if "minimum" in schema and value < schema["minimum"]:
            errors.append(f"{path}: {value} 小于下界 {schema['minimum']}")
        if "maximum" in schema and value > schema["maximum"]:
            errors.append(f"{path}: {value} 大于上界 {schema['maximum']}")
    if isinstance(value, str):
        if "minLength" in schema and len(value) < schema["minLength"]:
            errors.append(f"{path}: 长度 {len(value)} 小于 {schema['minLength']}")
    if isinstance(value, dict):
        props = schema.get("properties", {})
        for key in schema.get("required", []):
            if key not in value:
                errors.append(f"{path}: 缺少必填字段 {key}")
        if schema.get("additionalProperties") is False:
            for key in value:
                if key not in props:
                    errors.append(f"{path}: 存在未声明字段 {key}")
        for key, sub in props.items():
            if key in value:
                errors.extend(validate(sub, value[key], f"{path}.{key}"))
    if isinstance(value, list) and "items" in schema:
        for i, item in enumerate(value):
            errors.extend(validate(schema["items"], item, f"{path}[{i}]"))
    return errors


# ---------- 2. 注册表与数据结构 ----------
@dataclass(frozen=True)
class ToolSpec:
    name: str
    description: str
    parameters: dict[str, Any]
    side_effect: str = "read_only"   # read_only | reversible | irreversible
    timeout_s: float = 5.0


@dataclass
class ToolCall:
    call_id: str
    name: str
    arguments: dict[str, Any]


@dataclass
class ToolResult:
    call_id: str
    name: str
    text: str
    is_error: bool


class ToolRegistry:
    def __init__(self) -> None:
        self._specs: dict[str, ToolSpec] = {}
        self._impl: dict[str, Callable[..., Any]] = {}
        self._pool = ThreadPoolExecutor(max_workers=8)

    def register(self, *, name: str, description: str, parameters: dict[str, Any],
                 side_effect: str = "read_only", timeout_s: float = 5.0) -> Callable:
        def deco(fn: Callable) -> Callable:
            self._specs[name] = ToolSpec(name, description, parameters, side_effect, timeout_s)
            self._impl[name] = fn
            return fn
        return deco

    def specs(self) -> list[dict[str, Any]]:
        """转为请求中的 tools 数组，字段与工具调用协议一致。"""
        return [{"type": "function", "function": {"name": s.name,
                 "description": s.description, "parameters": s.parameters}}
                for s in self._specs.values()]


# ---------- 3. 执行：校验、超时、截断、错误回填 ----------
MAX_RESULT_CHARS = 600


def truncate(text: str, limit: int = MAX_RESULT_CHARS) -> str:
    """保留头 70% 与尾 30%，显式标注省略长度。"""
    if len(text) <= limit:
        return text
    head, tail = int(limit * 0.7), limit - int(limit * 0.7)
    return f"{text[:head]}\n...[已截断 {len(text) - head - tail} 字符]...\n{text[-tail:]}"


def error_result(call: ToolCall, code: str, message: Any, retryable: bool = False) -> ToolResult:
    payload = {"code": code, "message": message, "retryable": retryable, "tool": call.name}
    return ToolResult(call.call_id, call.name, json.dumps(payload, ensure_ascii=False), True)


def execute(registry: ToolRegistry, call: ToolCall) -> ToolResult:
    spec = registry._specs.get(call.name)
    if spec is None:
        return error_result(call, "unknown_tool", f"未注册的工具 {call.name}")
    errors = validate(spec.parameters, call.arguments)
    if errors:
        return error_result(call, "invalid_arguments", errors)
    if spec.side_effect == "irreversible":
        return error_result(call, "needs_confirmation", "不可逆操作必须经人工确认")

    future = registry._pool.submit(registry._impl[call.name], **call.arguments)
    try:
        raw = future.result(timeout=spec.timeout_s)
    except FutureTimeoutError:
        # 超时只终止等待，工作线程仍在运行；有副作用的工具必须靠幂等键去重
        return error_result(call, "timeout", f"执行超过 {spec.timeout_s}s", retryable=True)
    except ToolError as exc:
        return error_result(call, exc.code, exc.message, exc.retryable)
    except Exception as exc:  # 兜底：任何异常都必须转为工具结果回填
        return error_result(call, "internal_error", f"{type(exc).__name__}: {exc}")

    text = raw if isinstance(raw, str) else json.dumps(raw, ensure_ascii=False)
    return ToolResult(call.call_id, call.name, truncate(text), False)


def execute_many(registry: ToolRegistry, calls: list[ToolCall]) -> list[ToolResult]:
    """并行执行同一轮的多个调用，返回顺序与 calls 一致。"""
    if len(calls) <= 1:
        return [execute(registry, c) for c in calls]
    with ThreadPoolExecutor(max_workers=len(calls)) as pool:
        return list(pool.map(lambda c: execute(registry, c), calls))


# ---------- 4. 消息与循环 ----------
@dataclass
class Message:
    role: str
    content: str = ""
    tool_calls: list[ToolCall] = field(default_factory=list)
    tool_call_id: str | None = None
    is_error: bool = False


SYSTEM_PROMPT = "你可以调用工具。先判断是否需要工具，需要时给出参数，结束后用自然语言总结。"


def run_agent(model: Callable[[list[Message]], Message], registry: ToolRegistry,
              question: str, max_steps: int = 5) -> tuple[str, list[Message], str]:
    messages = [Message("system", SYSTEM_PROMPT), Message("user", question)]
    print(f"[step 0] user     {question}")
    for step in range(1, max_steps + 1):
        reply = model(messages)
        messages.append(reply)
        if not reply.tool_calls:
            print(f"[step {step}] model    最终回答 {reply.content}")
            return reply.content, messages, "final"

        names = ", ".join(c.name for c in reply.tool_calls)
        print(f"[step {step}] model    -> {len(reply.tool_calls)} 个调用: {names}")
        for result in execute_many(registry, reply.tool_calls):
            flag = "ERROR" if result.is_error else "OK"
            preview = result.text.replace("\n", " ")[:58]
            print(f"[step {step}] {result.name:<14} {flag:<5} {preview}")
            messages.append(Message("tool", result.text, tool_call_id=result.call_id,
                                    is_error=result.is_error))
    print(f"[step {max_steps}] 终止：达到最大步数，未得到最终回答")
    return "", messages, "max_steps"


# ---------- 5. 三个演示工具 ----------
registry = ToolRegistry()

FLIGHT_SCHEMA = {
    "type": "object",
    "properties": {
        "origin": {"type": "string", "description": "出发城市中文名"},
        "destination": {"type": "string", "description": "到达城市中文名"},
        "date": {"type": "string", "description": "出发日期，格式 YYYY-MM-DD"},
    },
    "required": ["origin", "destination", "date"],
    "additionalProperties": False,
}


@registry.register(name="search_flights",
                   description="查询指定日期两城市间的航班，返回航班号、起飞时间与含税价格。",
                   parameters=FLIGHT_SCHEMA)
def search_flights(origin: str, destination: str, date: str) -> list[dict[str, Any]]:
    return [{"flight": "MU5101", "depart": "08:05", "price_cny": 1240},
            {"flight": "CA1831", "depart": "12:40", "price_cny": 980},
            {"flight": "HU7605", "depart": "19:15", "price_cny": 1105}]


@registry.register(name="get_weather", description="查询城市当天天气。",
                   parameters={
                       "type": "object",
                       "properties": {
                           "city": {"type": "string", "minLength": 2},
                           "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                       },
                       "required": ["city"], "additionalProperties": False})
def get_weather(city: str, unit: str = "celsius") -> dict[str, Any]:
    celsius = 21.0
    return {"city": city, "unit": unit, "condition": "多云",
            "temperature": round(celsius if unit == "celsius" else celsius * 9 / 5 + 32, 1)}


@registry.register(name="slow_report", description="生成指定编号的报表，耗时较长。",
                   parameters={"type": "object", "properties": {"report_id": {"type": "string"}},
                               "required": ["report_id"], "additionalProperties": False},
                   timeout_s=0.3)
def slow_report(report_id: str) -> str:
    time.sleep(1.2)
    return f"报表 {report_id} 已生成"


# ---------- 6. 伪造模型输出：两轮工具调用 ----------
class ScriptedModel:
    def __init__(self, script: list[Message]) -> None:
        self._script = list(script)

    def __call__(self, messages: list[Message]) -> Message:
        return self._script.pop(0) if self._script else Message("assistant", "脚本结束")


script = [
    Message("assistant", "", tool_calls=[
        ToolCall("call_1", "search_flights",
                 {"origin": "北京", "destination": "上海", "date": "2026-10-25"}),
        ToolCall("call_2", "get_weather", {"city": 123, "unit": "kelvin"}),
    ]),
    Message("assistant", "", tool_calls=[
        ToolCall("call_3", "get_weather", {"city": "上海", "unit": "celsius"}),
        ToolCall("call_4", "slow_report", {"report_id": "R-7"}),
    ]),
    Message("assistant", "2026-10-25 北京到上海 3 个航班，最低含税 980 元；上海 21 摄氏度。"),
]

answer, history, status = run_agent(ScriptedModel(script), registry, "下周六去上海，查航班和天气", max_steps=4)
print("---")
print("状态:", status, "| 消息数:", len(history),
      "| 工具消息数:", sum(1 for m in history if m.role == "tool"))
```

在 Python 3.10 及以上版本直接运行，输出如下。第一步的两个调用中，`search_flights` 成功，`get_weather` 因城市类型与单位枚举两处错误被拒绝；第二步模型按错误信息修正后成功，`slow_report` 触发超时；第三步模型给出最终回答并终止。

```text
[step 0] user     下周六去上海，查航班和天气
[step 1] model    -> 2 个调用: search_flights, get_weather
[step 1] search_flights OK    [{"flight": "MU5101", "depart": "08:05", "price_cny": 1240
[step 1] get_weather    ERROR {"code": "invalid_arguments", "message": ["$.city: 期望 stri
[step 2] model    -> 2 个调用: get_weather, slow_report
[step 2] get_weather    OK    {"city": "上海", "unit": "celsius", "condition": "多云", "temp
[step 2] slow_report    ERROR {"code": "timeout", "message": "执行超过 0.3s", "retryable": t
[step 3] model    最终回答 2026-10-25 北京到上海 3 个航班，最低含税 980 元；上海 21 摄氏度。
---
状态: final | 消息数: 9 | 工具消息数: 4
```

输出中的错误结果被截断显示，完整内容为 `{"code": "invalid_arguments", "message": ["$.city: 期望 string，实际 int", "$.unit: 取值 'kelvin' 不在枚举 ['celsius', 'fahrenheit'] 内"], "retryable": false, "tool": "get_weather"}`，两处错误在一次结果中同时返回，模型可在下一轮同时修正。

四个部件去掉后的后果可以分别验证。去掉 `validate`，`get_weather` 会在函数体内以 `TypeError` 失败，且错误信息不含字段路径，模型无法定位；去掉 `except Exception` 兜底，第一个 `TypeError` 会终止整个循环，第二步不再发生；去掉 `truncate`，一个返回十万字符的工具会把上下文一次性占满；去掉 `max_steps`，脚本耗尽后 `ScriptedModel` 持续返回固定消息，循环不终止。

代码有两处简化需要说明。第一，超时由 `future.result(timeout=...)` 实现，超时后工作线程仍在运行，Python 无法安全终止线程；生产实现应把工具放入独立进程或容器，超时后终止进程。第二，`execute_many` 用嵌套线程池实现并行，工具函数占用内部池，调度占用外部池，若把两者合并为同一个池，在并发数等于池大小时会互相等待。

## 易错点

> [!warning]
> 1. 模式与实现不一致。模式声明 `count` 为 `integer`，函数签名写成 `count: str`；校验通过而调用抛错，错误被归为 `internal_error` 重试，参数永远不变。检查方法：为每个工具写一条用例，用模式生成合法参数并直接调用函数。
> 2. 异常未捕获导致循环中断。把工具函数直接调用而不包 `try`，一次 `KeyError` 即终止整个任务，轨迹中缺失后续步骤，无法判断是工具问题还是模型问题。
> 3. 结果过大占用上下文。单条结果未设上限，一次返回整个数据库表，后续轮次无法容纳系统提示与工具描述，请求被拒绝或模型忽略早期约束。
> 4. 工具描述歧义。两个工具都描述为「查询信息」，模型按字面选择，评测集若不包含干扰工具则测不出该错误。
> 5. 调用标识未对应。并行调用只回填了部分结果，或把结果的 `tool_call_id` 写成模型名称，下一轮请求被服务端拒绝。
> 6. 把工具输出当作指令。网页抓取结果中出现「忽略之前的限制」，若该文本被拼进系统提示，权限判定即被绕过。

## 关联笔记

- [[结构化输出]] —— 前置：参数模式是结构化输出的特例，约束解码与校验方法在本篇复用。
- [[MCP协议]] —— 后续：把本篇的工具注册表与四阶段消息序列标准化为跨进程接口。
- [[Agent工作流与编排]] —— 后续：单个循环之上的路由、并行与失败回退。
- [[Agent记忆与上下文]] —— 后续：工具结果持续追加导致的上下文增长与压缩策略。
- [[Harness与Loop工程]] —— 后续：运行时如何实现超时隔离、权限与轨迹记录。

## 达标检测

- [ ] 写出 Agent 的四元组定义，并列出至少三种终止条件及其触发场景。
- [ ] 默写一次工具调用的四阶段消息序列，标明调用标识与结果标识的对应字段。
- [ ] 给定一个 JSON Schema 与对应的 Python 函数，指出至少三处可能不一致的位置。
- [ ] 运行本篇代码，构造一个必填字段缺失的调用，说明错误如何被回填且循环继续。
- [ ] 计算 $C_0=800$、$m=400$、$T=8$ 时的累计输入 token 量，并与单次调用比较。
- [ ] 为三个工具分别标注副作用级别，并给出各自的重试与确认策略。

## 参考来源

- Anthropic, "Building effective agents", 2024 —— 对应本篇第 1 节的循环定义与「工具边界由运行时承担」的判断。
- Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models", arXiv:2210.03629 —— 对应第 1 节推理与动作交替的循环结构。
- OpenAI, Function calling 指南, platform.openai.com/docs/guides/function-calling —— 对应第 2 节的 `tools`、`tool_calls`、`role: tool` 字段与并行调用。
- Model Context Protocol 规范, modelcontextprotocol.io —— 对应第 2 节 `tools/list`、`tools/call` 与结果块的跨进程形式。
