OpenAI Agents SDK Python 实用指南：30 分钟跑通你的第一个多智能体工作流
【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python
OpenAI Agents SDK 是一个轻量级的多智能体工作流框架，核心就是 Agent 加 Runner 两个对象：你负责描述每个智能体"做什么、能用什么"，框架负责调用模型、执行工具、在多个智能体之间流转控制权。它默认对接 OpenAI 的 Responses 与 Chat Completions API，也兼容 100 多家其他模型提供商，适合想快速搭建客服分流、内容生产、研究助手等 AI 应用的开发者。
三步完成安装：环境搭建与配置验证
先说结论：装它只需要三条命令——建虚拟环境、装包、配密钥，前提是 Python 3.10 及以上。如果你之后要做语音应用，追加[voice]可选组；要多端共享会话记忆，追加[redis]可选组。
下面这段命令可以整体复制到终端执行（最后一行的密钥换成你自己的）：
python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install openai-agents export OPENAI_API_KEY=sk-...怎么算装好了？在激活的虚拟环境里运行python -c "import agents"，没有任何报错输出就代表成功。也可以直接跳进下一节，把最小示例跑起来，能拿到模型回复即验证通过。
最小可运行示例：第一个 Agent 跑起来
这个框架的运行方式非常直白：Agent是一个"配好提示词和能力的模型"，Runner负责真正发起对话并跑完整个流程，最后把结果装进result返回给你。下面的示例用同步方式调用，写完直接能跑：
from agents import Agent, Runner agent = Agent(name="Assistant", instructions="You are a helpful assistant.") result = Runner.run_sync(agent, "Write a haiku about recursion in programming.") print(result.final_output)运行后终端会打印模型生成的俳句文本，这个文本来自result.final_output。result里还藏着更多细节：result.new_items是按时间顺序记录的本轮所有事件（用户输入、模型回复、工具调用），result.last_agent则是最终由哪个智能体收尾。做调试时，这两个字段最常用。
动手前必懂的三个名词：交接、护栏与会话
交接（Handoff）：把当前对话转给某个专家智能体接管。说白了就像前台接待——总机听完你的问题，判断属于哪个部门，然后把电话转过去。框架把这个动作包装成一次工具调用，模型自己决定何时该转、转给谁，转出去之后控制权就归对方了。
护栏（Guardrail）：给输入或输出加的一道检查。典型用法是：用一个便宜快速的模型先审用户的请求，一旦触发"绊线"就直接报错拦截，避免昂贵的正式模型白白烧钱。输入护栏跑在对话开始前，输出护栏跑在最终答案产出后。
会话（Session）：一个按会话 ID 存取对话历史的记忆盒。每次运行时框架自动把历史读出来拼在输入前面，跑完再把新消息写回去，你不用自己拼"上下文"。这三者的完整参数，可以翻 docs/handoffs.md 和 docs/sessions/index.md 对照着看。
🤝 多智能体协作：用最小代码实现智能体交接
多个智能体协作最简单的形态就是"一个分诊 + 几个专家"。分诊智能体只负责判断，专家智能体各管一摊，交接关系通过handoffs参数声明即可，谁都不用手动传消息。
下面这段最小示例：总机根据语言把对话转给对应的专家，运行完会打印最终回答和收尾智能体的名字：
import asyncio from agents import Agent, Runner spanish = Agent(name="Spanish", instructions="You only speak Spanish.") english = Agent(name="English", instructions="You only speak English.") triage = Agent( name="Triage", instructions="Hand off to the matching language agent.", handoffs=[spanish, english], ) async def main(): result = await Runner.run(triage, "Hola, ¿cómo estás?") print(result.final_output, "| by", result.last_agent.name) asyncio.run(main())输出会是西班牙语的问候语，后面跟着| by Spanish——last_agent就是验证交接是否真正发生的最好办法。如果它显示Triage，说明模型根本没转出去，这时可以检查分诊智能体的提示词和专家的handoff_description（给路由智能体看的一句话说明）。
让 Agent 有记忆：长对话的会话管理
没有会话时，每轮对话都是"失忆"的：你问"金门大桥在哪个城市"，它答"旧金山"；紧接着问"在哪个州"，它不知道你在说哪座桥。接上会话后，同样的两句话就能连贯回答了。
做法很简单：新建一个 SQLiteSession 并给一个会话 ID，然后把session=传进每次Runner.run调用。以"金门大桥在哪个城市"接"它在哪个州"为例，第二轮会直接答出"California"，因为框架在每次运行前自动读出了第一轮的完整历史。本地开发用内置的 SQLiteSession 就够，它把历史存在一个本地数据库文件里，零配置；进阶版本 AdvancedSQLiteSession 还支持从任意一条消息分叉出对话分支、统计每轮 token 用量。
走向生产：追踪、调优与部署选型
SDK 自带运行追踪：每次运行的每一步——模型调用、工具执行、交接跳转——都会按时间线记录。用 OpenAI 平台的账号登录后，在 dashboard 的 Traces 页面能看到整棵调用树，右侧还能展开查看每次请求的耗时、token 数和模型配置。
调优方面，几条被反复验证的经验值得记住：提示词的质量决定上限，把工具清单、使用场景和参数要求写具体，比换模型更管用；多盯着追踪记录找问题出在哪一步，改完再看一眼确认；把智能体放进循环里让它批评自己的输出，往往能发现人工没注意到的毛病；最后，别让一个"全能智能体"扛所有事，按任务拆出专门负责单项的专家，协作效果通常更好。
部署选型上按记忆需求走：单机或原型阶段用 SQLiteSession；多个 worker 或微服务需要共享同一份对话历史时，装上[redis]组后改用 RedisSession，通过 URL 接入共享实例即可；如果工作流涉及长时间运行、中途等待人工审批，可以把它挂到 Temporal 这类持久化工作流引擎上执行。
【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
