AGI 未来之门

主题

Agent 工具设计与 MCP ​

对 Agent 而言，工具就是 API；但它的调用者不是严格按文档编程的人，而是根据名称、描述和 Schema 临时做决定的模型。模糊的工具边界会把普通 API 的易用性问题放大成错误行动。

1. 好工具的五个特征 ​

  1. 意图单一：名称准确表达一种业务动作；
  2. 参数窄而明确：使用枚举、格式、上下限和互斥规则；
  3. 结果结构化：明确成功、可重试失败和业务拒绝；
  4. 影响可预览：写入前可展示对象、范围与后果；
  5. 可幂等与审计：重复调用不产生重复副作用，能追溯调用来源。

execute_any_sql(sql) 或 http_request(url, body) 看似通用，却把权限和业务约束交给模型。更好的工具是 find_open_invoices(customer_id) 和 create_refund_draft(invoice_id, reason)。

2. 从名称和描述开始设计 ​

名称用动词加业务对象：search_documents、get_order、create_refund_draft。描述要说明何时用、何时不用、执行是否产生副作用：

text
create_refund_draft:
为一笔符合资格的订单创建退款草稿，不会实际打款。
仅在 get_order 返回 refundable=true 后调用。
同一 order_id 与 idempotency_key 重复调用会返回原草稿。

不要靠几十条提示词弥补工具语义混乱。若模型总把两个工具用反，优先重命名、拆分或合并工具。

3. Schema 是第一层护栏 ​

json
{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "pattern": "^ord_[a-z0-9]+$" },
    "reason": {
      "type": "string",
      "enum": ["duplicate_charge", "service_failure", "other"]
    },
    "note": { "type": "string", "maxLength": 500 },
    "idempotency_key": { "type": "string", "minLength": 16, "maxLength": 80 }
  },
  "required": ["order_id", "reason", "idempotency_key"],
  "additionalProperties": false
}

Schema 限制形状，服务端仍必须校验：当前用户能否访问订单、订单是否可退款、退款金额是否合规、幂等键是否与相同参数绑定。永远不因为参数“来自模型”就跳过鉴权。

4. 把预览和执行分开 ​

高影响工具采用两阶段：

text
prepare_deployment(commit, environment)
  → 返回 plan_id、Diff、风险、预计影响
用户或策略引擎批准 plan_id
execute_deployment(plan_id, approval_token)

执行接口只接受不可变 plan_id，而不是让模型在批准后重新组织参数。批准令牌绑定用户、计划摘要、过期时间和允许动作，防止“看的是 A，执行成 B”。

5. 设计机器可行动的错误 ​

只返回 Something went wrong 会让 Agent 反复盲试。错误响应应区分：

json
{
  "ok": false,
  "error": {
    "code": "ORDER_NOT_REFUNDABLE",
    "retryable": false,
    "message": "The settlement window has closed.",
    "next_actions": ["explain_policy", "escalate_to_human"]
  }
}

message 供模型解释，code 供状态机分支，retryable 供运行时判断。不要把堆栈、数据库语句或秘密放进返回结果。

6. 工具结果控制上下文体积 ​

列表工具默认分页，只返回决策所需字段；大文件或日志返回资源引用和摘要：

json
{
  "artifact_id": "artifact_123",
  "mime_type": "text/plain",
  "size": 842190,
  "summary": "Type check failed with 12 errors in 3 files.",
  "highlights": ["src/user.ts:42 TS2322"]
}

再提供 read_artifact(artifact_id, offset, limit) 按需读取。这样既保留原始证据，也避免一次观察撑满上下文。

7. MCP 解决哪一层问题 ​

MCP 把客户端与能力提供方之间的发现和调用方式标准化。常见概念包括：

  • Tools：可执行动作；
  • Resources：可读取的上下文资源；
  • Prompts：服务器提供的可复用交互模板；
  • Client / Server：主机中的客户端连接一个或多个能力服务器。

协议统一不等于自动安全。MCP Server 仍需实现鉴权、租户隔离、输入校验、限流和审计；Host 仍需控制哪些 Server 被信任、哪些工具在当前状态可见。

规范演进（核对于 2026-09）：现行 2026-07-28 版规范做了无状态化改造（移除 initialize 握手与会话头），标准传输为 stdio 与 Streamable HTTP，HTTP+SSE 已废弃。本文讲的是与协议版本无关的工具设计原则；动手实现按最新 SDK 写法，见《实战：把一个查询能力做成 MCP Server》，版本细节见其第 10 节快照。

8. MCP Server 的分层结构 ​

MCP Server 四层结构

  1. MCP 传输与协议适配自动触发
    只做协议转换，不含业务逻辑
  2. 工具 Schema 与结果映射自动触发
  3. 应用服务：鉴权、规则、幂等、审计检查点
    可独立测试的业务层
  4. 外部 API / 数据库 / 文件系统自动触发

协议处理层不直接拼数据库查询。业务逻辑放在可独立测试的应用服务中，MCP 只是一个适配器；未来增加 REST、队列消费者或内部调用时可复用同一规则。

9. 工具集合也需要评测 ​

建立工具调用测试集，记录目标、可用工具、期望工具、关键参数和禁止动作。指标至少包括：

  • 工具选择准确率；
  • 参数 Schema 通过率；
  • 首次调用成功率；
  • 无意义重复调用率；
  • 越权动作拦截率；
  • 每个成功任务的工具调用次数。

如果加入一个新工具后原有选择准确率下降，说明工具之间语义重叠或描述造成干扰。工具不是越多越强，而是越清晰越可靠。

10. 发布清单 ​

  • [ ] 名称、描述和参数能让不了解内部实现的人正确区分工具。
  • [ ] additionalProperties、枚举、范围和格式尽可能严格。
  • [ ] 服务端重新鉴权并验证所有业务不变量。
  • [ ] 写操作支持幂等，未知结果可以查询确认。
  • [ ] 高影响动作可预览，批准与执行参数绑定。
  • [ ] 错误码稳定、可分类，返回不泄露内部信息。
  • [ ] 大结果可分页或资源化，不直接淹没上下文。
  • [ ] 有调用级审计和针对模型调用者的回归评测。

先找工作，再找工具。

AGI 未来之门