OpenAI Agents SDK 从零到大师学习指南

第一章：OpenAI Agents SDK 概览

1.1 什么是 OpenAI Agents SDK？

1.2 为何选择 Agents SDK？

1.3 Agents SDK 的核心概念

• Agent (代理)：Agent 是 Agents SDK 的核心，本质上是一个配置了指令和工具的 LLM 。开发者可以为 Agent 设置系统提示等指令，指定其可以使用的工具，以及定义在需要时可以将任务移交给哪些其他 Agent 。Agent 还可以配置可选的输入/输出 Guardrails 和更高级的模型参数 。

• Tool (工具)：工具是 Agent 可以调用的外部功能，用于执行诸如获取数据、运行代码或与外部 API 交互等特定操作 。工具可以是同步或异步的 Python 函数 ，Agents SDK 允许开发者将任何 Python 函数轻松地转化为工具供 Agent 使用 。

• Handoff (移交)：Handoff 是一种机制，允许一个 Agent 将任务的控制权转移给另一个 Agent，以便更专业地处理特定的子任务 。这对于构建需要多个 Agent 协同工作的复杂系统非常有用 。

• Guardrail (护栏)：Guardrails 是一组安全检查措施，可以在 Agent 运行过程中并行执行，用于验证用户输入和 Agent 的输出是否符合预期的安全和合规标准 。Guardrails 可以帮助防止恶意使用和意外后果，确保 Agent 的行为在开发者设定的范围之内 。

• Tracing (追踪)：Tracing 是 Agents SDK 内置的功能，用于记录 Agent 运行过程中的每一个步骤，包括 LLM 的调用、工具的调用以及 Agent 之间的移交等 。Tracing 对于调试、分析和监控 Agent 的行为至关重要，开发者可以通过 Tracing 信息了解 Agent 的决策过程，并进行性能优化 。

• Context (上下文)：Context 是一个可以在 Agent 运行过程中存储和共享数据的可变对象 。开发者可以创建任何 Python 对象作为 Context，并在 Agent 运行的各个阶段（包括工具函数中）访问和修改 Context 对象中的数据，这对于维护会话状态和在多个步骤之间传递信息非常有用 。

• Output Types (输出类型)：Agents SDK 允许开发者指定 Agent 最终输出的结构。虽然默认情况下 Agent 的输出是自由格式的文本，但开发者可以定义特定的 Python 类型（例如 Pydantic 模型）来确保 Agent 返回结构化的 JSON 格式数据 。

1.4 Agents SDK 的架构概览

第二章：快速开始：环境搭建与基础 Agent

2.1 环境搭建

mkdir my_project
cd my_project
python -m venv .venv

source .venv/bin/activate

.venv\Scripts\activate

pip install openai-agents

export OPENAI_API_KEY=sk-...

set OPENAI_API_KEY=sk-...

2.2 创建你的第一个 Agent

from agents import Agent

agent = Agent(
    name="Math Tutor",
    instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
)

2.3 运行 Agent

from agents import Runner
import asyncio

async def main():
    result = await Runner.run(agent, "What is 2 + 2?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

第三章：工具的使用

3.1 什么是工具？

3.2 内置工具

• WebSearchTool (网页搜索工具)：允许 Agent 搜索互联网上的信息，获取最新的数据和知识 。

• FileSearchTool (文件搜索工具)：允许 Agent 在用户上传的文件中进行搜索，检索相关信息，这对于处理文档分析、知识库查询等场景非常有用 。

• ComputerTool (计算机使用工具)：允许 Agent 模拟用户在计算机上的操作，例如点击、滚动或输入文本，从而实现一些自动化的任务 。

3.3 Function Tools (函数工具)

3.4 Agents as Tools (将 Agent 作为工具)

3.5 处理工具中的错误

第四章：多 Agent 协作

4.1 Handoff 的概念与配置

4.2 运行多 Agent 工作流

4.3 Handoff 的输入和过滤器

4.4 示例：构建一个多语言客服系统

4.5 父 Agent (Triage Agent) 与子 Agent 的协作

第五章：保障安全：Guardrails 的应用

5.1 Guardrails 的重要性

5.2 输入 Guardrails

5.3 输出 Guardrails

5.4 实现自定义 Guardrails

第六章：上下文管理

6.1 Context 对象

6.2 本地 Context 与 Agent/LLM Context

6.3 在工具中使用 Context

from dataclasses import dataclass
from agents import RunContextWrapper, function_tool

@dataclass
class UserInfo:
    name: str
    uid: int

@function_tool
async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:
    return f"User {wrapper.context.name} is 47 years old"

6.4 在 Agent 指令中使用 Context

from dataclasses import dataclass
from agents import Agent, RunContextWrapper

@dataclass
class UserContext:
    name: str

def dynamic_instructions(context: RunContextWrapper[UserContext], agent: Agent[UserContext]) -> str:
    return f"The user's name is {context.context.name}. Help them with their questions."

user_info = UserContext(name="Alice")
triage_agent = Agent[UserContext](
    name="Triage agent",
    instructions=dynamic_instructions,
)

第七章：追踪与调试

7.1 Tracing 的作用与优势

7.2 查看 Traces

7.3 Spans 的概念

第八章：高级主题

8.1 Streaming (流式处理)

8.2 输出类型 (Output Types)

8.3 生命周期事件 (Lifecycle Events)

8.4 模型配置 (Model Configuration)

8.5 编排多个 Agent (Orchestrating Multiple Agents)

第九章：最佳实践

• 仔细记录函数 Schema：确保为 Agent 可以调用的每个工具函数编写清晰且详细的 Schema，以便 LLM 能够正确理解如何调用这些工具 。

• 使用严格的 Schema 检查：对于工具函数的参数，建议使用严格的 Schema 检查（例如 Pydantic 模型），以避免因参数不完整或格式错误导致的问题 。

• 应用适当的 Guardrails：根据应用程序的具体需求，应用合适的输入和输出 Guardrails，例如内容过滤、使用配额或数据验证等，以确保 Agent 的行为符合预期 。

• 彻底追踪复杂的工作流：对于涉及多个步骤或多个 Agent 的复杂工作流，务必启用并仔细查看 Tracing 信息，这对于调试和优化 Agent 的行为非常有帮助 。

• 考虑使用 Handoff 处理专业任务：如果应用程序涉及多个领域或需要处理多种语言，可以考虑使用 Handoff 将任务委派给更专业的子 Agent 。

• 参考 OpenAI 的 Prompt 工程最佳实践：遵循 OpenAI 提供的 Prompt 工程最佳实践，可以帮助开发者编写更有效的指令，引导 Agent 产生更符合预期的结果 。

• 监控 API 使用情况和成本：定期监控 API 的使用情况，并设置成本控制措施，以避免不必要的费用 。

第十章：实际应用案例

• AI 驱动的会计助手：可以自动化记账、查询最新的税务法规并生成财务报告 。

• 智能客服系统：能够调用 API 查询订单状态、解决客户支持问题，甚至可以处理退款或取消订单等操作 。

• 自动化研究助手：可以搜索最新的市场趋势、金融数据或法律更新，并生成研究报告 。

• 企业级知识管理系统：可以利用文件搜索工具，帮助员工快速找到他们需要的文档和信息 。

• 多语言翻译助手：可以根据用户输入的语言，自动将文本翻译成目标语言 。

• 内容创作助手：可以根据用户提供的关键词和要求，自动生成文章、博客帖子或其他类型的文本内容 。

第十一章：结论

引用的著作