给AI装上双手:Agent工具系统设计全解析

Agent 的能力 = LLM 推理能力 × 工具系统覆盖范围  推理能力（LLM）= 大脑  工具系统（Tools）= 双手  没有工具的 Agent → 只是聊天机器人  没有 LLM 的工具 → 只是普通函数

客服 Agent = 工单界面 + 工具集（查订单、退款、发邮件）+ LLM 推理循环

interface APITool {  name: string;           // 工具名（LLM 选择的依据）  description: string;    // 描述（LLM 理解用途的关键）  input_schema: {         // 参数定义（JSON Schema）type: "object";    properties: Record;    required: string[];  };}

// 工具分类enumToolCategory {READ = "READ",         // 只读，无副作用WRITE = "WRITE",       // 写入，有副作用EXECUTE = "EXECUTE",   // 执行命令，高风险}// 完整工具定义interfaceToolDefinition {name: string;description: string;category: ToolCategory;inputSchema: { type: "object"; properties: ...; required: ... };handler: (input: any) =>Promise;  // 执行函数}// 标准化结果interfaceToolResult {success: boolean;     // 是否成功  data?: unknown;       // 成功时的数据  error?: string;       // 失败时的错误信息  meta?: {              // 元信息（调试/监控）duration: number;toolName: string;  };}

classToolRegistry{private tools: Map;        // 名称 → 定义private categoryIndex: Map; // 分类 → 名称列表register(tool: ToolDefinition): void;       // 注册unregister(name: string): boolean;          // 注销get(name: string): ToolDefinition;          // 查找list(): ToolDefinition[];                   // 全部列出listByCategory(cat: ToolCategory): ...;     // 按分类列出execute(name: string, input: any): Promise;  // 执行toAPIFormat(): Tool[];                      // 转为 API 格式}

Agent 循环                       ToolRegistry    │                                  │    │  1. LLM 返回 tool_use            │    │  2. 提取工具名 + 参数            │    │──────────────▶  3. get(name)     │    │◀──────────────  4. 返回定义      │    │──────────────▶  5. execute()     │    │                    ├─ 检查参数    │    │                    ├─ 调用 handler│    │                    └─ 返回结果    │    │◀──────────────  6. 返回 ToolResult│    │  7. 注入结果到消息               │

// ❌ 坏描述 —— 太简略{  name: "search_code",  description: "搜索代码",}// ✅ 好描述 —— 说清用途、时机、限制{  name: "search_code",  description: "在项目中搜索代码。当你需要查找函数    定义、变量引用、或确认某段代码是否存在时使用。    支持按关键词和文件类型过滤。    注意：搜索范围仅限于已索引的项目文件。",}

{  name: "generate_report",  description: "生成分析报告。注意：在调用此工具前，    请确保已通过 read_file、search_code 等工具收集了    足够的信息。如果信息不足，请先收集信息。",}

LLM 思考："需要退款，先查订单，再退款，最后通知"  → 第1步: query_order("ORD-001")  → 第2步: refund_order("ORD-001")  → 第3步: send_email("user@example.com", "退款成功")

LLM: process_refund("ORD-001")  ↓process_refund handler 内部:1. query_order("ORD-001")     → 验证订单2. check_inventory("P001")     → 更新库存3. create_refund_record(...)   → 创建退款4. send_email("user@...")      → 通知用户5. return { success: true }

read_config → parse_config → validate_config → apply_config     ↓              ↓              ↓              ↓  原始 JSON     解析对象      验证结果       应用结果

executeTool(name, input) {  preHooks.forEach(hook =>hook(name, input));   // 前置钩子const result = awaithandler(input);            // 执行  postHooks.forEach(hook =>hook(name, result));  // 后置钩子return result;}

📦 01-tool-registry.ts — 注册中心 + 6 个示例工具

🔧 02-business-tools.ts — 真实业务场景（客服工具集）

🤖 03-tool-composition.ts — 工具组合（编排 + 组合 + 管道）

ToolDefinition（接口定义）  ├─ name         ← LLM 选择依据  ├─ description  ← LLM 理解依据  ├─ inputSchema  ← 参数验证  ├─ category     ← 安全分类（READ/WRITE/EXECUTE）  └─ handler      ← 实际执行ToolRegistry（注册中心）  ├─ register/unregister  ← 动态管理  ├─ get/list             ← 查找工具  ├─ execute              ← 统一执行入口  └─ toAPIFormat          ← 转为 API 格式ToolResult（结果标准化）  ├─ success: boolean  ← 执行状态  ├─ data/error        ← 成功/失败数据  └─ meta              ← 元信息（耗时等）