AI Agent / 系统课时

设计 Tool 接口

设计 Tool 接口

本课解决智能体调用外部能力时接口不统一的问题,通过设计标准 Tool 接口,让不同工具拥有一致的描述、参数校验、执行入口和错误返回方式。

学习目标

  • 理解智能体工具接口需要抽象哪些信息。
  • 设计包含 Schema 和执行逻辑的 Tool 结构。
  • 掌握工具调用结果与错误处理方式。

为什么需要统一 Tool 接口

智能体通常需要访问文件系统、Git、终端、数据库等不同能力。如果每个工具都使用独立调用方式,Agent Runtime 会充满特殊判断,难以扩展新的工具。

统一接口的目标是让模型只关心工具描述和输入格式,让运行时负责参数校验、执行调度和结果处理。

Tool 接口组成

一个完整工具通常包含四部分:

  • name:工具唯一名称,供模型选择调用。
  • description:工具用途说明,帮助模型理解适用场景。
  • inputSchema:定义输入参数格式并进行校验。
  • execute:真正执行工具逻辑并返回结果。

接口示例:

ts
interface ToolContext {
  requestId: string;
}

interface Tool<TInput = unknown, TResult = unknown> {
  name: string;
  description: string;
  inputSchema: object;
  execute(input: TInput, context: ToolContext): Promise<TResult>;
}

const readFileTool: Tool = {
  name: "read_file",
  description: "读取指定路径文件内容",
  inputSchema: {
    type: "object",
    required: ["path"]
  },
  async execute(input, context) {
    return {
      requestId: context.requestId,
      content: "file content"
    };
  }
};

预期结果

text
创建一个包含名称、描述、输入规则和执行方法的工具对象。

工具调用流程

模型生成工具调用请求后,Runtime 根据工具名称找到对应实现。执行前先校验参数,避免模型生成错误字段导致不可预测行为。执行完成后,将结果转换成统一格式返回给 Agent。

典型链路如下:

用户任务 → 模型选择工具 → 参数校验 → 执行工具 → 返回结果 → 继续推理。

设计执行结果和错误结构

工具返回值应该保持稳定,成功和失败都需要明确表达状态,方便 Runtime 处理。

ts
interface ToolResult {
  success: boolean;
  data?: unknown;
  error?: {
    code: string;
    message: string;
  };
}

function createErrorResult(message: string): ToolResult {
  return {
    success: false,
    error: {
      code: "TOOL_FAILED",
      message
    }
  };
}

预期结果

text
返回 success=false 的标准工具失败结果。

Tool 接口的边界

Tool 接口负责描述能力和执行协议,不应该把复杂业务流程全部塞入工具内部。例如文件修改流程中的计划生成、审批和回滚属于 Agent Runtime 或其他模块职责。

良好的工具设计应该满足可发现、可校验、可执行、可记录四个条件,使智能体能够安全扩展新的外部能力。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计 Tool 接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通