书名：《Agent Runtime 工程化：从工具调用循环到可恢复执行系统》
作者：陈堂会
章节：第四章 工具系统设计 / 4.1 Tool Registry 的真正职责
电子版系列：查看完整目录
第四章 工具系统设计：4.1 Tool Registry 的真正职责
Tool Registry 不是一个 Map<string, Function>。它至少保存以下信息：
type RiskLevel = "read" | "write" | "network" | "install" | "destructive";
type ToolDefinition<I = unknown, O = unknown> = {
name: string;
title: string;
description: string;
version: string;
inputSchema: unknown;
riskLevel: RiskLevel;
sideEffects: string[];
timeoutMs: number;
outputPolicy: {
maxCharsForModel: number;
summarizeWhenLarge: boolean;
};
execute(input: I, ctx: ToolContext): Promise<O>;
};
这些字段不是装饰。description 会影响模型是否选择工具；inputSchema 负责校验；riskLevel 进入权限审批；timeoutMs 进入执行器；outputPolicy 进入上下文预算；version 帮助兼容旧 trace 和 eval。
一个工具定义如果没有风险等级和输出策略，就像一篇报道没有事实来源和责任编辑，短期能发，长期会出事。
图 4-1：工具治理管线。工具从函数进入 runtime，要经过定义、校验、风险分类、执行预览、结果归一化和上下文预算。
读这张图时要抓住一件事：工具系统不是模型的附属品。工具定义同时服务四个消费者：
| 消费者 | 读取的字段 | 用途 |
|---|---|---|
| 模型 | name、description、inputSchema | 判断是否调用、如何填参数 |
| Permission Gate | riskLevel、sideEffects、preview | 决定自动执行、询问或拒绝 |
| Executor | timeoutMs、资源限制 | 控制执行过程和失败语义 |
| Context Builder | outputPolicy、结果类型 | 决定注入全文、摘要或引用 |
少填一个字段，可能不会立刻报错，但后面某个系统会用猜的方式补上。工程事故经常就从'先随便填一下'开始。
系列导航
前 5 篇
- 第四章 工具系统设计：导读
- 第三章 最小 Agent Loop：3.9 验收标准
- 第三章 最小 Agent Loop：3.8 动手任务
- 第三章 最小 Agent Loop：3.7 常见失败
- 第三章 最小 Agent Loop：3.6 一个 mini-agent 的目录