GPT-5 原生工具 Agent

源文件：chapter1/search-codegen/README.md

GPT-5 原生工具 Agent

一个进阶 AI Agent，通过 OpenRouter API 调用 GPT-5 的原生 web_search 和 code_interpreter 工具，复刻生产环境 Go 代码中的实现方式。该 Agent 能联网搜索实时信息并运行代码进行深度分析，借助 GPT-5 的内置能力，实现"搜索 → 阅读 → 分析 → 再搜索"的 Deep Research 循环。

🌟 特性

• 原生工具支持：通过 OpenRouter 专属格式调用 GPT-5 内置的 web_search 与 code_interpreter 工具
• OpenRouter 集成：与生产环境 Go 实现完全一致的 API 格式
• 网络搜索能力：
  • 联网搜索实时信息
  • 可配置搜索上下文规模与用户所在地区
• 推理力度档位：支持 low、medium、high 三档推理强度
• 交互式 CLI：界面友好，带推理控制
• Agent 链式调用：可串联多个请求以构建复杂工作流
• 完整测试套件：覆盖各类使用场景

📋 前置条件

• Python 3.8 或更高版本
• OpenRouter API Key（在 https://openrouter.ai/keys 获取）
• 联网环境（用于网络搜索功能）

🚀 快速开始

1. 安装

# Clone or navigate to the project directory
cd projects/week1/search-codegen

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp env.example .env

# Edit .env and add your OpenRouter API key
# OPENROUTER_API_KEY=sk-or-v1-your-key-here
​

2. 配置

编辑 .env 文件：

OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
MODEL_NAME=openai/gpt-5.6-sol
DEFAULT_TEMPERATURE=0.3
DEFAULT_MAX_TOKENS=4000
​

本实验以 OpenRouter 作为主后端，因此无需兜底。同一个 OPENROUTER_API_KEY
还可作为 chapter1 其他实验（context、learning-from-experience、
web-search-agent）的通用兜底——当它们缺少直连提供方的 key 时即可启用。

3. 运行 Agent

交互模式（推荐）

python main.py
​

单次请求模式

python main.py --mode single --request "Search for latest AI news and analyze the trends"
​

运行测试

python main.py --mode test
​

命令行参数（CLI）

本实验对应书中 实验 1.3 ★：GPT-5.6 原生 Deep Research 能力，演示模型如何自主组合 web_search（网络搜索）与 code_interpreter（代码解释器）两个原生工具，完成"搜索 → 阅读 → 分析 → 再搜索"的迭代研究。运行 python main.py --help 查看中文帮助。

Reasoning Effort 与 Verbosity 是书中强调的两个 GPT-5 原生参数：前者调节思考深度，后者控制回答详略。二者都已通过 CLI 暴露，并原样注入到发送给模型的请求体中。

示例：

# 书中示例任务：东盟 10 国首都最近的一对（搜索坐标 + 代码计算大圆距离）
python main.py --mode single --request "东盟 10 国首都之间距离最近的两个首都是？给出详细分析推理过程。" --reasoning high

# 书中示例任务：比特币技术分析（多源实时数据 + 指标计算）
python main.py --mode single --request "搜索比特币最近一个月走势，计算 MA、RSI、MACD 等技术指标" --verbosity high --output btc.json
​

离线查看请求体（dry-run）

无需 API Key 即可查看"模型即 Agent"范式下真正发送给模型的请求——包括两个原生工具的定义、reasoning 与 verbosity 参数。这直观展示了原生工具调用的结构，也便于调试：

python main.py --dry-run --request "东盟 10 国首都之间距离最近的两个首都是？" --reasoning high --verbosity high
​

输出的请求体中，tools 数组同时包含 web_search 和 code_interpreter，reasoning.effort 与 verbosity 反映所选档位——正是书中所述的原生工具 + 推理/详略参数的组合。

🛠️ 用法示例

示例 1：仅网络搜索

from agent import GPT5NativeAgent
from config import Config

agent = GPT5NativeAgent(
    api_key=Config.OPENROUTER_API_KEY,
    base_url=Config.OPENROUTER_BASE_URL
)

result = agent.process_request(
    "What are the latest developments in quantum computing?",
    use_tools=True
)
print(result["response"])
​

示例 2：高推理强度的网络搜索

result = agent.process_request(
    "Analyze the implications of quantum computing on encryption",
    use_tools=True,
    reasoning_effort="high"
)
​

示例 3：带分析的网络搜索

result = agent.process_request(
    """Search for current Bitcoin price and market data,
    then analyze the volatility and predict trends""",
    use_tools=True,
    reasoning_effort="medium"
)
​

示例 4：搜索 + 分析方法

analysis_code = """
import statistics
# Process search results
prices = [45000, 46000, 45500, 47000, 46500]
volatility = statistics.stdev(prices)
print(f"Volatility: ${volatility:.2f}")
"""

result = agent.search_and_analyze(
    topic="Current cryptocurrency market conditions",
    analysis_code=analysis_code
)
​

📁 项目结构

search-codegen/
├── agent.py          # Core GPT-5 agent implementation
├── config.py         # Configuration management
├── main.py           # Interactive CLI and entry point
├── test_agent.py     # Comprehensive test suite
├── env.example       # Environment variables template
├── requirements.txt  # Python dependencies
└── README.md        # This file
​

🔧 OpenRouter 工具格式

web_search 工具结构

web_search 工具使用 OpenRouter 专属格式：

{
    "type": "web_search",
    "search_context_size": "medium",
    "user_location": {
        "type": "approximate",
        "country": "US"
    }
}
​

推理配置

支持可配置的推理力度：

• low：快速响应，基础推理
• medium：在推理深度与响应时间之间取得平衡
• high：针对复杂查询的深度推理

🧪 测试

测试套件包含完整的测试用例：

1. 基础网络搜索：测试联网搜索能力
2. 带分析的网络搜索：搜索 + 分析洞见
3. 复杂研究：高推理强度的深度研究
4. 搜索 + 代码：搜索配合代码生成
5. 推理档位对比：对比不同推理力度
6. search_and_analyze 方法：便捷方法测试
7. Agent 链：多步工作流

运行指定测试：

# Run all tests
python test_agent.py

# Run specific test
python main.py --mode test --test basic
​

可用测试名：basic、analysis、complex、code、reasoning、search_analyze、chain

🎯 交互式 CLI 命令

在交互模式下，可用以下命令：

• /help - 显示帮助信息
• /clear - 清空对话历史
• /history - 显示对话历史
• /tools - 开启/关闭工具
• /search - 进入网络搜索模式
• /code - 进入代码生成模式
• /analyze - 搜索 + 分析的组合模式
• /config - 显示当前配置
• /reasoning - 设置推理力度档位
• /exit - 退出程序

⚙️ 配置选项

🤝 API 集成

本 Agent 通过 OpenRouter API 调用 GPT-5。OpenRouter 提供：

• 面向多模型的统一 API
• 提升可靠性的自动兜底
• 用量跟踪与分析
• 有竞争力的定价

了解更多见 OpenRouter 文档。

📊 Token 用量

Agent 会跟踪每次请求的 token 用量：

• Prompt tokens：输入 token 数
• Completion tokens：输出 token 数
• Total tokens：合并用量

可按 OpenRouter 定价估算成本：

• 输入：每百万 token $1.25
• 输出：每百万 token $10

🐛 故障排查

API Key 问题

# Verify your API key starts with 'sk-or-'
echo $OPENROUTER_API_KEY
​

限流

若遇到限流，可在 .env 中调整 RATE_LIMIT_RPM。

工具错误

• 调用 process_request 时确保 use_tools=True
• 设置 tool_choice="required" 以强制使用工具

📝 许可证

本项目是 AI Agent 实战训练营课程的一部分。

🔗 资源

• OpenRouter GPT-5 API
• OpenAI 原生工具文档
• OpenRouter 文档
• API Keys

👉 支持

如遇问题或疑问：

1. 查阅故障排查章节
2. 查看测试用例了解使用示例
3. 参考 OpenRouter 文档

基于 OpenRouter API 的 GPT-5 原生能力构建。