Agent Tool Registry 详解 - Agent 工具注册中心

什么是 Tool Registry？

生活类比

想象你有个万能管家，但他不是天生就会所有技能。你需要给他准备一个"技能包柜子"，里面放着各种工具：搜索技能包、代码执行技能包、邮件发送技能包...

每次你说"帮我搜一下最近的AI新闻"，管家就会打开柜子，找到"搜索技能包"，拆开，用里面的工具干活。

这就是 Tool Registry——Agent 的技能包管理中心。

正式定义：Tool Registry 是 AI Agent 系统中负责管理、注册、发现和调度工具（Tools/Skills）的核心组件。它维护着所有可用工具的元数据、权限配置、版本信息，并提供统一的调用接口。

为什么需要 Tool Registry？

凌晨3点17分，我盯着那段报错代码，突然明白了一个道理——Agent 不能没有"技能包管理器"，就像程序员不能没有 Stack Overflow。

技能发现

Agent 需要知道"我会什么"。Registry 告诉 Agent 当前有哪些工具可用，每个工具做什么。

权限控制

不是所有 Agent 都能用所有工具。Registry 管理着"谁在什么情况下能调用什么"。

版本管理

工具会升级，API 会变化。Registry 记录版本信息，确保兼容性。

调用追踪

谁调用了什么、什么时候调用的、结果如何——Registry 是审计的起点。

Tool Registry 核心架构

三层结构

// Tool Registry 典型架构
┌─────────────────────────────────────────┐
│           Agent Layer                 │
│  "我需要搜索工具"                       │
└─────────────────┬───────────────────────┘
                  │ Tool Discovery
┌─────────────────▼───────────────────────┐
│        Tool Registry Layer             │
│  ┌─────────────────────────────────┐    │
│  │ Tool Catalog - 工具目录          │    │
│  │ Permission Manager - 权限管理     │    │
│  │ Version Controller - 版本控制    │    │
│  └─────────────────────────────────┘    │
└─────────────────┬───────────────────────┘
                  │ Tool Execution
┌─────────────────▼───────────────────────┐
│           Tool Layer                  │
│  [search_tool] [code_exec] [email] ...  │
└─────────────────────────────────────────┘

关键数据结构

interface ToolRegistration {
  // 工具身份
  id: string;              // "search-web"
  name: string;            // 显示名称
  description: string;     // 功能描述（给 LLM 看的）
  
  // 接口定义
  parameters: JSONSchema;  // 输入参数 schema
  returns: JSONSchema;     // 返回值 schema
  
  // 执行配置
  handler: Function;        // 实际执行函数
  timeout: number;         // 超时时间（毫秒）
  retries: number;          // 重试次数
  
  // 权限与版本
  permissions: string[];    // ["read:web", "write:email"]
  version: string;          // "1.2.0"
  deprecated: boolean;      // 是否已弃用
}

OpenClaw 实战应用

OpenClaw 的 Skills 系统本质上就是一个高级 Tool Registry 实现。来看看怎么用：

1. 查看可用的 Skills

# OpenClaw CLI 查看已注册的 Skills
$ openclaw skills list

Available Skills:
  ├─ feishu-doc       Feishu 文档操作
  ├─ feishu-drive      飞书云盘管理
  ├─ cover-image      封面图生成
  ├─ ai-seo           AI 搜索优化
  └─ cold-email        营销邮件撰写

2. 注册新的 Skill

// 在 SKILL.md 中定义工具注册信息
# SKILL.md - My Custom Skill

## Tool Definition
- id: my-custom-tool
- name: 自定义工具
- description: 执行自定义任务的工具
- parameters:
    - input (string): 输入内容
    - mode (enum): 执行模式
- returns:
    - result (string): 执行结果
    - status (boolean): 是否成功

## Permission Required
- read:files
- exec:shell

3. 动态调用注册的工具

const result = await openclaw.useSkill('cover-image', {
  title: 'Agent Tool Registry 详解',
  type: 'cinematic',
  palette: 'dark-gold',
  aspect: '16:9'
});

// Registry 自动处理：
// 1. 权限验证 - 检查当前 Agent 是否有权限
// 2. 参数校验 - 根据 JSON Schema 验证输入
// 3. 超时控制 - 默认 30 秒超时
// 4. 错误处理 - 自动重试 + 回退

常见设计模式

模式	描述	适用场景
Static Registry	启动时加载所有工具，运行时不变	工具固定的系统
Dynamic Registry	运行时可注册/注销工具	插件化架构
Federated Registry	多个 Registry 协同，跨服务共享	多 Agent 系统
Lazy Registry	按需加载工具，节省资源	工具数量庞大的系统

常见坑点

踩坑实录

坑1：工具描述太模糊

如果你的工具描述是"执行任务"，LLM 根本不知道什么时候该用。好的描述："搜索互联网并返回前10个相关结果，适合需要实时信息的查询"。

坑2：权限粒度太粗

给 Agent "write:*" 权限，等于把整个系统的钥匙交出去。应该细化为 "write:email"、"write:calendar" 等。

坑3：版本兼容噩梦

升级工具后，所有依赖的 Agent 都挂了。Registry 必须支持多版本共存，让 Agent 指定版本调用。

最佳实践

描述驱动：给每个工具写详细描述，LLM 靠这个决定何时调用
Schema 优先：用 JSON Schema 定义参数，自动验证 + 文档生成
最小权限：默认不给权限，按需申请
版本锁定：生产环境固定版本号，避免自动升级
超时兜底：每个工具都必须有超时，防止卡死整个 Agent
可观测性：记录每次调用，方便调试和审计

Agent Tool Registry