openai-agents-python 智能体Agent开发指南核心配置、工具编排与生命周期管理【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonAgent是 openai-agents-python 框架中应用的核心构建块一个配置了指令instructions、工具tools、任务转移handoffs、安全防护措施guardrails与结构化输出structured outputs的大语言模型LLM封装。本指南以 docs/zh/agents.md 为骨架结合 Agent 源码 展开覆盖Agent的全部核心配置项、提示词模板、上下文注入、输出类型、多智能体编排模式、生命周期钩子以及工具使用行为控制。读完本文你将能够独立定义、克隆、配置并运行一个生产可用的智能体并理解其底层运行机制。智能体应用中的核心构建块在 openai-agents-python 中Agent代表一个被配置好的 LLM 实例。它本身不负责运行循环——真正的编排由Runner完成SDK 通过AgentRunner的组合替你管理模型轮次、工具调用、安全防护、任务转移与会话状态。对于 OpenAI 模型SDK 默认使用 Responses API。如果你希望自行控制模型调用循环可以直接使用 Responses API而AgentRunner的差异在于编排SDK 为你管理轮次、工具、安全防护措施、任务转移和会话。在动手之前请先确定你的使用场景以选择合适的指南入口如果你想要……接下来阅读选择模型或提供商设置模型为智能体添加能力工具让智能体针对真实代码仓库、文档包或隔离工作区运行沙箱智能体快速入门在管理器式编排与任务转移之间进行选择智能体编排配置任务转移行为任务转移运行轮次、流式传输事件或管理对话状态运行智能体检查最终输出、运行项或可恢复状态结果共享本地依赖项和运行时状态上下文管理如果你要定义或自定义单个基础Agent而非SandboxAgent请继续阅读本页。基本配置Agent最常用的属性如下表所示来源于 Agent 数据类定义属性必需说明name是便于人类阅读的智能体名称。源码在__post_init__中校验其必须为字符串见 agent.py。instructions否系统提示词或动态指令回调。强烈建议设置。请参阅动态指令。prompt否OpenAI Responses API 提示词配置。接受静态提示词对象或函数。请参阅提示词模板。handoff_description否当此智能体作为任务转移目标提供时显示的简短说明。handoffs否将对话委派给专业智能体。请参阅任务转移。model否要使用的 LLM。未设置时使用agents.models.get_default_model()返回的默认模型见 agent.py。请参阅模型。model_settings否模型调优参数例如temperature、top_p和tool_choice对应 ModelSettings。tools否智能体可以调用的工具。请参阅工具。mcp_servers否为智能体提供基于 MCP 的工具的 MCP 服务器。请参阅 MCP 指南。mcp_config否微调 MCP 工具的准备方式例如将其 schema 转换为严格模式以及设置 MCP 失败信息的格式。请参阅 MCP 指南。input_guardrails否针对此智能体链的第一个用户输入运行的安全防护措施。请参阅安全防护措施。output_guardrails否针对此智能体的最终输出运行的安全防护措施。请参阅安全防护措施。output_type否用于替代纯文本的 structured outputs 类型。请参阅输出类型。hooks否智能体作用域内的生命周期回调。请参阅生命周期事件钩子。tool_use_behavior否控制是将工具结果送回模型继续循环还是结束运行。请参阅工具使用行为。reset_tool_choice否在工具调用后重置tool_choice默认值True以避免工具使用循环。请参阅强制使用工具。一个最小可运行的示例来自 docs/zh/agents.mdfrom 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], )从源码角度看Agent继承自AgentBase见 agent.py后者承载了name、handoff_description、tools、mcp_servers、mcp_config等被RealtimeAgent等共享的基础参数。__post_init__agent.py会对所有关键字段做类型校验例如instructions必须是字符串或可调用对象、tool_use_behavior必须是run_llm_again、stop_on_first_tool、StopAtTools字典或可调用函数。本节中的所有内容均适用于Agent。SandboxAgent基于相同理念构建并额外添加了default_manifest、base_instructions、capabilities和run_as用于工作区作用域内的运行。请参阅沙箱智能体概念。提示词模板通过设置prompt你可以引用在 OpenAI 平台中创建的提示词模板。当通过 Responses API 访问 OpenAI 模型时此功能可用。使用步骤前往 https://platform.openai.com/playground/prompts创建一个新的提示词变量poem_style。创建包含以下内容的系统提示词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是一个 TypedDict包含id必填、version可选和variables可选见 prompts.py。PromptUtil.to_model_input()prompts.py负责将 Prompt 对象或动态函数解析为 Responses API 的ResponsePromptParam最终下发id、version与variables。你也可以在运行时动态生成提示词——传入一个接收GenerateDynamicPromptData内含context与agent并返回Prompt的函数普通函数与async函数均可from dataclasses import dataclass from agents import Agent, GenerateDynamicPromptData, Runner dataclass class PromptContext: prompt_id: str poem_style: str async def build_prompt(data: GenerateDynamicPromptData): ctx: PromptContext data.context.context return { id: ctx.prompt_id, version: 1, variables: {poem_style: ctx.poem_style}, } agent Agent(namePrompted assistant, promptbuild_prompt) result await Runner.run( agent, Say hello, contextPromptContext(prompt_idpmpt_123, poem_stylelimerick), )动态函数必须返回Prompt字典否则会抛出UserErrorprompts.py。上下文智能体以其context类型作为泛型参数。上下文是一种依赖注入工具它是由你创建并传递给Runner.run()的对象随后会传递给每个智能体、工具、任务转移等并作为智能体运行所需依赖项和状态的集合。你可以提供任何 Python 对象作为上下文。from dataclasses import dataclass dataclass class Purchase: id: str dataclass class UserContext: name: str uid: str is_pro_user: bool async def fetch_purchases(self) - list[Purchase]: # implement your logic here return [] agent AgentUserContext有关完整的RunContextWrapper接口、共享用量追踪、嵌套的tool_input以及序列化注意事项请阅读上下文指南。在运行期间工具函数、动态指令、钩子、任务转移和防护措施都会收到包装后的RunContextWrapper通过context.context访问你的原始对象。输出类型默认情况下智能体生成纯文本即str输出。如果你希望智能体生成特定类型的输出可以使用output_type参数。常见选择是使用 Pydantic 对象但框架支持任何可以封装在 Pydantic TypeAdapter 中的类型例如 dataclass、列表、TypedDict 等。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后即表示要求模型使用 structured outputs而不是常规纯文本响应。从源码看output_type接受普通类型或AgentOutputSchemaBase实例如果你希望使用非严格 JSON schema可传入AgentOutputSchema(MyClass, strict_json_schemaFalse)或通过继承AgentOutputSchemaBase提供自定义 JSON schema见 agent.py。在__post_init__中output_type会被校验为类型、AgentOutputSchemaBase或泛型起源agent.py。多智能体系统设计模式多智能体系统有多种设计方式但通常有两种具有广泛适用性的模式管理器agents as tools中央管理器/编排器将专业子智能体作为工具调用并保留对对话的控制权。任务转移handoffs对等智能体将控制权转移给接管对话的专业智能体。这是一种去中心化模式。两者的关键区别在于控制权归属agents as tools 中原始智能体始终掌控对话handoffs 中被委派的智能体会接收对话历史记录并接管对话。管理器agents as toolscustomer_facing_agent负责处理所有用户交互并调用作为工具公开的专业子智能体。请在工具文档中了解更多信息。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., ) ], )源码层面的as_tool()agent.py将智能体转换为一个FunctionTool与 handoffs 不同被调用时子智能体接收的是生成的输入而非对话历史且调用结束后对话仍由原智能体继续。它还支持custom_output_extractor、is_enabled、on_stream、needs_approval、结构化parameters等高级参数。仓库中的 agents_as_tools.py 与 agents_as_tools_streaming.py 提供了可直接运行的完整示例。任务转移配置的任务转移目标是智能体可以委派任务的子智能体。发生任务转移时被委派的智能体会接收对话历史记录并接管对话。此模式支持模块化的专业智能体使其能够出色完成单一任务。请在任务转移文档中了解更多信息。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接受Agent实例或Handoff对象列表agent.py并支持条件启用的is_enabled回调handoff_description会作为 LLM 判断何时转移的依据。动态指令在大多数情况下你可以在创建智能体时提供指令。不过你也可以通过函数提供动态指令。该函数将接收智能体和上下文并且必须返回提示词。普通函数和async函数均可接受。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 AgentUserContext源码中instructions字段的类型即str | Callable[[RunContextWrapper[TContext], Agent[TContext]], MaybeAwaitable[str]] | Noneagent.py印证了它既可以是静态字符串也可以是接收上下文与智能体实例、返回字符串支持同步与异步的指令生成函数。仓库中的 dynamic_system_prompt.py 是一个可运行的动态指令示例。生命周期事件钩子有时你可能希望观察智能体的生命周期。例如你可能希望在特定事件发生时记录事件日志、预取数据或记录用量。钩子分为两个作用域RunHooks观察整个Runner.run(...)调用包括向其他智能体进行的任务转移。AgentHooks通过agent.hooks附加到特定智能体实例。回调上下文也会随事件而变化智能体开始/结束钩子接收AgentHookContext它会封装你的原始上下文并携带共享的运行用量状态。LLM、工具和任务转移钩子接收RunContextWrapper。典型的钩子触发时机如下on_agent_start特定智能体开始运行时on_agent_end该智能体完成最终输出时。on_llm_start/on_llm_end紧邻每次模型调用的前后触发。on_tool_start/on_tool_end在每次本地工具调用前后触发。对于函数工具钩子context通常是ToolContext因此你可以检查工具调用元数据例如tool_call_id。on_handoff控制权从一个智能体转移到另一个智能体时。如果希望为整个工作流设置一个统一观察器请使用RunHooks如果希望将生命周期回调限定到特定智能体请使用AgentHooks。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)从源码看RunHooksBase定义了on_llm_start、on_llm_end、on_agent_start、on_agent_end、on_handoff、on_tool_start、on_tool_end等回调接口AgentHooksBase则额外提供on_start/on_end见 lifecycle.py。两套接口均为基类你只需覆写需要的方法。仓库中的 lifecycle_example.py 与 agent_lifecycle_example.py 展示了完整用法。有关完整的回调接口请参阅生命周期 API 参考。安全防护措施安全防护措施允许你在智能体运行的同时并行检查/验证用户输入并在智能体生成输出后对其进行检查/验证。例如你可以筛查用户输入和智能体输出是否与任务相关。请在安全防护措施文档中了解更多信息。在源码中input_guardrails仅在该智能体是链中的第一个智能体时运行针对首个用户输入output_guardrails仅在智能体产生最终输出时运行见 agent.py。仓库中的 input_guardrails.py 与 output_guardrails.py 提供了可直接参考的示例。智能体克隆与复制通过在智能体上使用clone()方法你可以复制一个智能体并可选择更改任意属性。pirate_agent Agent( namePirate, instructionsWrite like a pirate, modelgpt-5.6-sol, ) robot_agent pirate_agent.clone( nameRobot, instructionsWrite like a robot, )源码中的clone()基于dataclasses.replace实现执行的是浅拷贝agent.py。需要注意tools、handoffs、mcp_servers、input_guardrails、output_guardrails等列表属性不会被复制——未传入的属性会共享原智能体的同一个列表例如cloned.tools.append(extra_tool)也会改变原智能体。若想让克隆体拥有独立的列表请显式传入新列表例如agent.clone(tools[*agent.tools, extra_tool])。另外clone()还会在仅替换model时自动继承对应的默认model_settings。相关行为测试见 test_agent_clone_shallow_copy.py。强制使用工具提供工具列表并不总是意味着 LLM 会使用工具。你可以通过设置ModelSettings.tool_choice强制使用工具。有效值包括auto允许 LLM 决定是否使用工具。required要求 LLM 使用工具但它可以智能决定使用哪个工具。none要求 LLM不使用工具。设置特定字符串例如my_tool要求 LLM 使用该特定工具。使用 OpenAI Responses 工具搜索时具名工具选项受到更多限制不能通过tool_choice指定纯命名空间名称或仅延迟加载的工具且tool_choicetool_search不会指定ToolSearchTool。在这些情况下建议使用auto或required。有关 Responses 特有的限制请参阅托管工具搜索。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) )源码中ToolChoice的类型别名即为Literal[auto, required, none] | str | MCPToolChoice | Nonemodel_settings.py与文档描述的四种取值一一对应。仓库中的 forcing_tool_use.py 提供了完整示例。防止工具使用循环reset_tool_choice为防止无限循环框架会在工具调用后自动将tool_choice重置为auto。此行为可通过agent.reset_tool_choice默认True配置。产生无限循环的原因是工具结果会发送给 LLM而 LLM 随后会由于tool_choice再次生成工具调用如此无限重复。底层实现位于 tool_execution.py 的maybe_reset_tool_choice()def maybe_reset_tool_choice( agent: Agent[Any], tool_use_tracker: AgentToolUseTracker, model_settings: ModelSettings, ) - ModelSettings: Reset tool_choice if the agent was forced to pick a tool previously and should be reset. if agent.reset_tool_choice is True and tool_use_tracker.has_used_tools(agent): return dataclasses.replace(model_settings, tool_choiceNone) return model_settings该函数在运行循环的每一轮模型调用前被调用见 run_loop.py 与 run_loop.py只要智能体已使用过工具且reset_tool_choice为True就会把tool_choice重置为None即auto避免模型被强制反复调用同一工具。工具使用行为Agent配置中的tool_use_behavior参数控制工具输出的处理方式agent.pyrun_llm_again默认行为。运行工具后由 LLM 处理结果并生成最终响应。stop_on_first_tool将第一次工具调用的输出用作最终响应不再由 LLM 进行后续处理。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( nameWeather Agent, instructionsRetrieve weather details., tools[get_weather], tool_use_behaviorstop_on_first_tool )StopAtTools(stop_at_tool_names[...])如果调用了任一指定工具则停止运行并将其输出用作最终响应。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]) )StopAtTools在源码中是一个 TypedDict包含stop_at_tool_names: list[str]agent.py。需要注意该配置仅对函数工具FunctionTool生效托管工具如 file search、web search始终由 LLM 处理结果agent.py。ToolsToFinalOutputFunction自定义函数用于处理工具结果并决定是以最终输出结束运行还是让 LLM 继续处理。from 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: Processes tool results to decide final output. 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 )从源码看ToolsToFinalOutputResult包含is_final_output: bool是否为最终输出若为FalseLLM 会再次运行并接收工具调用输出与可选的final_output: Any必须匹配智能体的output_typeagent.py。ToolsToFinalOutputFunction的类型签名是接收RunContextWrapper与工具结果列表、返回可等待的ToolsToFinalOutputResult的函数agent.py因此同步与异步处理函数均可使用。小结本文以 docs/zh/agents.md 为主体完整覆盖了Agent的定义与全部核心配置从基本属性name、instructions、tools、model等到提示词模板与动态指令从泛型上下文注入到结构化输出类型从管理器/任务转移两种多智能体模式到生命周期钩子再到tool_choice强制工具、tool_use_behavior工具使用行为与reset_tool_choice防循环机制并逐一给出了对应的源码位置agent.py、model_settings.py、prompts.py、lifecycle.py、tool_execution.py与可运行示例examples/basic、examples/agent_patterns。下一步你可以依据后续指南选择中的决策表继续深入模型选择、工具、任务转移、运行智能体、结果处理与上下文管理或在需要隔离工作区与沙箱原生能力时转向沙箱智能体概念。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
