教程3：工具使用代理

教程 3：工具使用代理

欢迎来到工具的世界！本教程将教你如何创建能够使用自定义函数和内置工具来执行特定任务的代理。正是在这里，你的代理才真正变得强大，具备在现实世界中采取行动的能力。

你将学到的内容

• 函数工具：创建自定义 Python 函数作为代理工具
• 内置工具：使用 OpenAI 预建的功能
• 工具集成：有效地将工具添加到代理中
• 工具执行：了解代理如何决定何时使用工具

核心概念：OpenAI 代理 SDK 中的工具

工具是你的代理可以调用的函数，用于执行特定任务。可以把它们想象成代理的“双手”——它们让代理能够：

• 执行计算和数据处理
• 搜索网络并获取实时信息
• 执行代码并分析数据
• 调用外部 API 和服务
• 访问数据库和文件系统

┌─────────────────────────────────────────────────────────────┐
│                    AGENT WITH TOOLS                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   INPUT     │───▶│    AGENT    │───▶│   OUTPUT    │     │
│  │ "Calculate  │    │  Reasoning  │    │ "Using the  │     │
│  │  compound   │    │ + Tool Use  │    │ calculator  │     │
│  │  interest"  │    │             │    │ tool: $..."│     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                             │                               │
│                             ▼                               │
│                      ┌─────────────┐                       │
│                      │    TOOLS    │                       │
│                      │ ┌─────────┐ │                       │
│                      │ │Calculator│ │                       │
│                      │ ├─────────┤ │                       │
│                      │ │Web Search│ │                       │
│                      │ ├─────────┤ │                       │
│                      │ │File I/O │ │                       │
│                      │ └─────────┘ │                       │
│                      └─────────────┘                       │
└─────────────────────────────────────────────────────────────┘
​

工具的类型

1. 函数工具

你创建的自定义 Python 函数：

@function_tool
def calculate_compound_interest(principal: float, rate: float, time: int) -> float:
    """Calculate compound interest"""
    return principal * (1 + rate) ** time
​

2. 内置工具

OpenAI 提供了强大的预建工具：

• WebSearchTool：搜索网络以获取最新信息
• CodeInterpreterTool：安全地执行 Python 代码
• FileSearchTool：搜索上传的文件

教程概述

本教程包含三个聚焦的工具集成示例：

1. 函数工具 (3_1_function_tools/)

• Custom Python functions as tools
• @function_tool decorator usage
• Basic mathematical and utility functions

2. Built-in Tools (3_2_builtin_tools/)

• OpenAI's WebSearchTool integration
• CodeInterpreterTool for computations
• Pre-built tool capabilities

3. Agents as Tools (3_3_agents_as_tools/)

• 将代理用作工具进行编排
• 专门的代理协调
• 高级代理组合模式

项目结构

3_tool_using_agent/
├── README.md                    # This file - concept explanation
├── requirements.txt             # Dependencies
├── 3_1_function_tools/          # Custom function tools
│   ├── __init__.py
│   ├── tools.py                # Custom tool definitions
│   └── agent.py                # Agent with function tools (25 lines)
├── 3_2_builtin_tools/           # Built-in tools integration
│   ├── __init__.py
│   └── agent.py                # Agent with built-in tools (30 lines)
├── 3_3_agents_as_tools/         # Agents as tools pattern
│   ├── __init__.py
│   ├── agent.py                # Basic agent orchestration (40 lines)
│   └── advanced_agent.py       # Custom agent tools with Runner config
├── app.py                      # Streamlit web interface (optional)
└── env.example                 # Environment variables template
​

学习目标

完成本教程后，你将理解：

• ✅ 如何使用 @function_tool 创建自定义函数工具
• ✅ 如何集成 WebSearch 和 CodeInterpreter 等内置工具
• ✅ 代理如何决定何时以及如何使用工具
• ✅ 工具设计与集成的最佳实践
• ✅ 错误处理与工具验证

开始使用

1. 安装 OpenAI 代理 SDK：

   pip install openai-agents
   ​

2. 安装依赖：

   pip install -r requirements.txt
   ​

3. 设置环境变量：

   cp env.example .env
   # Edit .env and add your OpenAI API key
   ​

4. 测试计算器代理：

   python calculator_agent.py
   ​

5. 测试研究代理：

   python research_agent.py
   ​

6. 测试数据分析代理：

   python data_analysis_agent.py
   ​

7. 运行交互式 Web 界面：

   streamlit run app.py
   ​

示例用例

代理作为工具

尝试这些编排请求：

• “将‘Hello, how are you?’翻译成西班牙语和法语”
• “用所有可用语言说‘Good morning’”
• “研究人工智能并撰写专业总结”

研究代理

尝试这些信息请求：

• “关于人工智能的最新消息是什么？”
• “查找 2024 年可再生能源趋势的信息”
• “搜索 Python 编程最佳实践”

数据分析代理

尝试这些数据请求：

• “分析这个 CSV 数据：[粘贴一些数据]”
• “创建销售数据的简单柱状图”
• “计算这个数据集的统计指标”

关键工具模式

1. 简单函数工具

@function_tool
def add_numbers(a: float, b: float) -> float:
    """Add two numbers together"""
    return a + b
​

2. 带验证的复杂函数工具

@function_tool
def get_weather(city: str, units: str = "metric") -> str:
    """Get current weather for a city"""
    if not city.strip():
        return "Error: City name cannot be empty"
    
    # API call logic here
    return f"Weather data for {city}"
​

3. 代理作为工具的集成

from agents import Agent

# Define specialized agents
translator = Agent(name="Translator", instructions="Translate text")

# Use agent as a tool
orchestrator = Agent(
    name="Orchestrator",
    instructions="Coordinate translation tasks",
    tools=[
        translator.as_tool(
            tool_name="translate_text",
            tool_description="Translate user's message"
        )
    ]
)
​

工具设计最佳实践

1. 清晰的文档字符串：工具需要描述性的文档字符串，以便代理理解其用途
2. 类型提示：始终为参数和返回值使用正确的类型提示
3. 错误处理：优雅地处理错误并返回有意义的消息
4. 简单参数：保持工具参数简单且定义明确
5. 单一职责：每个工具应只做好一件事

下一步

完成本教程后，你将准备好：

• 教程 4：Runner 执行方法 - 掌握不同的执行模式
• 教程 5：上下文管理 - 管理跨交互的状态
• 教程 6：防护措施与验证 - 添加安全性和验证功能

故障排除

• 工具未被调用：检查你的工具文档字符串是否清楚地描述了其用途
• 类型错误：验证参数类型是否与函数签名匹配
• 导入问题：确保你已导入 function_tool 装饰器
• API 错误：对于内置工具，检查你的 OpenAI API 密钥和权限

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文语言版本的文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。