使用 OpenAI Agents SDK 在 Python 中构建你的第一个 AI 代理
内容提要
本文介绍如何用 OpenAI Agents SDK 在 Python 中构建 AI 代理。代理能自主调用工具并多步执行，区别于普通 LLM。教程依次演示：创建研究代理并接入 WebSearchTool 实现联网搜索；用 @tool 装饰器添加自定义计算函数，由 SDK 自动生成工具模式；用 SQLiteSession 实现持久对话记忆；整合为带错误处理和连续对话的完整程序。SDK 默认启用追踪，便于调试工具调用。核心思路是为代理配置合适工具，由 SDK 管理执行循环。
延伸解读
代理与普通LLM应用的关键区别
文章指出，普通LLM应用是“提示—模型—响应”的线性流程，而AI代理增加了工具和执行循环：代理可自主决定是否先调用工具（如搜索、计算），再由Runner管理多步执行直至给出最终答案。这种“推理—行动—再推理”的能力，使代理能处理需要外部信息或计算的任务，而不仅限于生成文本。
自定义工具如何被SDK自动集成
通过@tool装饰器定义Python函数后，SDK会自动提取函数名、参数类型提示和文档字符串，生成模型可理解的工具模式，无需手动编写JSON Schema或工具调用循环。文章强调，清晰的文档字符串能帮助模型判断何时使用该工具，因此编写工具时应注重说明其用途和适用场景。
会话记忆的持久化与扩展选项
使用SQLiteSession可将对话历史保存在文件中，即使程序重启也能恢复上下文，使代理能理解指代和连续对话。文章提到，对于更大规模的应用，SDK还提供Redis、SQLAlchemy和MongoDB等会话后端，方便根据实际需求替换存储方案，而无需改动代理逻辑。
追踪与错误处理对调试的价值
SDK默认启用追踪，可在OpenAI仪表板中查看模型调用、工具使用和交接等步骤，有助于理解代理如何得出答案、选择了哪些工具以及问题出在哪里。完整示例中还加入了API密钥检查、异常捕获和会话关闭等错误处理，使代理在连续对话中更稳健，便于定位工具调用行为的问题。
Q&A
OpenAI Agents SDK 里的 AI 代理和普通 LLM 应用有什么区别？
普通 LLM 应用流程是提示词→模型→响应，模型只生成文本就停止。AI 代理则增加了工具和执行循环：用户→代理→按需调用工具→代理→最终响应。代理能自主决定是否需要先执行搜索、调用 Python 函数或检索记忆等动作，并由 Runner 自动管理多步执行直到给出最终答案。
怎么用 OpenAI Agents SDK 快速创建一个能联网搜索的代理？
安装 openai-agents 包并设置 OPENAI_API_KEY 环境变量后，用 Agent 类创建代理，在 tools 参数中传入 WebSearchTool()，再用 Runner.run_sync(agent, 问题) 运行即可。WebSearchTool 是托管工具，模型会自行决定何时需要最新信息，无需手动调用搜索 API。
如何给代理添加自定义的 Python 函数作为工具？
用 @tool 装饰器定义函数（如 calculate_total），写好类型提示和 docstring，然后把该函数加入 Agent 的 tools 列表。SDK 会自动根据函数名、参数、类型提示和 docstring 生成工具模式，模型就能理解并调用它，无需手动编写 JSON schema 或工具调用循环。
怎样让代理记住之前的对话内容？
使用 SQLiteSession 创建会话，例如 SQLiteSession("user_1", "conversations.db")，然后在每次 Runner.run_sync 调用时传入 session 参数。这样后续请求会自动携带之前的对话历史，代理能理解上下文指代；由于是文件型 SQLite 数据库，历史在程序重启后也能保留。大型应用还可选用 Redis、SQLAlchemy、MongoDB 等会话后端。
Agents SDK 的追踪功能有什么用？
SDK 默认启用追踪，可以检查模型调用、工具使用、交接等步骤。在 OpenAI 仪表板中查看这些追踪记录，能了解代理如何得出答案、选择了哪些工具、问题出在哪里，特别适合调试工具调用行为和优化代理指令。
构建完整代理程序时如何处理错误和退出？
完整示例中，先检查 OPENAI_API_KEY 是否设置，未设置则退出。主循环用 try/except 捕获 input 的 EOFError 和 KeyboardInterrupt 以正常退出，支持输入 exit/quit 结束；对 Runner.run_sync 的异常单独捕获并打印错误类型和消息后继续循环；最后在 finally 中关闭 session。
