openai-agents-python 运行指南掌握 Runner 执行、RunConfig 配置与多轮会话状态管理【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本文基于 docs/ja/running_agents.md 编写围绕 openai-agents-python 框架的Runner执行体系展开系统讲解三种执行入口、Agent 循环的工作原理、RunConfig全部配置类别、四类多轮记忆策略、错误处理器以及异常体系。读者完成后将能够熟练编排单 Agent 与多 Agent 工作流按需启用流式输出、Responses WebSocket 传输、Sessions 持久化与会话级恢复并正确处置运行中的各类异常。一、三种执行入口run / run_sync / run_streamed在 openai-agents-python 中Agent 的一切执行都经由Runner类完成。它提供了三个等价的入口方法分别面向异步、同步与流式场景方法执行方式返回值适用场景Runner.run()异步协程RunResult常规 async 应用、FastAPI、Jupyter 等已有事件循环的环境Runner.run_sync()同步阻塞RunResult脚本、简单命令行工具内部只是对.run()的封装Runner.run_streamed()异步 流式RunResultStreaming需要边生成边消费事件token 级体验、进度反馈最小可运行示例from agents import Agent, Runner async def main(): agent Agent(nameAssistant, instructionsYou are a helpful assistant) result await Runner.run(agent, Write a haiku about recursion in programming.) print(result.final_output) # Code within the code, # Functions calling themselves, # Infinite loops dance asyncio.run(main())关于三个入口方法的完整签名context、max_turns、hooks、run_config、error_handlers、previous_response_id、auto_previous_response_id、conversation_id、session等参数可直接参考 src/agents/run.py 中的Runner类定义。需要注意run_sync()的约束由于它内部直接调用.run()因此不能在已存在事件循环的上下文中使用例如 async 函数内部、Jupyter Notebook、FastAPI 请求处理中这些场景请改用run()。运行结果对象的具体字段final_output、last_agent、to_input_list()、last_response_id等可参考 执行结果指南。二、Runner 的生命周期与配置2.1 Agent 循环The Agent Loop调用上述任一入口时需要传入起始 Agentstarting agent与输入。输入支持三种形式字符串作为一条用户消息OpenAI Responses API 格式的输入条目列表list[TResponseInputItem]RunState用于恢复一次被暂停的执行或恢复通过cancel(modeafter_turn)停止的执行。状态中可以携带为下次恢复准备好的输入条目详见 results.md 的恢复前追加输入。随后 Runner 执行如下循环使用当前输入调用当前 Agent 的 LLMLLM 产生输出后分三种情况处理判定为最终输出终止循环并返回运行结果产生handoff转交更新当前 Agent 与输入重新进入循环产生工具调用执行这些工具调用、把结果追加回输入再重新进入循环若超过传入的max_turns抛出MaxTurnsExceeded异常传max_turnsNone可禁用该限制。注意LLM 输出被判定为最终输出的条件是——生成了目标类型的文本输出且没有工具调用。另外从源码看只有起始 Agent 的输入护栏input guardrails会被执行见 run.py 的 docstring。max_turns的默认值为DEFAULT_MAX_TURNS 10定义在 src/agents/run_config.py。所谓一个 turn定义为一次 LLM 调用含该轮可能发生的所有工具调用。2.2 流式执行Streaming流式模式让你在 LLM 执行过程中实时收到语义事件流结束后RunResultStreaming中仍保存包含全部新输出的完整运行信息。通过.stream_events()消费事件事件类型复用 OpenAI Responses API 的语义事件。详见 流式指南。from agents import Agent, Runner async def main(): agent Agent(nameAssistant, instructionsBe concise.) result Runner.run_streamed(agent, Summarize recursion in one sentence.) async for event in result.stream_events(): if event.type raw_response_event: continue print(event.type) asyncio.run(main())2.3 Responses WebSocket 传输可选辅助启用 OpenAI Responses 的 WebSocket 传输后普通RunnerAPI 依然照常可用responses_websocket_session()会话辅助器只是推荐用于连接复用的可选增强并非强制。注意这是经 WebSocket 传输的 Responses API不是Realtime APIRealtime 见 docs/realtime/guide.md。传输选择规则及具体模型对象 / 自定义 provider 的注意事项见 模型文档。模式 1不使用会话辅助器可用但每次可能重连import asyncio from agents import Agent, Runner, set_default_openai_responses_transport async def main(): set_default_openai_responses_transport(websocket) agent Agent(nameAssistant, instructionsBe concise.) result Runner.run_streamed(agent, Summarize recursion in one sentence.) async for event in result.stream_events(): if event.type raw_response_event: continue print(event.type) asyncio.run(main())这种模式适合单次执行。若反复调用Runner.run()/Runner.run_streamed()而不手动复用同一个RunConfig/ provider 实例每次执行都可能重新建立连接。该全局设置函数定义于 src/agents/_config.py 与 src/agents/init.py仅接受http与websocket两个取值。模式 2使用responses_websocket_session()多轮复用推荐当需要在多次执行间共享 WebSocket 能力的 provider 与RunConfig时使用responses_websocket_session()。它也会作用于继承了同一run_config的嵌套调用如把 Agent 当作工具使用。import asyncio from agents import Agent, responses_websocket_session async def main(): agent Agent(nameAssistant, instructionsBe concise.) async with responses_websocket_session( responses_websocket_options{ping_interval: 20.0, ping_timeout: 60.0}, ) as ws: first ws.run_streamed(agent, Say hello in one short sentence.) async for _event in first.stream_events(): pass second ws.run_streamed( agent, Now say goodbye., previous_response_idfirst.last_response_id, ) async for _event in second.stream_events(): pass asyncio.run(main())使用注意事项退出上下文前必须完整消费流式结果若在 WebSocket 请求处理中退出 context可能强制关闭共享连接每个 WebSocket 连接同时只处理一个响应且连接时长限制为 60 分钟辅助器只负责复用连接并不能解除这些限制重连后在storeFalse与 ZDRzero-data-retention流程中未缓存的previous_response_id无法恢复此时应携带完整输入上下文开启新链或从本地管理的会话状态重建长推理轮次若触发 WebSocket keepalive 超时可增大ping_timeout或设ping_timeoutNone禁用心跳超时当可靠性比延迟更重要时改用 HTTP/SSE 传输。底层实现上responses_websocket_session()构造了一个使用openai_use_responses_websocketTrue的MultiProvider并把共享RunConfig注入其ResponsesWebSocketSession包装对象见 src/agents/responses_websocket_session.pykeepalive 参数ping_interval/ping_timeout由OpenAIResponsesWebSocketOptions定义并透传给底层websockets库见 src/agents/models/openai_responses.py。2.4 运行配置RunConfigrun_config参数用于配置一次 Agent 运行的全局设置在不修改任何 Agent 定义的前提下仅覆盖单次执行的行为。其完整字段定义见 src/agents/run_config.py。按类别归纳如下。模型、Provider 与会话默认值model设置全局 LLM 模型会覆盖每个 Agent 自带的model传入的model_provider必须能解析该模型名model_provider解析模型名所用的 provider默认 OpenAImodel_settings覆盖 Agent 级设置例如设置全局temperature或top_p接受ModelSettings实例或字段字典session_settings覆盖执行时取历史所用的会话级默认值例如SessionSettings(limit...)session_input_callback使用 Sessions 时定制每次Runner执行前新用户输入与会话历史的合并方式支持同步或异步回调。护栏、Handoff 与模型输入整形input_guardrails、output_guardrails应用到所有执行的输入/输出护栏列表handoff_input_filter当某 handoff 未自带输入过滤器时作为全局过滤器应用可编辑传给新 Agent 的输入参考Handoff.input_filternest_handoff_historyopt-in 的 beta 功能。开启后会把可总结的历史压缩为有序的 assistant 摘要段同时把无损消息条目保留在原始位置默认关闭。设True开启保持False则原样传递原始 transcript。Sessions、RunState、RunResult.to_input_list()不会对已保留的同一消息重复追加但会保留独立存在的相同消息单个 handoff 可用Handoff.nest_handoff_history覆盖该设置handoff_history_mapper在nest_handoff_history开启时生效的可选 callable接收规范化 transcript历史 handoff 条目返回应传给下一个 Agent 的精确输入条目列表用于替换内置的有序摘要段call_model_input_filter模型调用前一刻编辑完整模型输入instructions 与输入条目的钩子常用于裁剪历史或插入系统提示reasoning_item_id_policy控制 Runner 把上一轮输出转换为下一轮模型输入时推理条目 ID 是保留还是省略。追踪与可观测性tracing_disabled禁用整个执行的追踪tracing传入TracingConfig覆盖导出设置如每次执行的追踪 API keytrace_include_sensitive_data是否把 LLM 与工具调用的输入/输出等敏感数据写入追踪默认值由环境变量OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA控制见 src/agents/run_config.pyworkflow_name、trace_id、group_id设置执行的追踪工作流名、trace ID 与分组 ID建议至少设置workflow_namegroup_id用于把多次执行的 trace 关联到同一会话trace_metadata附加到所有 trace 的元数据字典。工具执行、审批与错误行为tool_execution配置 SDK 侧本地工具调用的执行行为例如限制并发数tool_not_found_behavior当模型生成的函数工具调用名在当前 Agent 中找不到时Runner 的处理策略默认抛出ModelBehaviorError也可改为向模型返回可感知的错误输出tool_name_collision_policy无命名空间的函数工具名与 handoff 名冲突时的策略。默认warn记录可操作的告警只暴露当前选中的分发目标error则在调用模型前抛出UserError。带命名空间与延迟加载工具的严格校验不受影响tool_error_formatter定制返回给模型的可感知工具错误消息如审批拒绝、opt-in 的未找到工具输出。另外开启RunConfig(nest_handoff_historyTrue)后如需修改内置摘要段的包装文本而不手写自定义 mapper可调用set_conversation_history_wrappers恢复默认用reset_conversation_history_wrappers。2.5 RunConfig 关键配置项详解tool_execution控制本地函数工具并发from agents import Agent, RunConfig, Runner, ToolExecutionConfig agent Agent(nameAssistant, tools[...]) result await Runner.run( agent, Run the required tool calls., run_configRunConfig( tool_executionToolExecutionConfig( max_function_tool_concurrency2, pre_approval_tool_input_guardrailsTrue, ), ), )max_function_tool_concurrencyNone保持默认行为模型在一轮中生成多个函数工具调用时SDK 会并发启动全部本地调用设置整数可限制同时执行的本地函数工具调用数最小为 1传 0 或负数会在__post_init__中抛ValueError见 src/agents/run_config.py。它与 provider 侧的ModelSettings.parallel_tool_calls是两个不同维度parallel_tool_calls控制模型能否在一个响应中生成多个工具调用max_function_tool_concurrency控制模型生成调用之后、SDK 如何执行这些本地函数工具调用。pre_approval_tool_input_guardrailsFalse保持默认审批流程函数工具需要审批时先暂停执行工具输入护栏在审批通过后、执行前才运行设True则在生成待审批中断前先运行工具输入护栏。注意即便通过审批前检查审批后同一输入护栏仍会再执行一次因此时间敏感检查会在执行前被重新验证。tool_not_found_behavior模型调用不存在的工具默认情况下模型生成的函数工具调用名与当前 Agent 的任何函数工具都不匹配时Runner 抛出ModelBehaviorError。若希望运行保持可恢复状态设return_error_to_modelSDK 会为无法解析的工具调用追加一条function_call_output并重新运行模型让模型改选可用工具或直接回答。from agents import Agent, RunConfig, Runner agent Agent(nameAssistant, tools[...]) result await Runner.run( agent, Handle this request with the available tools., run_configRunConfig(tool_not_found_behaviorreturn_error_to_model), )当前该选项仅适用于工具名查找失败的函数工具调用其他无效工具载荷仍沿用既有错误行为。类型别名定义见 src/agents/run_config.py。tool_error_formatter定制工具错误消息SDK 构造返回给模型的工具错误输出时可用tool_error_formatter替换消息。格式化器接收带以下字段的ToolErrorFormatterArgskind错误类别如approval_rejected、tool_not_foundtool_type工具运行时如function、computer、shell、apply_patch、customtool_name工具名call_id工具调用 IDdefault_messageSDK 默认的可感知消息run_context当前激活的运行上下文包装器。返回字符串以替换消息返回None则使用 SDK 默认值。from agents import Agent, RunConfig, Runner, ToolErrorFormatterArgs def format_rejection(args: ToolErrorFormatterArgs[None]) - str | None: if args.kind approval_rejected: return ( fTool call {args.tool_name} was rejected by a human reviewer. Ask for confirmation or propose a safer alternative. ) if args.kind tool_not_found: return fTool {args.tool_name} is not available. Choose one of the listed tools. return None agent Agent(nameAssistant) result Runner.run_sync( agent, Please delete the production database., run_configRunConfig(tool_error_formatterformat_rejection), )reasoning_item_id_policy推理条目 ID 的保留与省略该策略控制 Runner 在继承历史时例如使用RunResult.to_input_list()或基于 session 的执行如何把推理条目转换为下一轮的模型输入None或preserve默认保留推理条目 IDomit从生成的下一轮输入中移除推理条目 ID。omit主要作为对一类 Responses API 400 错误的 opt-in 缓解当推理条目携带id发送、却缺少其必需的后继条目例如报错Item rs_... of type reasoning was provided without its required following item.时触发。这在 SDK 从上一轮输出构造后续输入的多轮 Agent 执行中可能发生涉及 session 持久化、服务端管理的会话差分、流式与非流式的后续轮次以及恢复路径。设omit后推理内容仍然保留只是去掉推理条目的id从而避免违反该 API 不变量。适用范围注意仅修改 SDK 构造后续输入时生成或转发的推理条目不会重写用户显式提供的初始输入条目call_model_input_filter在该策略生效后仍可有意地重新引入推理 ID。类型定义ReasoningItemIdPolicy Literal[preserve, omit]见 src/agents/run_config.py。三、状态与会话管理3.1 选择记忆策略四种方案对比把状态传递到下一轮常见的有四种方式策略状态存放位置最佳用途下一轮需要传入的内容result.to_input_list()应用内存小型聊天循环、完全手动控制、任意 providerto_input_list()返回的列表 下一条用户消息session存储层 SDK持久化聊天状态、可恢复执行、自定义存储同一个session实例或引用同一存储的另一个实例conversation_idOpenAI Conversations API在 worker / 服务间共享的具名服务端会话同一个conversation_id 新用户回合previous_response_idOpenAI Responses API不创建会话资源的轻量服务端续接result.last_response_id 新用户回合to_input_list()与session属于客户端管理conversation_id与previous_response_id属于OpenAI 管理仅在走 OpenAI Responses API 时适用。大多数应用请为每个会话选择一种持久化策略除非有意协调两层否则混用客户端历史与服务端状态可能造成上下文重复。注意同一次执行中不能同时使用 session 持久化与服务端会话设置conversation_id、previous_response_id或auto_previous_response_id每次调用只能选择其中一种方式。3.2 会话与聊天线程一次执行方法调用可能驱动一个或多个 Agent、引发一次或多次 LLM 调用但在聊天会话层面它只代表一个逻辑回合例如用户回合用户输入文本Runner 执行首个 Agent 调用 LLM、执行工具然后 handoff 给第二个 Agent第二个 Agent 继续执行工具并生成输出。执行结束后你可以自行选择展示给用户的内容展示 Agent 生成的全部新条目或仅展示最终输出。之后用户可能继续提问此时再次调用执行方法即可。手动管理会话to_input_list()from agents import Agent, Runner, trace async def main(): agent Agent(nameAssistant, instructionsReply very concisely.) thread_id thread_123 # Example thread ID with trace(workflow_nameConversation, group_idthread_id): # First turn result await Runner.run(agent, What city is the Golden Gate Bridge in?) print(result.final_output) # San Francisco # Second turn new_input result.to_input_list() [{role: user, content: What state is it in?}] result await Runner.run(agent, new_input) print(result.final_output) # Californiato_input_list()定义于RunResultBase支持mode参数默认preserve_all控制返回条目的保真程度。Sessions 自动管理会话更省事的方式是使用 Sessions无需手动调用.to_input_list()from agents import Agent, Runner, SQLiteSession, trace async def main(): agent Agent(nameAssistant, instructionsReply very concisely.) # Create session instance session SQLiteSession(conversation_123) thread_id thread_123 # Example thread ID with trace(workflow_nameConversation, group_idthread_id): # First turn result await Runner.run(agent, What city is the Golden Gate Bridge in?, sessionsession) print(result.final_output) # San Francisco # Second turn - agent automatically remembers previous context result await Runner.run(agent, What state is it in?, sessionsession) print(result.final_output) # CaliforniaSessions 会自动完成三件事每次执行前取回会话历史每次执行后保存新消息按 session ID 维护相互独立的会话。服务端管理的会话Server-Managed Conversations除了本地处理还可以用 OpenAI 的会话状态能力在服务端维护会话从而无需手动重发全部历史消息。两种服务端方式都在每个请求中只传新回合输入、复用保存的 ID。方式 1conversation_id——先用 OpenAI Conversations API 创建会话后续所有调用复用该 IDfrom agents import Agent, Runner from openai import AsyncOpenAI client AsyncOpenAI() async def main(): agent Agent(nameAssistant, instructionsReply very concisely.) # Create a server-managed conversation conversation await client.conversations.create() conv_id conversation.id while True: user_input input(You: ) result await Runner.run(agent, user_input, conversation_idconv_id) print(fAssistant: {result.final_output})方式 2previous_response_id响应链式续接——把每个回合显式关联到上一回合的响应 IDfrom agents import Agent, Runner async def main(): agent Agent(nameAssistant, instructionsReply very concisely.) previous_response_id None while True: user_input input(You: ) # Setting auto_previous_response_idTrue enables response chaining automatically # for the first turn, even when theres no actual previous response ID yet. result await Runner.run( agent, user_input, previous_response_idprevious_response_id, auto_previous_response_idTrue, ) previous_response_id result.last_response_id print(fAssistant: {result.final_output})last_response_id属性定义于 src/agents/result.py返回最后一次模型响应的 ID。补充要点当执行因等待审批暂停并从RunState恢复时SDK 会保留保存的conversation_id/previous_response_id/auto_previous_response_id设置使恢复后的回合继续在同一服务端会话中conversation_id与previous_response_id不可同时使用需要跨系统共享的具名会话资源用conversation_id需要回合间最轻量的 Responses API 续接基元用previous_response_idSDK 会对conversation_locked错误进行带退避的自动重试服务端会话执行在重试前会回滚内部会话跟踪器的输入从而可安全重发相同已准备条目本地 session 执行也会尽力回滚最近持久化的输入条目减少重试后的历史重复。该兼容性重试即使未设置ModelSettings.retry也会执行更广泛的模型请求 opt-in 重试行为见 模型文档。四、钩子与定制call_model_input_filtercall_model_input_filter在模型调用前一刻编辑模型输入。钩子接收当前 Agent、上下文与合并后的输入条目含 session 历史如有返回新的ModelInputData。返回值必须是ModelInputData对象其input字段必填且必须是输入条目列表返回其他形式会触发UserError。from agents import Agent, Runner, RunConfig from agents.run import CallModelData, ModelInputData def drop_old_messages(data: CallModelData[None]) - ModelInputData: # Keep only the last 5 items and preserve existing instructions. trimmed data.model_data.input[-5:] return ModelInputData(inputtrimmed, instructionsdata.model_data.instructions) agent Agent(nameAssistant, instructionsAnswer concisely.) result Runner.run_sync( agent, Explain quines, run_configRunConfig(call_model_input_filterdrop_old_messages), )Runner 会把准备输入列表的副本交给钩子因此可以在不原地修改调用方原列表的情况下完成裁剪、替换、重排。执行时机语义使用 Sessions 时call_model_input_filter在会话历史已加载并与当前回合合并之后运行想定制更早的合并过程本身改用session_input_callback使用conversation_id/previous_response_id/auto_previous_response_id服务端会话时钩子作用于为下一次 Responses API 调用准备的载荷该载荷可能已只包含新回合的差分而不再重发全部历史返回的条目会被记录为已发送。典型用途包括敏感数据脱敏、长历史裁剪、插入额外系统指令——均通过run_config按执行粒度配置。五、错误与恢复5.1 错误处理器error_handlers所有Runner入口都接受error_handlers一个以错误种类为键的字典支持的键为max_turns、model_refusal、invalid_final_output类型定义见 src/agents/run_error_handlers.py。当对应错误发生时不再以异常终止执行而是返回受控的最终输出。处理max_turns超出回合上限from agents import ( Agent, RunErrorHandlerInput, RunErrorHandlerResult, Runner, ) agent Agent(nameAssistant, instructionsBe concise.) def on_max_turns(_data: RunErrorHandlerInput[None]) - RunErrorHandlerResult: return RunErrorHandlerResult( final_outputI couldnt finish within the turn limit. Please narrow the request., include_in_historyFalse, ) result Runner.run_sync( agent, Analyze this long transcript, max_turns3, error_handlers{max_turns: on_max_turns}, ) print(result.final_output)处理invalid_final_output结构化输出校验失败当模型消息未通过 Agent 的 structuredoutput_type校验、或模型未返回结构化最终消息时使用。处理器可返回应用特定的回退值SDK 会针对同一output_type校验它SDK不会重试模型调用或重新执行工具副作用。返回None表示不恢复无回退时非空值的校验失败仍抛ModelBehaviorError空的结构化响应保持既有的下一回合行为。from pydantic import BaseModel from agents import Agent, ModelBehaviorError, RunErrorHandlerInput, Runner class Recipe(BaseModel): ingredients: list[str] recovered_from_invalid_output: bool False def on_invalid_final_output(data: RunErrorHandlerInput[None]) - Recipe: assert isinstance(data.error, ModelBehaviorError) return Recipe(ingredients[], recovered_from_invalid_outputTrue) agent Agent( nameRecipe assistant, instructionsReturn a structured recipe., output_typeRecipe, ) result Runner.run_sync( agent, Plan tonights dinner., error_handlers{invalid_final_output: on_invalid_final_output}, ) print(result.final_output)处理model_refusal模型拒绝当模型拒绝产生所请求的输出而抛ModelRefusalError时可生成应用特定的回退from pydantic import BaseModel from agents import Agent, ModelRefusalError, RunErrorHandlerInput, Runner class Recipe(BaseModel): ingredients: list[str] refusal_reason: str | None None def on_model_refusal(data: RunErrorHandlerInput[None]) - Recipe: assert isinstance(data.error, ModelRefusalError) return Recipe(ingredients[], refusal_reasondata.error.refusal) agent Agent( nameRecipe assistant, instructionsReturn a structured recipe., output_typeRecipe, ) result Runner.run_sync( agent, Make me something unsafe., error_handlers{model_refusal: on_model_refusal}, ) print(result.final_output)RunErrorHandlerResult.include_in_history默认为True在 max_turns 处理器中合成的回退输出会被加入会话历史并持久化到已配置的 session若只想把回退返回给调用方而不写入历史或存储设include_in_historyFalse。六、持久化执行集成与人在回路工具审批的暂停/恢复模式请从专门的人在回路指南开始。以下集成面向执行可能跨越长时间等待、重试与进程重启的持久化编排场景Dapr借助 Agents SDK 的 DaprDiagrid集成可运行自动从故障恢复、支持人在回路工作流的持久化长时 Agent。Dapr 是厂商中立的 CNCF 工作流编排器Temporal借助 Temporal 集成可运行包含人在回路任务的持久化长时工作流Restate借助 Restate 集成可实现包含人工审批、handoff 与会话管理的轻量持久化 Agent该集成把 Restate 单二进制运行时作为依赖Agent 可运行在进程、容器或 serverless 函数中DBOS借助 DBOS 集成可运行在故障与重启后仍保留进度的可靠 Agent支持长时 Agent、人在回路工作流与 handoff同步/异步方法均支持仅需 SQLite 或 Postgres 数据库。七、异常体系SDK 在特定情况下抛出异常完整列表见agents.exceptions。要点如下AgentsExceptionSDK 所有异常的基类其余专属异常均派生自该通用类型MaxTurnsExceededAgent 执行超过Runner.run/run_sync/run_streamed传入的max_turns时抛出表示 Agent 未能在指定回合数LLM 调用次数内完成任务max_turnsNone可禁用限制ModelTimeoutError模型调用尝试超过ModelSettings.timeout时抛出适用范围与重试行为见模型调用超时ModelBehaviorError底层模型产生意外或无效输出时抛出包括畸形 JSON模型在工具调用或直接输出中返回非法 JSON尤其定义了output_type时意外的工具相关失败模型未能按要求使用工具失败或未完成的非流式 Responses 调用最终状态为failed或incomplete时OpenAIResponsesModel与AnyLLMModel的 Responses 路径会抛出异常携带最终状态及响应中可取得的错误/未完成详情ModelRefusalError模型拒绝产生所请求的输出时抛出携带refusal文本ToolTimeoutError函数工具调用超过配置超时且工具使用timeout_behaviorraise_exception时抛出UserErrorSDK 使用方写代码时的失误通常源于实现错误、无效配置或 API 误用InputGuardrailTripwireTriggered/OutputGuardrailTripwireTriggered输入护栏条件满足时抛前者输出护栏条件满足时抛后者输入护栏在交付前检查入站消息输出护栏在交付前检查 Agent 最终响应。八、快速上手建议一次性脚本用Runner.run_sync()即可已在 async 环境FastAPI、Notebook中请改用Runner.run()。需要流式体验用Runner.run_streamed().stream_events()多轮复用 WebSocket 连接时包一层responses_websocket_session()。多轮对话轻量用result.to_input_list()手动续接需要持久化用 Sessions如 SQLiteSession 示例需要跨服务共享会话用conversation_id需要最简续接用previous_response_id。生产可靠性为max_turns/invalid_final_output/model_refusal配置error_handlers并善用tool_not_found_behaviorreturn_error_to_model与tool_error_formatter保持运行可恢复。可观测性至少设置RunConfig(workflow_name...)并按需配置group_id、trace_metadata与trace_include_sensitive_data。以上配置项与 API 均可在仓库的 src/agents/run.py、src/agents/run_config.py、src/agents/exceptions.py 中直接查阅相关行为也有对应单元测试与 API 契约如 tests/fixtures/released_api_contract.json可以佐证。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
