概述

OpenAI Agents SDK 是一个轻量级的 Python 库，用于构建和编排 AI Agent。与 LangChain 不同，它专注于 Agent 编排的核心能力，提供简洁的 API 和强大的多 Agent 协作机制（handoff）。

前置条件

• Python 3.10+
• OpenAI API Key
• 安装：pip install openai-agents

核心用法

1. 创建基础 Agent

from agents import Agent

agent = Agent(
    name="Math Tutor",
    instructions="你是一个数学导师，清晰地解释数学概念和计算步骤。"
)

2. 定义 Function Tool

使用 @function_tool 装饰器定义工具：

from agents import function_tool, Agent, Runner
import asyncio

@function_tool
def calculate(expression: str) -> str:
    """执行数学表达式计算
    
    Args:
        expression: 数学表达式，如 "2 + 3 * 4"
    """
    try:
        result = eval(expression)
        return str(result)
    except Exception as e:
        return f"计算错误: {e}"

# 创建带工具的 Agent
math_agent = Agent(
    name="Calculator",
    instructions="你是一个计算器助手。使用 calculate 工具进行数学运算。",
    tools=[calculate]
)

# 运行 Agent
async def main():
    result = await Runner.run(math_agent, "计算 25 * 4 + 10 的值")
    print(result.final_output)

asyncio.run(main())

3. 多 Agent 协作（Handoff）

from agents import Agent, Runner
import asyncio

# 定义专家 Agent
coder = Agent(
    name="Coder",
    instructions="你是一个 Python 编程专家，帮助用户编写代码。"
)

researcher = Agent(
    name="Researcher", 
    instructions="你是一个研究助手，帮助用户查找和分析信息。"
)

# 分类 Agent（路由器）
triage = Agent(
    name="Triage",
    instructions="分析用户问题，将其分配给合适的专家。",
    handoffs=[coder, researcher]
)

# 运行
async def main():
    result = await Runner.run(triage, "帮我写一个快速排序算法")
    print(f"回答: {result.final_output}")
    print(f"处理者: {result.last_agent.name}")

asyncio.run(main())

4. 带上下文的 Tool 定义

from agents import function_tool, Agent, Runner
import asyncio

@function_tool
def search_knowledge_base(query: str, category: str = "general") -> str:
    """在知识库中搜索相关信息
    
    Args:
        query: 搜索关键词
        category: 知识分类，默认为 general
    """
    # 模拟知识库搜索
    return f"在 {category} 分类中找到关于 '{query}' 的结果"

assistant = Agent(
    name="Knowledge Assistant",
    instructions="你是一个知识助手。使用知识库搜索工具回答用户问题。",
    tools=[search_knowledge_base]
)

async def main():
    result = await Runner.run(
        assistant, 
        "查找关于 Python 异步编程的资料"
    )
    print(result.final_output)

asyncio.run(main())

完整示例：任务助手

from agents import Agent, Runner, function_tool
import asyncio

@function_tool
def create_task(title: str, priority: str = "medium") -> str:
    """创建新任务
    
    Args:
        title: 任务标题
        priority: 优先级 (high/medium/low)
    """
    return f"已创建任务: [{priority}] {title}"

@function_tool
def list_tasks() -> str:
    """列出所有任务"""
    return "当前任务:\n1. [high] 完成报告\n2. [medium] 回复邮件"

task_agent = Agent(
    name="Task Manager",
    instructions="你是一个任务管理助手，帮助用户创建和管理任务。",
    tools=[create_task, list_tasks]
)

async def main():
    result = await Runner.run(task_agent, "创建一个高优先级的代码评审任务")
    print(result.final_output)

asyncio.run(main())

常见问题

Q1: @function_tool 的 description 字段从哪里来？

• 使用 docstring（文档字符串）的格式编写
• Args 部分定义参数说明
• 函数名会自动作为工具名

Q2: Handoff 和 Tools 的区别是什么？

• Tools 是 Agent 可调用的外部能力（函数）
• Handoff 是 Agent 之间的任务转移
• Handoff 会传递完整的对话上下文

Q3: 如何调试 Agent 的执行过程？

• 在 OpenAI 控制台查看 Trace viewer
• 使用 Runner.run() 的 verbose=True 参数
• 检查 result.last_agent 了解最终处理者

参考资料

• OpenAI Agents SDK 官方文档
• GitHub 仓库
• 快速入门指南