Agent 教程

外观

设计自己的 Tool 系统 ​

第一版 Tool 系统不要太复杂。建议只做 4 个模块：

text
Tool
ToolRegistry
ToolExecutor
ToolResultSerializer

Tool ​

ts
export type Tool<Input = unknown, Output = unknown> = {
  name: string
  description: string
  inputSchema: Schema<Input>
  readonly: boolean
  execute(input: Input, context: ToolContext): Promise<Output>
  toText(output: Output): string
}

ToolRegistry ​

ts
export class ToolRegistry {
  private tools = new Map<string, Tool>()

  register(tool: Tool) {
    if (this.tools.has(tool.name)) {
      throw new Error(`Duplicate tool: ${tool.name}`)
    }
    this.tools.set(tool.name, tool)
  }

  get(name: string) {
    const tool = this.tools.get(name)
    if (!tool) throw new Error(`Unknown tool: ${name}`)
    return tool
  }

  toModelSchemas() {
    return [...this.tools.values()].map(tool => ({
      name: tool.name,
      description: tool.description,
      input_schema: tool.inputSchema.toJSON(),
    }))
  }
}

ToolExecutor ​

ts
export async function executeToolUse(
  toolUse: ToolUse,
  registry: ToolRegistry,
  context: ToolContext,
) {
  const tool = registry.get(toolUse.name)
  const input = tool.inputSchema.parse(toolUse.input)
  const output = await tool.execute(input, context)

  return {
    type: "tool_result",
    tool_use_id: toolUse.id,
    content: tool.toText(output),
  }
}

什么时候再加复杂能力 ​

按这个顺序演进：

  1. schema 校验。
  2. 读写工具。
  3. 权限网关。
  4. 工具并发。
  5. Hooks。
  6. MCP。
  7. 插件化。

不要在第一天就实现 Claude Code 的完整 Tool 接口。那个接口是大型产品演化后的结果，不是最小起点。