跳转到主要内容

​
工具概览

工具使 AI Agent 能够通过统一接口与外部世界交互。该框架包括用于常见任务的内置工具,并支持专门用例的自定义工具开发。

​
什么是工具?

工具是 AI Agent 可以调用以与外部系统交互并执行特定任务的可编程函数。它们将 Agent 能力扩展到文本生成之外,包括文件操作、代码执行、网页浏览和系统交互。

​
关键特征

  • 面向操作: 工具执行特定操作而不是生成响应
  • 类型安全: 完整的类型支持和运行时模式验证
  • 标准化接口: 所有工具实现一致的基础接口
  • 错误处理: 带有分类错误类型的结构化错误响应
  • 上下文感知: 工具可以访问执行上下文并维护状态

​
Agent 如何使用工具

  1. 推理: Agent 分析用户请求并确定需要哪些工具
  2. 选择: Agent 根据描述和模式选择适当的工具
  3. 调用: Agent 使用经过验证的参数调用工具
  4. 观察: Agent 处理工具结果和错误响应
  5. 响应: Agent 将工具输出合并到最终响应中

​
工具类别

​
内置工具

用于常见 Agent 任务的全面内置工具集:

文件系统工具

使用可配置工具包完成文件和目录操作

代码执行工具

安全的多语言代码执行,包含沙箱和本地选项

命令行工具

基于操作符架构的 Shell 命令执行

MCP 工具

用于外部工具生态系统的模型上下文协议集成

​
自定义工具

构建针对您特定用例的专门工具:

函数工具

从 TypeScript/JavaScript 函数创建工具

连接自定义 MCP 服务

用于外部工具生态系统的模型上下文协议集成

​
工具架构

工具遵循一致的架构模式:
  • 沙箱: 工具在隔离环境中执行以确保安全
  • 模式验证: 输入参数在执行前根据定义的模式进行验证
  • 错误处理: 结构化错误响应使 Agent 能够优雅地处理失败
  • 上下文集成: 工具可以访问和修改执行上下文
  • 标准化输出: 所有工具的一致结果格式简化了 Agent 处理

​
工具结果

所有工具返回标准化的结果结构以实现一致的错误处理: 
from typing import Optional, Any
from dataclasses import dataclass

@dataclass
class ToolResult:
    success: bool                    # 操作成功状态
    data: Optional[Any] = None      # 工具输出(成功时)
    error: Optional[str] = None     # 错误消息(失败时)
    error_type: Optional[str] = None # 分类的错误类型
    execution_time: Optional[float] = None # 执行持续时间(毫秒)

​
快速开始

​
使用内置工具

内置工具为文件操作和代码执行等常见任务提供即用型功能。有关详细文档,请参见 内置工具。

​
创建自定义工具

创建针对您特定需求的自定义工具。有关全面指南,请参见 自定义工具开发。

​
与 Agent 集成

工具通过其配置集成到 Agent 中。Agent 可以根据其描述和模式自动发现和使用可用工具。有关详细示例,请参见 Agent 集成。

​
下一步

Agent 集成

将工具与 Agent 集成

内置工具

探索全面的内置工具集

自定义工具开发

学习为您的用例构建自定义工具

API 参考

详细的 API 文档和示例