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 或其他模块职责。
良好的工具设计应该满足可发现、可校验、可执行、可记录四个条件,使智能体能够安全扩展新的外部能力。
按自己的节奏,确认真正理解。