Agent工具调用机制完全解析:learn-agent-architecture 的工具注册表、Schema校验与分发路由实现细节
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 追加回消息 → 再次调用模型。
真正复杂的工程都在循环外围。工具运行时必须完成 5 件事:
- 告诉模型有哪些工具(下发工具清单)
- 描述每个工具的输入 Schema(参数名、类型、必填项)
- 按名称路由每一次
tool_use(分发到对应 handler) - 安全前提下并行执行调用
- 工具很多时保持可发现性(大目录的按需加载)
没有这一层,模型只能"请求动作",却没有任何环境能执行动作。
工具注册表:name → handler 的一张查表
learn-agent-architecture 的核心设计思想是:给 Agent 添加一项新能力,只需要注册一个工具,循环代码一行都不用改。
工具被定义为一个轻量的 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):注册,添加能力就是注册一个 handlerget(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。
权限决策本身是一个纯函数(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 工具就是"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 个高频坑,值得对照检查自己的实现:
- 未知工具名——返回
tool_result错误,而非崩溃循环 - Schema 漂移——schema 说一套、handler 期望另一套;必须在分发前校验
- 不安全的并行——两个写入可能损坏同一文件;默认串行,除非确知安全
- 目录溢出——几百个工具的 schema 会挤爆 prompt;先给名称,按需加载完整 schema,且追加在消息末尾以保护缓存前缀
- 结果过大——限制大小、持久化完整输出,返回"预览 + 路径",截断必须显式标注
- 选错工具——description 重叠或一工具两职;合并重复、拆分过载 schema,写清"不做什么"
- 静默输入漂移——运行时规范化或多塞参数,模型无从查因;拒绝要带理由
- 批量失败扩散——并行批次里一个调用失败拖死整个回合;只中止依赖它的调用
小结
learn-agent-architecture 用最小实现讲清了 Agent 工具调用机制的三个支柱:
- 工具注册表:
name → Tool查表,添加能力 = 注册 handler - Schema 契约:input_schema 定义参数、description 定义选型,参数保真是红线
- 分发路由:
_dispatch一个函数完成查表、执行、包装结果,且是权限、Hooks、MCP 的统一扩展点
读懂这 100 行代码,你就拿到了打开 Claude Code 等复杂 Agent 源码的钥匙——它们的工具运行时都是在这张"查表"上叠加权限、并行与懒加载。建议按仓库章节顺序继续往下读:权限与沙箱 讲 _dispatch 里的第一道门,Skills 章节 则展示了大工具目录的按需发现。



