Agent工具调用机制完全解析:learn-agent-architecture 的工具注册表、Schema校验与分发路由实现细节

原创2026-10-14 11:27:431,990 阅读

Agent工具调用机制完全解析:learn-agent-architecture 的工具注册表、Schema校验与分发路由实现细节

在 AI Agent 开发中,Agent 工具调用机制是连接"模型想做的事"和"系统真正做的事"的关键一环。开源项目 learn-agent-architecture 用约 100 行 Python 代码,把 Agent 工具调用的完整链路拆解成可运行的最小实现:工具注册表(Registry)、输入 Schema 校验、按名称分发路由(dispatch),以及只读工具的并行批处理。本文将从注册表讲到分发路由,带你看懂工具运行时(Tool Runtime)的每个实现细节。

Agent 工具调用机制全景:一次调用的完整旅程

Agent 循环(Agent Loop)本身很小:调用模型 → 模型发出结构化的 tool_use 区块(含 name 和 input)→ 运行时执行工具 → 把结果作为 tool_result 追加回消息 → 再次调用模型。

Agent 工具调用循环:模型请求工具与结果回流的流程图

真正复杂的工程都在循环外围。工具运行时必须完成 5 件事:

  1. 告诉模型有哪些工具(下发工具清单)
  2. 描述每个工具的输入 Schema(参数名、类型、必填项)
  3. 按名称路由每一次 tool_use(分发到对应 handler)
  4. 安全前提下并行执行调用
  5. 工具很多时保持可发现性(大目录的按需加载)

没有这一层,模型只能"请求动作",却没有任何环境能执行动作。

工具注册表:name → handler 的一张查表

learn-agent-architecture 的核心设计思想是:给 Agent 添加一项新能力,只需要注册一个工具,循环代码一行都不用改。

Agent 工具运行时机制图:工具注册表、Schema 校验与分发路由的关系

工具被定义为一个轻量的 dataclass(见 tools.py),每个字段都有明确用途:

@dataclass
class Tool:
    name: str                       # 注册表的主键
    run: Callable[[dict], Any]      # 真正执行的工具函数
    description: str = ""           # 给模型看的"说明书"
    input_schema: dict = ...        # 输入参数 Schema(Anthropic 格式)
    is_read_only: bool = False      # 是否只读(权限门读取)
    is_concurrency_safe: bool = False  # 能否进入并行批次
    is_edit: bool = False          # 是否文件编辑(权限门读取)

Registry 则是一张 name → tool 的字典(tools.py),只提供三个方法:

  • register(tool):注册,添加能力就是注册一个 handler
  • get(name):查表,分发本质上就是一次字典查找
  • schemas():生成下发给模型的 tools 列表(name + description + input_schema)

这种"注册表即接口"的设计让循环、权限、Hooks、MCP 等上层模块全部面向 Registry 编程,互不耦合。

input_schema 与参数保真:为什么运行时绝不能改写输入

input_schema 是模型填参的"契约":声明了参数名、类型和 required 字段。无参工具使用统一的空对象 Schema NO_INPUT(tools.py)。

这里有一条工程红线,也是官方文档(README.zh-CN.md)重点强调的参数保真原则:

模型发来一个编辑,查找字符串里带一个弯引号,harness 却在送往 handler 的路上把它"纠正"成直引号——编辑随即失配,而模型只看到"字符串没找到"。它发出的输入是对的,整个对话记录里找不到任何解释。

规则很简单:input 原封不动交给 handler;不合法就拒绝并说明原因;绝不悄悄改写,也绝不添加模型没写的参数。 否则会出现"模型没错却失败"的幽灵 Bug。

同样关键的是 description——它是模型在选工具前唯一读得到的文字。写得好会交代五件事:什么时候用、什么时候不该用、参数的真实取值长什么样、返回什么形状、调用一次的代价。两个 description 描述重叠,是"模型选错工具"最常见的原因。

分发路由:_dispatch 如何把 tool_use 变成 tool_result

分发逻辑集中在一个函数里。第 2 章的最小实现见 loop.py:

def _dispatch(block, registry):
    tool = registry.get(block.name)                      # 1. 按名称查表
    content = f"error: no tool {block.name!r}" if tool is None \
              else run_tool(tool, block.input)           # 2. 执行(永不抛异常)
    return {"type": "tool_result", "tool_use_id": block.id, "content": content}

两个细节决定了 Agent 的健壮性:

  • 未知工具名不崩溃:模型指名一个不存在的工具时,返回一条 error: no tool 的 tool_result,让模型看到错误并自行纠正,而不是让整个循环抛异常。
  • 失败是结果,不是崩溃:run_tool 用 try/except 把任何异常转成 "error: 类型: 信息" 字符串喂回模型——工具失败必须依然返回 tool_result,模型才有机会恢复。
  • max_steps 兜底:外层循环设最大步数(loop.py),防止"调用工具→再调用工具"的失控循环。

_dispatch 也是整个运行时的核心扩展点:后续章节的权限门、Hooks 都插在同一个位置。以完整演进后的版本为例(loop.py),一次分发依次经过:查表 → PreToolUse Hook → 权限决策(allow / ask / deny)→ 执行 → PostToolUse Hook。

权限与沙箱机制:工具执行前的 allow、ask、deny 三道决策

权限决策本身是一个纯函数(permissions.py):只读工具放行,acceptEdits 模式预批编辑,不确定时默认 ask 交给人判断——这正是 Tool 上 is_read_only、is_edit 两个谓词字段的用途。

并行工具调用:is_concurrency_safe 的批处理规则

模型一个回合常发出多个工具调用。真实的运行时会把调用分区(partition-then-run):

run_concurrently 的实现规则是:

调用类型 执行方式
标记 is_concurrency_safe=True(如只读查询) 线程池并行,共享一个批次
其余调用(写操作等) 严格串行,避免两个写入竞争同一文件
输出顺序 与输入顺序一致,模型看到的时序不会乱

默认关闭并行、只对已知安全的工具放行——"宁可慢,不可错"。

外部工具接入:MCP 工具如何并入同一注册表

工具注册表的另一优点是开放性:接入 MCP 服务器后,每个远端工具被包装成一个标准 Tool,命名为 mcp__<server>__<tool>,直接并入同一个工具池(mcp.py)。

MCP 与插件:外部工具如何并入 Agent 工具池并走同一分发流程

也就是说,一个 MCP 工具就是"run() 通过 transport 调到远端进程"的普通 Tool——循环、权限门、分发逻辑完全不变。远端工具自带的 readOnlyHint 注解会映射成权限门读取的风险提示。

动手运行:官方示例与测试

第 2 章自带可运行代码(src/),无需联网即可验证分发、未知工具报错和并行批处理:

# 离线检查(无需 API Key)
python sections/02-tool-runtime/src/test.py

# 实时演示:注册一个 ReadFile 工具并对 API 跑完整循环
uv run python sections/02-tool-runtime/src/demo.py

相关文件导读:

仓库的学法也很特别:每一章的 src/ 承接上一章,只新增一个机制。对比相邻两章的 diff,就能看出本章到底加了什么——从第 2 章的注册表一路演进到第 23 章的完整 harness。

工具运行时的 8 个常见失败模式

官方文档总结了 8 个高频坑,值得对照检查自己的实现:

  1. 未知工具名——返回 tool_result 错误,而非崩溃循环
  2. Schema 漂移——schema 说一套、handler 期望另一套;必须在分发前校验
  3. 不安全的并行——两个写入可能损坏同一文件;默认串行,除非确知安全
  4. 目录溢出——几百个工具的 schema 会挤爆 prompt;先给名称,按需加载完整 schema,且追加在消息末尾以保护缓存前缀
  5. 结果过大——限制大小、持久化完整输出,返回"预览 + 路径",截断必须显式标注
  6. 选错工具——description 重叠或一工具两职;合并重复、拆分过载 schema,写清"不做什么"
  7. 静默输入漂移——运行时规范化或多塞参数,模型无从查因;拒绝要带理由
  8. 批量失败扩散——并行批次里一个调用失败拖死整个回合;只中止依赖它的调用

小结

learn-agent-architecture 用最小实现讲清了 Agent 工具调用机制的三个支柱:

  • 工具注册表:name → Tool 查表,添加能力 = 注册 handler
  • Schema 契约:input_schema 定义参数、description 定义选型,参数保真是红线
  • 分发路由:_dispatch 一个函数完成查表、执行、包装结果,且是权限、Hooks、MCP 的统一扩展点

读懂这 100 行代码,你就拿到了打开 Claude Code 等复杂 Agent 源码的钥匙——它们的工具运行时都是在这张"查表"上叠加权限、并行与懒加载。建议按仓库章节顺序继续往下读:权限与沙箱 讲 _dispatch 里的第一道门,Skills 章节 则展示了大工具目录的按需发现。

登录后查看全文
learn-agent-architecture