AI Agent / 系统课时
注册与发现工具
注册与发现工具
本篇解决智能体如何知道自己当前可以调用哪些能力,并实现一个可扩展的工具注册中心。完成后,智能体可以根据运行环境动态获取工具列表,而不是把工具名称硬编码在流程中。
学习目标
- 理解 Tool Registry 在智能体工具系统中的职责
- 实现工具注册、查询和发现的基础流程
- 掌握工具元数据设计与动态加载方式
工具注册中心解决的问题
智能体调用工具前需要知道有哪些工具可用、每个工具需要什么参数以及适合什么场景。如果把工具列表直接写在 Agent 逻辑中,新增能力时就需要修改核心代码,导致系统难以维护。
Tool Registry 将工具定义集中管理。它保存工具名称、描述、参数结构和执行入口,Agent 只负责查询和选择,不需要了解每个工具的内部实现。

实现工具注册与查询
一个最小 Registry 需要维护工具名称到工具对象的映射,并提供注册和发现接口。
python
from dataclasses import dataclass
from typing import Callable
@dataclass
class Tool:
name: str
description: str
handler: Callable
class ToolRegistry:
def __init__(self):
self.tools = {}
def register(self, tool: Tool):
# 使用名称作为唯一标识,避免调用时产生歧义
self.tools[tool.name] = tool
def discover(self):
return [
{
"name": tool.name,
"description": tool.description
}
for tool in self.tools.values()
]
def get_time():
return "<TIME>"
registry = ToolRegistry()
registry.register(Tool("get_time", "获取当前时间", get_time))
print(registry.discover())预期输出
text
[{'name': 'get_time', 'description': '获取当前时间'}]实际项目中,discover 返回的信息通常会进一步转换为模型可理解的工具描述,例如函数参数 JSON Schema。
工具元数据设计
工具不仅需要名称,还需要描述边界。高质量的工具描述可以帮助模型判断什么时候调用它。
常见字段包括:
| 字段 | 作用 |
|---|---|
| name | 工具唯一名称 |
| description | 告诉模型工具用途 |
| inputSchema | 定义输入参数 |
| permissions | 限制可执行范围 |
工具描述应该说明能力和限制,避免出现“万能工具”这种模糊定义。
常见错误
工具系统初期容易把所有能力暴露给模型,但工具数量增长后会产生选择困难。更好的方式是根据用户任务、权限和运行环境过滤工具列表。
另一个问题是工具名称重复。Registry 必须保证名称唯一,否则模型选择工具时无法确定实际执行逻辑。
本课总结
- Tool Registry 将工具定义与 Agent 推理逻辑解耦。
- 注册、发现和执行应该拆分为独立阶段。
- 工具元数据质量会直接影响模型选择效果。
下一课预告
下一课将实现文件读取工具,让智能体能够安全访问外部文件内容,并控制读取范围。
按自己的节奏,确认真正理解。