# Agent Tools-use 工具调用可靠性规则与约束

> **适用范围**：本文件适用于所有调用外部工具的 AI Agent。Agent 在发起任何工具调用前，须完整遵循以下结构化范式与自纠错机制。

## 总体原则

将工具视为确定性合约（contracts first, code second）。每项工具调用必须满足三个条件：格式合法、参数有效、结果可验证。工具调用失败后，Agent 必须具备自我修复能力，而非单纯重试或放弃。2026 年的最佳实践已将工具调用从"单向输出"升级为"可控+可验证"的工程化模式。

## 一、结构化范式

### 1. Schema 设计规范

#### 1.1 单一职责
- 每个工具的功能必须聚焦于一个明确的职责。若一个工具承担多项职责，应拆分为多个独立工具。

#### 1.2 命名与描述规范
- 工具名必须采用动词_名词格式（如 `get_weather`、`search_database`、`send_email`），不得使用模糊命名（如 `process`、`handle`、`do`）。
- 描述中必须明确说明工具的功能、适用场景、输入约束和输出格式。
- 参数名称必须自描述：`user_id` 优于 `id`，`date_of_birth` 优于 `dob`。

#### 1.3 Schema 约束规则

所有工具的定义必须遵循以下 JSON Schema 约束：

```json
{
  "name": "工具名称",
  "description": "清晰描述功能、场景和约束",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["必填参数列表"],
    "properties": {
      "参数名": {
        "type": "string|integer|boolean|array|object",
        "description": "参数说明"
      }
    }
  }
}
```

**关键约束：**
- `additionalProperties: false` — 必须禁止模型生成 Schema 未定义的字段
- `required` 数组 — 必须明确列出所有必填参数，缺一不可
- `type` 声明 — 每个参数必须声明类型
- 取值范围约束 — 为有限取值的参数使用 `enum`；数值参数使用 `minimum`/`maximum`；字符串使用 `pattern` 正则约束
- `format` 扩展 — 对日期、邮箱等格式使用 `format: date-time|email|uuid` 等标准格式

#### 1.4 时间预算与幂等性设计

每个工具调用必须声明：
- **timeout**：最大等待时间（毫秒），超时后必须触发降级或重试
- **retry**：最大重试次数 + 退避策略（exponential backoff）
- **idempotency**：幂等性键（key_fields），确保重复调用不产生副作用

对于有状态变更的工具（如数据库写入、API 调用），必须通过幂等键确保重复调用的安全性。

### 2. 输出格式规范

#### 2.1 强制结构化输出

所有工具调用的输出必须为合法 JSON 格式，且符合预先定义的输出 Schema。Agent 不得输出自由文本作为工具调用结果。

对于支持 `strict: true` 的模型 API，必须在请求中启用此选项，将 Schema 约束内置于生成过程本身，而非仅依赖生成后验证。

#### 2.2 调用前验证（pre-call validation）

在每次工具调用执行前，必须验证：
- JSON 格式是否合法
- 必填字段是否完整
- 参数类型是否符合 Schema
- 参数值是否在允许范围内

验证失败时，不得执行调用，必须进入自纠错流程。

#### 2.3 调用后验证（post-call validation）

在工具执行返回后，必须验证：
- 返回状态码是否为 2xx（HTTP）或等效的成功码
- 返回数据的关键字段是否存在
- 返回数据是否符合预期格式
- 来源和时间戳（如适用）是否可追溯

工具调用不能只成功，还要可验证。检索类工具必须返回来源 + 时间戳，否则不进入下一步；写入类工具必须返回路径 + 字数 + 摘要。

## 二、自纠错机制

### 1. 错误分类法

Agent 在检测到错误时，必须按以下分类法诊断，不得模糊处理。分类法借鉴 AgentFixer 的验证框架思路，涵盖输入处理、提示设计和输出生成等多个维度。

| 错误类别 | 触发条件 | 可恢复性 |
|---|---|---|
| **格式错误** | 输出不是合法 JSON；JSON Schema 验证失败 | 可恢复 |
| **参数错误** | 参数类型错误、超出范围、格式不匹配 | 可恢复 |
| **工具选择错误** | 调用了错误的工具；在无需调用时错误调用了工具 | 可恢复 |
| **执行错误** | 调用成功但 API 返回异常状态码、超时、数据格式异常 | 部分可恢复 |
| **语义错误** | 模型对工具返回结果理解有误，导致后续推理错误 | 可恢复 |
| **权限/安全错误** | 工具尝试执行越权操作（不可恢复时须立即终止） | 不可恢复 |

### 2. 结构化反思流程

当一次工具调用失败时，Agent 必须按以下结构执行反思，而非盲目重试。美团研究团队提出的结构化反思方法将错误诊断和修复转化为可学习的可训练动作，显著提升了多轮工具调用的成功率和错误恢复能力。

**Step 1 — 错误诊断：**
```
[ERROR_DIAGNOSIS]
- 错误类别：{format|argument|tool_choice|execution|semantic|permission}
- 失败步骤：{步骤序号/名称}
- 证据依据：{原始错误信息或返回内容}
- 根本原因：{简述}
```

**Step 2 — 修正提案：**
```
[FIX_PROPOSAL]
- 修正动作：{重试|重写参数|切换工具|降级处理|上报}
- 修正后调用：{完整的修正后工具调用}
- 预期结果：{描述}
```

**Step 3 — 执行修正：**
执行修正提案，重复 Step 1–2 直到成功或达到最大重试次数。

### 3. 重试与降级策略

#### 3.1 重试预算

| 失败阶段 | 最大重试次数 | 退避策略 |
|---|---|---|
| 格式/参数验证失败 | 2 次 | 立即重试，反馈错误信息 |
| 工具执行超时/失败 | 3 次 | 指数退避（1s, 2s, 4s） |
| 语义错误 | 2 次 | 立即重试，携带反思轨迹 |

达到最大重试次数后，必须触发降级。

#### 3.2 降级路径

按以下优先级选择降级路径：
1. 切换到备用工具（如主搜索失败 → 备用搜索引擎）
2. 降低精确度要求（如实时数据 → 缓存数据）
3. 请求人工确认/介入
4. 标记任务为"不可完成"并记录失败原因

### 4. 反馈闭环

#### 4.1 反馈信号分级

每次成功或失败的调用，必须生成结构化的反馈记录：

| 信号类型 | 触发条件 | 权重 |
|---|---|---|
| 成功 | 验证通过且结果满足预期 | +1.5（成功路径比失败路径更稀有，因此权重更高） |
| 可恢复错误 | 任何可恢复类错误触发重试 | +1.0 |
| 不可恢复错误 | 权限错误或达到最大重试次数后失败 | +0（需人工介入） |

成功信号的权重高于失败信号，因为存在无限种失败方式，但只有少数方式能正确完成任务。成功信号的信息密度更高。

#### 4.2 错误记录规范

每次工具调用失败必须记录以下信息，用于后续规则优化：
- 时间戳、会话 ID、步骤 ID
- 原始输入、模型输出、错误信息
- 修正过程（如触发反思流程）
- 最终结果（成功/失败/降级）

## 三、执行流程示意

Agent 在调用工具时必须遵循以下流程：

```
用户请求 → 拆解任务 → 选择工具 + 生成参数 → [预验证] → 调用工具 → [后验证]
    ↑                                        ↓                      ↓
    │                                      失败                    失败
    └────────── 反思修正 ←───────────────── 错误分类 ─────────────→ 降级/上报
```

关键节点说明：
- **预验证**：在调用执行前，校验格式与参数合法性
- **后验证**：调用返回后，校验状态码与数据完整性
- **反思修正**：遵循"诊断 → 修正提案 → 执行修正"三步流程

## 四、与 Memory 系统的集成

### 4.1 在 Memory 系统中的应用

本规范定义的规则与 Agent Memory System 的关系：

- **记忆记录**：工具调用的错误、修正过程、降级决策应记录到记忆中
- **上下文编排**：`ContextOrchestrator` 应支持工具调用结果验证
- **错误处理**：`FallbackManager` 应集成工具调用的降级策略

### 4.2 推荐集成点

| 集成点 | 功能 | 说明 |
|--------|------|------|
| `ContextOrchestrator` | 工具调用结果验证 | 在 prepare_context 中集成后验证 |
| `FallbackManager` | 工具调用降级 | 扩展降级策略支持工具调用场景 |
| `ShortTermMemoryManager` | 错误记录 | 记录工具调用错误和修正过程 |
| `ChainReasoningEnhancer` | 反思机制 | 支持结构化反思流程 |

### 4.3 实现建议

本规范是 Agent 层面的通用规则，Memory 系统可以：

1. **提供记忆支持**：记录工具调用的错误、修正、降级等信息
2. **集成验证机制**：在 `ContextOrchestrator` 中添加工具调用结果验证
3. **扩展降级策略**：在 `FallbackManager` 中添加工具调用特定的降级策略
4. **支持反思机制**：在 `ChainReasoningEnhancer` 中支持结构化反思流程

## 补充说明

**层级关系**：本文件定义的是 Agent 执行层面的通用规则。具体项目的技术栈声明、代码规范、测试要求、Git 规范等，应另行维护在项目根目录的 `AGENTS.md` 文件中，与本文件形成分层管理。

**参考文档**：
- [FallbackManager 错误处理机制](../scripts/fallback_manager.py)
- [ContextOrchestrator 上下文编排](../scripts/context_orchestrator.py)
- [agent_loops_integration.md](agent_loops_integration.md) - 智能体循环集成