openai-agents-python 快速上手从零构建你的第一个多智能体工作流【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本指南以 openai-agents-python 官方快速入门为核心带你完成从环境搭建、安装 SDK、配置 API Key到创建并运行第一个 Agent、为 Agent 挂载工具再到通过 Handoff交接编排多 Agent 协作的完整链路。读完本文你将掌握Agent、Runner、RunResult、tool装饰器与handoffs的核心用法并理解底层运行循环的源码原理能够立即动手写出可运行的第一个智能体应用。一、环境准备创建项目与虚拟环境这一步只需执行一次。打开终端创建项目目录并建立 Python 虚拟环境mkdir my_project cd my_project python -m venv .venvpython -m venv .venv会在my_project目录下生成一个名为.venv的独立 Python 环境避免与系统全局环境相互污染依赖版本。激活虚拟环境每次打开新的终端会话都需要重新激活虚拟环境。macOS 或 Linuxsource .venv/bin/activateWindows.venv\Scripts\activate激活后终端提示符前会出现(.venv)前缀此时pip、python等命令均指向虚拟环境内的解释器。二、安装 Agents SDK 与配置 OpenAI API Key安装 SDK在激活的虚拟环境中安装 Agents SDKpip install openai-agents如果你使用 uv 管理项目依赖也可以执行uv add openai-agents其余包管理器同理。安装完成后即可在 Python 中from agents import Agent, Runner。设置 OpenAI API KeySDK 运行 Agent 时需要调用模型服务因此必须先配置 API Key。若你还没有 Key可按 OpenAI 官方指引创建并导出。以下命令仅对当前终端会话生效推荐做法避免 Key 写入历史记录或配置文件。macOS 或 Linuxexport OPENAI_API_KEYsk-...Windows PowerShell$env:OPENAI_API_KEY sk-...Windows Command Promptset OPENAI_API_KEYsk-...说明OPENAI_API_KEY是 SDK 读取的默认环境变量名配置完成后当前会话中的 Agent 即可使用默认的 OpenAI 模型。三、创建你的第一个 AgentAgent 是 SDK 的核心抽象。它通过instructions指令、name名称以及可选的模型等配置来定义行为from agents import Agent agent Agent( nameHistory Tutor, instructionsYou answer history questions clearly and concisely., )从源码看Agent的基类AgentBase定义于 src/agents/agent.py声明了name、handoff_description、tools、mcp_servers等核心字段nameAgent 的名称同时会出现在追踪trace与运行结果中handoff_descriptionAgent 被其他 Agent 作为 Handoff 目标时提供给路由 LLM 的描述文本帮助其判断何时该委派tools该 Agent 可调用的工具列表mcp_servers可挂载的 MCPModel Context Protocol服务器列表。这里的instructions是系统提示词的核心内容直接决定了 Agent 的人设与回答风格。四、运行你的第一个 Agent使用Runner执行 Agent并获取一个RunResult返回对象import asyncio from agents import Agent, Runner agent Agent( nameHistory Tutor, instructionsYou answer history questions clearly and concisely., ) async def main(): result await Runner.run(agent, When did the Roman Empire fall?) print(result.final_output) if __name__ __main__: asyncio.run(main())Runner.run是一个异步类方法。从 src/agents/run.py 的签名可以看到它支持丰富的可选参数参数作用starting_agent起始 Agent工作流从它开始input初始输入可以是单个字符串也可以是TResponseInputItem列表或RunStatecontext运行上下文TContextmax_turns最大轮次默认由DEFAULT_MAX_TURNS决定传None可禁用轮次限制hooks生命周期回调钩子run_config整个运行过程的全局配置error_handlers按错误类型注册的错误处理器previous_response_idOpenAI Responses API 的上一次响应 ID可跳过上一轮输入直接续接auto_previous_response_id为 True 时自动启用 Responses API 响应链式续接conversation_idOpenAI 服务端会话 ID用于读写会话历史session用于自动管理会话历史的 Session 对象Runner.run的 docstring 还清楚描述了运行循环的四个阶段这也是理解多 Agent 工作流的关键用给定输入调用 Agent若产生最终输出即符合agent.output_type的结果循环终止若发生 Handoff则换用新 Agent 重新进入循环否则执行工具调用如有然后再次循环。另外Runner.run_sync提供了同步入口它只是对run的包装因此不能在已存在事件循环的环境中使用例如 Jupyter Notebook、FastAPI 或任何 async 函数内部这些场景请使用runRunner.run_streamed则用于流式输出场景。补充运行结束后result.final_output保存最后一个 Agent 的最终文本输出在多 Agent 场景中还可以通过result.last_agent.name得知最终由哪个 Agent 作答。五、多轮对话的三种记忆续接策略上面的例子只跑了一轮。要进行第二轮对话官方提供了三种方案选择取决于你对历史记录由谁管理的偏好如果你想要……起始方案完全手动控制、与模型提供商无关的历史记录result.to_input_list()让 SDK 自动加载与保存历史记录session...OpenAI 服务端托管的会话续接previous_response_id或conversation_idresult.to_input_list()会把本轮运行产生的全部输入项转换为可再次传给Runner.run(...)的列表实现完全自主、跨提供商的上下文传递传入session...后SDK 负责历史记录的读写详见 会话文档使用previous_response_id/conversation_id则依赖 OpenAI 服务端保存的状态可跳过重复传递历史。三者各有取舍详细的对比与精确行为可参考 运行 Agent选择记忆策略。另外需要明确的是当任务主要发生在提示词、工具与对话状态内时直接使用普通AgentRunner即可如果 Agent 需要在隔离的工作区中真实地查看或修改文件则应转向沙盒 Agent 快速入门。六、给你的 Agent 挂载工具工具让 Agent 能够查询外部信息或执行具体动作。SDK 提供了tool装饰器可将普通 Python 函数一键转为 Agent 可调用的工具import asyncio from agents import Agent, Runner from agents.decorators import tool tool def history_fun_fact() - str: Return a short history fact. return Sharks are older than trees. agent Agent( nameHistory Tutor, instructionsAnswer history questions clearly. Use history_fun_fact when it helps., tools[history_fun_fact], ) async def main(): result await Runner.run( agent, Tell me something surprising about ancient life on Earth., ) print(result.final_output) if __name__ __main__: asyncio.run(main())在 src/agents/decorators.py 中可以看到tool实际上是function_tool的别名同文件还导出了input_guardrail、output_guardrail、tool_input_guardrail、tool_output_guardrail等装饰器。tool装饰的函数会基于函数签名与 docstring 自动生成工具的模式描述Schema供模型调用因此docstring 就是给模型的说明书应清晰描述函数作用类型注解与参数描述会被用于生成 JSON Schema建议使用Annotated[str, 描述]等方式补充参数说明。仓库中的 examples/basic/tools.py 展示了更完整的用法它定义了一个WeatherPydantic 模型作为工具返回值并用Annotated描述城市参数运行后 Agent 会根据用户提问自动触发工具调用。七、添加更多 Agent选择多 Agent 模式在引入多 Agent 之前先想清楚一个关键问题最终答案由谁负责官方推荐两种模式Handoffs交接在某一轮中专家 Agent 接管对话完成该部分任务Agents as toolsAgent 即工具编排者orchestrator保持控制权把专家 Agent 当作工具来调用。本快速入门选用Handoffs因为它是代码量最少、最容易理解的第一示例。Manager 风格的模式可参考多 Agent 编排与工具Agents as tools。新增 Agent 的写法和第一个完全一致关键在于为每个专家 Agent 提供handoff_description给路由 Agent 额外的上下文让它知道何时该把问题交给谁from agents import Agent history_tutor_agent Agent( nameHistory Tutor, handoff_descriptionSpecialist agent for historical questions, instructionsYou answer history questions clearly and concisely., ) math_tutor_agent Agent( nameMath Tutor, handoff_descriptionSpecialist agent for math questions, instructionsYou explain math step by step and include worked examples., )从源码看handoff_description正是AgentBase中声明的字段src/agents/agent.py它的注释明确指出该描述在 Agent 被用作 Handoff 目标时供 LLM 判断其职责与调用时机。八、定义 Handoffs 并运行编排在 Agent 上你可以声明一组出站交接选项供其在解决任务的过程中自行选择triage_agent Agent( nameTriage Agent, instructionsRoute each homework question to the right specialist., handoffs[history_tutor_agent, math_tutor_agent], )运行编排时Runner负责执行单个 Agent、处理所有 Handoff 与所有工具调用import asyncio from agents import Runner async def main(): result await Runner.run( triage_agent, Who was the first president of the United States?, ) print(result.final_output) print(fAnswered by: {result.last_agent.name}) if __name__ __main__: asyncio.run(main())这里result.last_agent.name会告诉你最终由哪个专家 Agent 给出了答案——这也是验证 Handoff 路由是否生效的最直观方式。对照前文Runner.run的运行循环triage_agent收到问题后若判定为历史类问题便通过 Handoff 把控制权移交给history_tutor_agent由后者产出最终答案循环随之终止。仓库中的 examples/agent_patterns/routing.py 提供了一个更完整的路由示例它创建了法语、西班牙语、英语三个语言 Agent 与一个triage_agent根据请求语言进行 Handoff并使用Runner.run_streamed流式输出、用result.to_input_list()维护多轮上下文——非常适合作为多 Agent 路由的进阶参考。九、参考示例速查仓库中为上述核心模式准备了可直接运行的完整脚本examples/basic/hello_world.py第一个 Agent 的首次运行examples/basic/tools.py函数工具含 Pydantic 结构化返回examples/agent_patterns/routing.py多 Agent 路由Handoff。十、查看运行追踪Traces运行 Agent 时SDK 会自动为每次执行生成分布式追踪trace记录模型调用、工具调用、Handoff 等全过程。你可以在 OpenAI Dashboard 的Trace viewer中查看这些追踪用于调试与性能分析。若你想了解追踪的底层实现与自定义处理器可阅读 追踪文档 以及 src/agents/tracing 目录下的源码。十一、下一步至此你已经掌握了 openai-agents-python 最核心的单 Agent → 工具 → 多 Agent 编排链路。继续深入的方向包括学习如何全面配置 Agent模型、输出类型、动态指令等深入理解 运行 Agent 与会话Sessions如果任务需要在真实工作区内执行探索沙盒 Agent进阶学习工具、护栏Guardrails与模型接入。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考