openai-agents-python Agent 类完整指南构造参数、工具行为与多智能体编排【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python导读Agent是 openai-agents-python 框架的核心构建单元——它是一个由 LLM 驱动的实体通过instructions系统提示、tools工具、handoffs交接、guardrails护栏与结构化输出output_type等配置组合而成。本文以 Agent API 参考即agents.agent模块为主体结合 用户指南 与 模块源码 的 docstring 实现逐项讲解Agent的全部构造参数、底层校验逻辑、clone()/as_tool()/get_system_prompt()等关键方法以及tool_use_behavior、MCPConfig、StopAtTools等配套类型。读完本文你将能够独立完成一个生产级 Agent 的配置、工具接入、多智能体编排与生命周期观测。Agent 在框架中的定位在 openai-agents-python 中Agent与Runner是一对核心组合Agent负责配置指令、工具、护栏、交接、输出结构Runner负责执行管理轮次、调用模型、执行工具、处理交接与会话。文档明确指出两者区分的关键在于编排层——如果你希望框架替你管理 turns、tools、guardrails、handoffs 与 sessions就使用AgentRunner如果你要完全自己掌控这个循环则应直接使用 Responses API。从源码结构看agent.py 中先定义了基类AgentBase泛型于上下文类型TContext它承载Agent与RealtimeAgent共用的参数name、handoff_description、tools、mcp_servers、mcp_config随后 Agent 在基类之上扩展出指令、交接、模型、护栏、输出类型、生命周期钩子与工具行为等完整配置面。from agents import Agent from agents.decorators import tool tool def get_weather(city: str) - str: returns weather info for the specified city. return fThe weather in {city} is sunny agent Agent( nameHaiku agent, instructionsAlways respond in haiku form, modelgpt-5-nano, tools[get_weather], )需要特别说明的是docs/ref/agent.md是 mkdocstrings 的渲染占位文件由 generate_ref_files.py 生成内容为::: agents.agent指令其真正的文档内容来自 agent.py 中每个类与方法的 docstring本文所有参数说明均以这些 docstring 与__post_init__校验逻辑为准。Agent 构造参数全景Agent是一个泛型 dataclass其全部构造参数、类型与默认行为如下表所示对应 agent.py 的字段定义与 docs/agents.md 的配置说明参数必填类型说明name是str人类可读的 Agent 名称。instructions否str \| Callable[[RunContextWrapper, Agent], MaybeAwaitable[str]] \| None系统提示词强烈建议提供也支持返回字符串的动态函数。prompt否Prompt \| DynamicPromptFunction \| NoneOpenAI Responses API 的 prompt 配置平台提示词模板仅对 OpenAI 模型 Responses API 可用。handoff_description否str \| None当该 Agent 作为交接目标暴露给 LLM 时的短描述LLM 据此判断何时调用它。handoffs否list[Agent \| Handoff]子 Agent 列表Agent 可在相关时委派delegate给它实现关注点分离与模块化。model否str \| Model \| None调用 LLM 时使用的模型实现。未设置时使用agents.models.get_default_model()的默认值。model_settings否ModelSettings模型调参如temperature、top_p、tool_choice接受ModelSettings实例或其字段字典。tools否list[Tool]Agent 可调用的工具列表。mcp_servers否list[MCPServer]提供 MCP 工具的服务器列表每次运行都会并入可用工具。mcp_config否MCPConfig微调 MCP 工具的准备方式严格模式转换、失败格式化等。input_guardrails否list[InputGuardrail]在 Agent 链中首个 Agent 生成响应前并行运行的检查。output_guardrails否list[OutputGuardrail]在 Agent 产生最终输出后对输出运行的检查。output_type否type \| AgentOutputSchemaBase \| None结构化输出类型未提供时输出为str。hooks否AgentHooks \| None该 Agent 实例的生命周期回调。tool_use_behavior否run_llm_again \| stop_on_first_tool \| StopAtTools \| ToolsToFinalOutputFunction控制工具结果是否回环给模型或直接结束运行。reset_tool_choice否bool默认True工具调用后是否将tool_choice重置为默认值避免工具使用死循环。构造时的类型校验post_initagent.py 的__post_init__对每个参数做了严格类型检查任何不合法输入都会在构造阶段抛出TypeError而不是等到运行期才暴露。值得注意的校验点name必须是字符串handoff_description必须是字符串或Noneinstructions必须是字符串、可调用对象或Noneprompt必须是Prompt、动态函数或Nonemodel必须是字符串、Model实例或Nonemodel_settings会经_coerce_model_settings统一处理支持直接传字典tool_use_behavior必须是两个字符串字面量之一、StopAtTools字典或可调用对象reset_tool_choice必须是布尔值。此外有一个隐式行为当显式设置了model且model_settings仍是全局默认值时会自动将该 Agent 的model_settings切换为该模型对应的默认设置见 agent.py。默认模型与默认模型设置若model未指定Agent 使用 default_models.py 中get_default_model()的返回值其逻辑为读取环境变量OPENAI_DEFAULT_MODEL未设置时回退到gpt-5.6-luna。而model_settings的默认值由get_default_model_settings()决定对于 GPT-5 系列模型会根据模型名匹配对应的默认推理强度reasoning.effort与verbositylow见 default_models.py。这意味着你通常无需手动为每个 Agent 配置model_settings框架已按模型族给出合理默认。instructions静态字符串与动态函数instructions是 Agent 的系统提示词描述 Agent 应该做什么、如何回应。它有两种形态静态字符串直接传入。动态函数函数签名必须恰好为(context: RunContextWrapper[TContext], agent: Agent[TContext])返回str同步与async函数均可。底层实现见 get_system_prompt()框架会通过inspect.signature强制校验函数参数恰好为 2 个然后调用函数若返回值是 awaitable 则自动await。注意注释中的细节——可调用实例实现了__call__的类实例的__call__是异步的时iscoroutinefunction判断会跳过因此框架统一用inspect.isawaitable判断保证两类写法都能工作。from agents import Agent, RunContextWrapper def dynamic_instructions( context: RunContextWrapper[UserContext], agent: Agent[UserContext] ) - str: return fThe users name is {context.context.name}. Help them with their questions. agent AgentUserContextpromptOpenAI 平台提示词模板prompt参数允许你在代码之外动态配置指令、工具等仅对 OpenAI 模型 Responses API 可用。用法在 OpenAI 平台创建提示词模板如系统提示为Write a poem in {{poem_style}}然后通过prompt引用模板 ID 与版本from agents import Agent agent Agent( namePrompted assistant, prompt{ id: pmpt_123, version: 1, variables: {poem_style: haiku}, }, )也可以在运行时动态生成 prompt——传入一个接收GenerateDynamicPromptData、返回 prompt 字典的函数完整示例见 docs/agents.md。底层转换由 get_prompt() 调用PromptUtil.to_model_input完成最终产出 Responses API 的ResponsePromptParam。output_type结构化输出默认情况下 Agent 输出纯文本str。传入output_type后模型将使用结构化输出structured outputs而非普通文本。支持任何可被 PydanticTypeAdapter包装的类型dataclass、Pydantic 模型、TypedDict、list 等。from pydantic import BaseModel from agents import Agent class CalendarEvent(BaseModel): name: str date: str participants: list[str] agent Agent( nameCalendar extractor, instructionsExtract calendar events from text, output_typeCalendarEvent, )如需更精细的控制output_type还支持两种自定义方式见 agent.py 的 docstring想用非严格 JSON schema 时传AgentOutputSchema(MyClass, strict_json_schemaFalse)想完全自定义 JSON schema 时继承AgentOutputSchemaBase子类传入。相关概念可参考 结构化输出与严格模式 与 output_type 参考。工具与 MCP 服务器tools参数是 Agent 可调用的本地工具列表如tool装饰器定义的FunctionTool。除本地工具外AgentBase还支持通过mcp_servers接入 MCPModel Context Protocol服务器每次 Agent 运行都会将这些服务器提供的工具并入可用工具集。MCPConfig 配置项mcp_config是一个TypedDict定义见 agent.py用于微调 MCP 工具的准备方式字段默认值说明convert_schemas_to_strictFalse是否尝试将 MCP schema 转换为严格模式 schema。这是尽力而为的转换部分 schema 可能无法转换。failure_error_functiondefault_tool_error_function将 MCP 工具失败转换为模型可见消息的可选函数。显式设为None时工具错误将被直接抛出。include_server_in_tool_namesFalse为True时本地 MCP 工具以服务器名前缀的公开名称暴露避免多个 MCP 服务器之间的工具名冲突。这些字段在 get_mcp_tools() 中被实际消费读取mcp_config取值后调用MCPUtil.get_all_function_tools拉取全部工具。当include_server_in_tool_names开启时还会先计算保留名称包括本地FunctionTool名称与已启用的 handoff 工具名防止命名冲突。详见 MCP 指南。工具聚合与启用控制get_all_tools() 汇总了最终暴露给 LLM 的工具集合先取 MCP 工具再对每个FunctionTool检查is_enabled布尔值或返回布尔值的可调用函数随后裁剪孤儿工具搜索工具prune_orphaned_tool_search_tools最后校验 Codex 工具名冲突重复的 Codex 工具名会抛出UserError。也就是说禁用工具会在运行时对 LLM 隐藏而非简单从列表中移除。MCP 服务器的生命周期需要你自己管理必须在传入 Agent 前调用server.connect()不再需要时调用server.cleanup()。文档建议使用agents.mcp中的MCPServerManager将 connect/cleanup 放在同一任务中。多智能体设计的两种模式框架文档归纳了两种常见的多智能体系统设计模式详见 docs/agents.md模式一Manageragents as tools中央编排 Agent 将专业子 Agent 暴露为工具调用并始终保留对话控制权。这是通过as_tool()方法实现的from agents import Agent booking_agent Agent(...) refund_agent Agent(...) customer_facing_agent Agent( nameCustomer-facing agent, instructions( Handle all direct user communication. Call the relevant tools when specialized expertise is needed. ), tools[ booking_agent.as_tool( tool_namebooking_expert, tool_descriptionHandles booking questions and requests., ), refund_agent.as_tool( tool_namerefund_expert, tool_descriptionHandles refund questions and requests., ) ], )模式二Handoffs交接配置的交接目标handoff targets是 Agent 可委派的子 Agent。发生交接时被委派的 Agent接收完整对话历史并接管对话这是一种去中心化的协作方式from agents import Agent booking_agent Agent(...) refund_agent Agent(...) triage_agent Agent( nameTriage agent, instructions( Help the user with their questions. If they ask about booking, hand off to the booking agent. If they ask about refunds, hand off to the refund agent. ), handoffs[booking_agent, refund_agent], )完整细节见 Handoffs 指南 与 多智能体编排。另外handoff_description在此处至关重要——它作为交接目标被 LLM 看到时的描述决定 LLM 是否会、何时调用该 Agent。tool_use_behavior控制工具结果的去向tool_use_behavior定义见 agent.py决定工具调用结果如何被处理共有四种取值取值行为run_llm_again默认执行工具后把结果发回 LLM由 LLM 继续生成最终响应。stop_on_first_tool第一个工具调用的输出直接作为最终结果不再送回 LLM 处理。StopAtTools(stop_at_tool_names[...])若调用列表中任一工具则停止运行最终输出为第一个匹配工具调用的输出LLM 不再处理该结果。可调用函数ToolsToFinalOutputFunction接收运行上下文与工具结果列表返回ToolsToFinalOutputResult自行决定是否将工具结果作为最终输出。重要限制tool_use_behavior只对FunctionTool生效——托管工具hosted tools如 file search、web search始终由 LLM 处理不受此配置控制。StopAtToolsStopAtTools是一个TypedDictagent.py包含stop_at_tool_names: list[str]即任一工具名命中即停止from agents import Agent from agents.agent import StopAtTools from agents.decorators import tool tool def get_weather(city: str) - str: Returns weather info for the specified city. return fThe weather in {city} is sunny tool def sum_numbers(a: int, b: int) - int: Adds two numbers. return a b agent Agent( nameStop At Stock Agent, instructionsGet weather or sum numbers., tools[get_weather, sum_numbers], tool_use_behaviorStopAtTools(stop_at_tool_names[get_weather]) )ToolsToFinalOutputFunction自定义函数的类型为Callable[[RunContextWrapper[TContext], list[FunctionToolResult]], MaybeAwaitable[ToolsToFinalOutputResult]]。ToolsToFinalOutputResultagent.py包含两个字段is_final_output: bool是否最终输出为False时 LLM 会再次运行并接收工具输出与final_output: Any | None最终输出is_final_output为True时必须匹配 Agent 的output_typefrom agents import Agent, FunctionToolResult, RunContextWrapper from agents.agent import ToolsToFinalOutputResult from agents.decorators import tool from typing import List, Any tool def get_weather(city: str) - str: Returns weather info for the specified city. return fThe weather in {city} is sunny def custom_tool_handler( context: RunContextWrapper[Any], tool_results: List[FunctionToolResult] ) - ToolsToFinalOutputResult: for result in tool_results: if result.output and sunny in result.output: return ToolsToFinalOutputResult( is_final_outputTrue, final_outputfFinal weather: {result.output} ) return ToolsToFinalOutputResult( is_final_outputFalse, final_outputNone ) agent Agent( nameWeather Agent, instructionsRetrieve weather details., tools[get_weather], tool_use_behaviorcustom_tool_handler )reset_tool_choice 与强制工具使用框架为防止死循环会在一次工具调用后自动把tool_choice重置为auto可通过agent.reset_tool_choice配置默认True。死循环的成因是工具结果被送回 LLMLLM 因固定的tool_choice又生成一次工具调用如此往复。相关测试见 test_tool_choice_reset.py。如果你想强制LLM 使用某个工具可设置ModelSettings.tool_choice合法值为autoLLM 自行决定、required必须用工具但可智能选择、none禁止使用工具、或具体工具名字符串强制使用该工具from agents import Agent, ModelSettings from agents.decorators import tool tool def get_weather(city: str) - str: Returns weather info for the specified city. return fThe weather in {city} is sunny agent Agent( nameWeather Agent, instructionsRetrieve weather details., tools[get_weather], model_settingsModelSettings(tool_choiceget_weather) )注意使用 OpenAI Responses 工具搜索tool search时命名工具选择受限——无法用tool_choice定位裸命名空间名称或仅延迟deferred的工具tool_choicetool_search也不能直接指定ToolSearchTool此时应优先auto或required详见 docs/tools.md。clone()克隆 Agent 及其浅拷贝语义clone() 基于dataclasses.replace实现返回参数被替换后的新 Agentpirate_agent Agent( namePirate, instructionsWrite like a pirate, modelgpt-5.6-sol, ) robot_agent pirate_agent.clone( nameRobot, instructionsWrite like a robot, )其语义有四个关键点docstring 中明确说明执行的是浅拷贝列表属性tools、handoffs、mcp_servers、input_guardrails、output_guardrails永远不会被复制未覆盖的属性会沿用原 Agent 自己的列表——两个 Agent 持有同一个列表对象通过任一 Agent 修改如cloned.tools.append(extra_tool)都会影响另一个覆盖传入的属性按传入值原样使用只有当你复用了同一个列表/条目时才与原 Agent 共享想要一个完全独立的列表容器请传入新列表pirate_agent.clone(tools[*pirate_agent.tools, extra_tool])——新列表中的条目仍是原对象除非你也替换了这些条目。另外clone()还有两个隐含的智能行为若只改model而未改model_settings且原设置匹配隐式模型默认值则会自动为新模型套用对应默认设置若改动了model_settings会基于原类型做_coerce_model_settings统一处理。相关测试见 test_agent_clone_shallow_copy.py 与 test_agent_config.py。as_tool()把 Agent 变成工具as_tool() 将一个 Agent 转换为FunctionTool供其他 Agent 调用。它与 handoffs 有两点本质区别docstring 原文输入来源不同handoffs 中新 Agent 接收完整对话历史而 as_tool 中新 Agent 接收的是生成的结构化输入。控制权归属不同handoffs 中新 Agent 接管对话而 as_tool 中新 Agent 作为工具被调用对话仍由原 Agent 继续。方法参数如下参数说明tool_name工具名未提供时使用 Agent 名转换为函数风格如MyAgent→my_agent。tool_description工具描述应说明它做什么、何时使用。custom_output_extractor从运行结果中提取输出的函数未提供时使用 Agent 的最后一条消息。嵌套运行结果会通过agent_tool_invocation元数据暴露。is_enabled布尔值或接收 (运行上下文, Agent) 的可调用函数禁用工具在运行时对 LLM 隐藏。on_stream同步/异步回调接收嵌套 Agent 运行的流式事件AgentToolStreamEvent含嵌套 agent、原始工具调用与每个流事件提供后嵌套 Agent 以流式模式执行且回调在后台分发慢 handler 不会阻塞事件消费。run_config嵌套运行的RunConfig或字典。max_turns嵌套运行最大轮次未提供时使用Runner的DEFAULT_MAX_TURNS。hooks嵌套运行的RunHooks。previous_response_id/conversation_id/session嵌套运行的会话相关参数恢复运行时这些会被忽略。failure_error_function嵌套运行失败时生成发给 LLM 的错误消息为None时直接抛出异常。needs_approval布尔值或可调用函数决定该 Agent 工具是否暂停等待审批。parameters工具参数的结构化输入类型dataclass 或 Pydantic 模型未提供时使用默认的AgentAsToolInput。input_builder从结构化数据构建嵌套 Agent 输入的可选函数。include_input_schema结构化输入中是否包含完整 JSON schema。源码层面的实现要点_run_agent_impl会先解析并校验 JSON 输入用TypeAdapter验证失败抛ModelBehaviorError构造嵌套的ToolContext避免与父运行共享审批状态然后调用Runner.run或Runner.run_streamed运行结果按tool_call身份缓存record_agent_tool_run_result支持嵌套中断interruption的恢复与审批状态流转最终返回逻辑依次为自定义提取器 →final_output非空字符串时→ 反向扫描new_items中的文本输出 → 工具调用输出。返回的工具会打上_is_agent_tool True标记便于框架识别其Agent 即工具来源。相关测试见 test_agent_as_tool.py。生命周期钩子hookshooks参数允许你观察 Agent 的生命周期例如记录日志、预取数据或记录用量。框架提供两种作用域详见 生命周期参考RunHooks观察整个Runner.run(...)调用包括交接给其他 Agent 的过程AgentHooks通过agent.hooks挂载到特定 Agent 实例。回调上下文也因事件而异Agent 开始/结束钩子接收AgentHookContext包装你的原始上下文并携带共享运行用量状态LLM、工具、交接钩子接收RunContextWrapper。典型时序on_agent_start/on_agent_end围绕单个 Agent 的起止on_llm_start/on_llm_end紧贴每次模型调用on_tool_start/on_tool_end围绕每次本地工具调用函数工具的钩子上下文通常是ToolContext可查看tool_call_id等元数据on_handoff在控制权转移时触发。from agents import Agent, RunHooks, Runner class LoggingHooks(RunHooks): async def on_agent_start(self, context, agent): print(fStarting {agent.name}) async def on_llm_end(self, context, agent, response): print(f{agent.name} produced {len(response.output)} output items) async def on_agent_end(self, context, agent, output): print(f{agent.name} finished with usage: {context.usage}) agent Agent(nameAssistant, instructionsBe concise.) result await Runner.run(agent, Explain quines, hooksLoggingHooks()) print(result.final_output)护栏Guardrailsinput_guardrails与output_guardrails分别对首个用户输入和最终输出运行检查如相关性筛查且都并行于 Agent 执行。需要注意运行时机上的两个限定输入护栏仅当该 Agent 是链中首个 Agent 时运行输出护栏仅当该 Agent 产生最终输出时运行。具体实现与示例见 Guardrails 指南。与上下文Context的关系Agent是泛型于上下文类型的Agent[TContext]。上下文是你创建的可变对象通过Runner.run(..., context...)传入并传递给工具函数、交接、护栏等所有环节充当依赖注入的杂货袋。例如from dataclasses import dataclass dataclass class UserContext: name: str uid: str is_pro_user: bool agent AgentUserContext完整的能力面RunContextWrapper、共享用量跟踪、嵌套tool_input、序列化注意事项见 Context 指南。延伸阅读Agent 用户指南本文配套的实操级使用文档含更多示例运行 AgentRunner轮次、流式事件与会话管理运行结果Results最终输出、run items 与可恢复状态模型与提供商model参数的取值与自定义Model模型设置参考model_settings全部字段工具指南 与 MCP 指南tools、mcp_servers、mcp_config的深入用法Handoffs 指南 与 多智能体编排两种多智能体模式的完整实践源码与测试Agent 实现、默认模型设置、浅拷贝语义测试、as_tool 测试、工具选择重置测试。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考