OpenAI Agents Python 示例库全景解读：从 Agent 设计模式到可自动化运行的完整案例体系

OpenAI Agents Python 示例库全景解读从 Agent 设计模式到可自动化运行的完整案例体系【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAI Agents Python SDK 仓库的examples/目录是学习该框架的最佳实践载体覆盖了从 Hello World 到多智能体编排、人机协同HITL、MCP 集成、会话记忆与沙箱运行的完整场景谱系。本文基于官方文档 examples 的类目结构结合仓库中真实的示例源码与执行脚本examples/README.md、examples/run_examples.py系统梳理每一类示例解决的问题、关键实现方式以及如何在本地一键运行这些示例帮助你快速定位并复用适合自身业务的 Agent 架构模式。示例目录总览15 个类目覆盖的完整能力面仓库的 examples 目录按功能划分为以下类目每一类都对应框架中的一个核心能力域类目目录覆盖的核心能力agent_patternsexamples/agent_patterns通用 Agent 设计模式确定性流程、Agents as tools、路由、并行、守卫Guardrail、HITLbasicexamples/basicSDK 基础功能Hello World、生命周期、工具、流式输出、文件处理、用量跟踪customer_serviceexamples/customer_service航空公司客服系统Handoff 上下文收集 结构化输出financial_research_agentexamples/financial_research_agent金融数据分析的结构化研究工作流handoffsexamples/handoffs智能体交接含消息过滤hosted_mcpexamples/hosted_mcpResponses API 托管 MCP连接器、中断审批mcpexamples/mcp自建 MCP 服务接入文件系统、Git、SSE、Streamable HTTP、管理器、工具过滤memoryexamples/memory多后端会话存储与 HITL 审批恢复model_providersexamples/model_providers非 OpenAI 模型的接入方式realtimeexamples/realtime实时语音/文本交互Web 应用、CLI 音频循环、Twilio 集成reasoning_contentexamples/reasoning_content推理内容Reasoning Content的处理与回放research_botexamples/research_bot多智能体深度研究 BotPlan → 并行搜索 → 撰写sandboxexamples/sandbox隔离工作空间中运行 AgentDocker / Modal 后端toolsexamples/toolsOpenAI 托管工具与实验性 Codex 工具链voiceexamples/voiceTTS/STT 语音 Agent静态与流式每个示例都以__main__保护的可运行脚本组织仓库自带的运行器 examples/run_examples.py 会扫描examples/下所有带__name__ __main__守卫的入口文件。下面按类目展开讲解。运行机制make examples-run 与自动化模式示例套件由仓库的 runner 与 Make 目标统一管理完整的前台自动运行命令为make examples-runrunner 参数通过EXAMPLES_ARGS透传例如make examples-run EXAMPLES_ARGS--filter basic make examples-run EXAMPLES_ARGS--include-server --include-audio后台运行与进程生命周期管理对应make examples-run-background、make examples-status、make examples-stop、make examples-logs、make examples-tail设置EXAMPLES_LOG可指定examples-tail使用的日志文件。这些目标定义在 Makefile 中底层调用bash .github/scripts/run_examples.sh。从源码看examples/README.md、examples/run_examples.py几个关键机制值得注意日志输出每次正常运行都会在.tmp/examples-start-logs/下写入主日志与每个示例的独立日志便于事后用--filter substring重跑子集定位问题。自动化模式auto mode当设置EXAMPLES_INTERACTIVE_MODEauto时examples/auto_mode.py 提供的input_with_fallback与confirm_with_fallback会跳过input()交互直接返回确定性的回退输入和默认确认值使示例可以无人值守执行。这也是许多示例中同时出现交互式提示和脚本化输入的写法原因。默认包含/排除策略默认保留自动输入与审批、包含交互式示例但排除需要常驻服务器、音频或外部依赖的示例除非显式选择。环境变量EXAMPLES_UV_EXTRAS控制uv安装的可选依赖 extrasEXAMPLES_INCLUDE_INTERACTIVE、EXAMPLES_INCLUDE_SERVER、EXAMPLES_INCLUDE_AUDIO、EXAMPLES_INCLUDE_EXTERNAL提供基于环境变量的包含开关。自动跳过清单runner 维护了一个DEFAULT_AUTO_SKIP集合跳过需要额外凭证或容易挂起的示例如examples/agent_patterns/llm_as_a_judge.py、examples/hosted_mcp/connectors.py。agent_patterns核心设计模式库这是最值得精读的类目examples/agent_patterns/README.md 汇总了框架的常见设计模式每个模式对应一个独立可运行脚本确定性工作流—— deterministic.py用代码编排 Agent 顺序执行而非让模型自行决策。示例中三个 Agent 串联story_outline_agent生成大纲 →outline_checker_agent以 Pydantic 模型OutlineCheckerOutput含good_quality、is_scifi两个布尔字段作为结构化输出做质量把关 → 只有通过检查才交给story_agent写正文。整个流程用with trace(Deterministic story flow):包裹为单一 trace是“代码控制流程 模型负责生成”的典型范式。Agents as tools—— agents_as_tools.pyorchestrator Agent 通过agent.as_tool(tool_name..., tool_description...)把西班牙/法语/意大利语翻译 Agent 注册为工具由编排者按需调用最后由synthesizer_agent对orchestrator_result.to_input_list()做汇总。同类扩展还包括使用流式事件agents_as_tools_streaming.py结构化输入参数agents_as_tools_structured.py条件分支变体agents_as_tools_conditional.py并行执行—— parallelization.py多个子 Agent 并发运行后聚合结果research_bot示例同样依赖该思想。路由Handoff—— routing.pytriage_agent通过handoffs[french_agent, spanish_agent, english_agent]按请求语言把对话交接给对应语言 Agent并用Runner.run_streamedtrace(group_idconversation_id)把每轮对话关联到同一会话 trace实时流式输出ResponseTextDeltaEvent。强制工具使用—— forcing_tool_use.py演示不同工具使用行为配置下的调用效果。输入/输出 Guardrail—— input_guardrails.py 与 output_guardrails.py以输入守卫为例示例定义了一个MathHomeworkOutputreasoning: str、is_math_homework: bool的结构化判定 Agent用input_guardrail装饰器包装的math_guardrail函数在 Agent 执行并行地运行检查命中时返回tripwire_triggeredTrue的GuardrailFunctionOutput框架随即抛出InputGuardrailTripwireTriggered接管执行。LLM as Judge—— llm_as_a_judge.py用一个 Agent 评估另一个 Agent 的输出质量。流式 Guardrail—— streaming_guardrails.py。HITL人机协同—— 三个递进示例human_in_the_loop.py基于工具审批与状态序列化的完整中断/恢复human_in_the_loop_stream.py流式场景下的 HITLhuman_in_the_loop_custom_rejection.py自定义审批拒绝消息。basicSDK 基础功能速查examples/basic 目录是 API 入门的第一站每个脚本聚焦一个特性Hello World—— hello_world.py 展示了最小可运行单元agent Agent(nameAssistant, instructionsYou only respond in haikus.) result await Runner.run(agent, Tell me about recursion in programming.) print(result.final_output)同类还有默认模型的 hello_world.py、GPT-5 变体 hello_world_gpt_5.py、开放权重模型变体 hello_world_gpt_oss.py。生命周期—— lifecycle_example.py 展示RunHooks与AgentHooks的使用agent_lifecycle_example.py 是补充变体。动态系统提示词—— dynamic_system_prompt.py演示将 instructions 写成可调用对象、在每轮运行时动态生成提示。基础工具—— tools.py 与 tool_guardrails.py工具输入/输出守卫。图像作为工具输出—— image_tool_output.py文件处理则包括本地文件 local_file.py、本地图片 local_image.py、远程图片 remote_image.py 与远程 PDF remote_pdf.pymedia/目录附带测试用 PDF 与图片资源。流式输出—— 三种粒度文本 stream_text.py、输出项 stream_items.py、函数调用参数 stream_function_call_args.pystream_ws.py 进一步演示在多个 Turn 间共享会话的 Responses WebSocket 传输。提示词模板—— prompt_template.py。用量跟踪—— usage_tracking.py。Runner 管理式重试—— retry.py 展示框架内置的模型调用重试配置retry_litellm.py 展示经第三方 LiteLLM 适配器时的重试。其他—— 非严格输出类型 non_strict_output_type.py、复用历史响应的 previous_response_id.py。业务型完整示例customer_service、research_bot、financial_research_agent航空公司客服系统—— customer_service/main.py 是“生产形态”的最小参考实现AirlineAgentContextPydantic 模型承载passenger_name、confirmation_number、seat_number、flight_number等对话状态tool装饰器定义faq_lookup_tool等工具handoff与RECOMMENDED_PROMPT_PREFIX构造客服、改签等子 Agent 间的交接主循环通过ItemHelpers处理MessageOutputItem、ToolCallItem、HandoffOutputItem等输出项类型完整演示了带上下文收集的多 Agent 客服架构。多 Agent 研究 Bot—— research_bot/README.md 给出了清晰的架构图用户输入主题 →planner_agent产出带理由的搜索查询计划 → 每个查询由search_agent调用 Web Search 工具并行搜索并摘要 →writer_agent汇总成报告。运行方式为python -m examples.research_bot.main。README 同时给出进阶方向向量检索、附件上下文、更长的规划与评估环节、代码执行。金融研究 Agent—— examples/financial_research_agent 用 Agent 与工具组合完成金融数据研究的结构化工作流入口 main.py 通过 manager.py 编排agents/下的多个专职 Agent并由 printer.py 统一格式化输出。handoffs交接与消息过滤message_filter.py演示在 Agent 交接时过滤传递的消息历史避免无关上下文被带到下游 Agent。message_filter_streaming.py同一机制在流式运行Runner.run_streamed下的实现。MCP托管与自建两条路线hosted_mcpResponses API 托管 MCPsimple.py无需审批直接使用托管 MCPconnectors.py接入 Google Calendar 等现成 MCP 连接器human_in_the_loop.py基于中断interruption的托管 MCP 审批流on_approval.py为 MCP 工具审批请求注册回调程序化处理审批决策。mcp自建 MCP 服务子目录各自独立可运行文件系统 filesystem_example 与 Git git_example本地 stdio 型 MCP 服务的典型接入提示词服务器 prompt_server使用 MCP 提供的 prompts 能力传输协议全覆盖SSE sse_example 与 SSE 远程连接 sse_remote_example、Streamable HTTP streamablehttp_example 与远程连接 streamable_http_remote_example、自定义 HTTP 客户端工厂 streamablehttp_custom_client_exampleget_all_mcp_tools_exampleMCPUtil.get_all_function_tools一次性预取全部 MCP 工具manager_example在 FastAPI 应用中使用MCPServerManager管理多个 MCP 服务器的连接生命周期tool_filter_example按名称/前缀过滤暴露给模型的 MCP 工具。框架侧的 MCP 客户端实现位于 src/agents/mcp 目录tests/mcp/下有大量单测覆盖缓存、重试、审批、工具过滤与版本兼容行为可配合示例深入阅读。memory多后端会话存储与 HITL 审批恢复examples/memory 演示了会话Session抽象在不同存储后端上的落地存储后端SQLite sqlite_session_example.py、高级 SQLite advanced_sqlite_session_example.py、Redis redis_session_example.py、SQLAlchemy sqlalchemy_session_example.py、Dapr 状态存储 dapr_session_example.py、MongoDB mongodb_session_example.py、加密存储 encrypted_session_example.py云端会话OpenAI Conversations openai_session_example.pyResponses 压缩compaction会话compaction_session_example.py以及使用ModelSettings(storeFalse)的无状态压缩版本 compaction_session_stateless_example.py文件型会话file_session.py 及其 HITL 变体 file_hitl_example.pyHITL 审批场景四连SQLite 内存会话 HITL memory_session_hitl_example.py、OpenAI Conversations HITL openai_session_hitl_example.py、跨多个会话的审批/拒绝场景 hitl_session_scenario.py。会话抽象的接口定义在 src/agents/memory文档侧的存储方案说明可参考 docs/sessions。model_providers接入 OpenAI 之外的模型examples/model_providers/README.md 说明该目录聚焦“SDK 中使用非 OpenAI 模型”的两种方式自定义 Provider 实现custom_example_provider.py、custom_example_agent.py、全局注册的 custom_example_global.py第三方适配器LiteLLM 方式 litellm_provider.py、litellm_auto.py以及任意 LLM 的自动接入 any_llm_provider.py、any_llm_auto.py。对应的模型层实现位于 src/agents/models文档 docs/models 与 docs/models/litellm.md 提供更完整的参数说明。realtime、voice 与 reasoning_content多模态交互realtime—— examples/realtime 覆盖四种形态结构化文本图像消息的 Web 应用examples/realtime/app含 README 与 FastAPI 服务端 server.py、命令行音频循环与回放examples/realtime/cli、基于 WebSocket 的 Twilio Media Streams 集成examples/realtime/twilio、以及使用 Realtime Calls APIattach流程的 Twilio SIP 集成examples/realtime/twilio_sip。voice—— examples/voice 分 static 与 streamed 两组分别演示 TTS/STT 模型的静态调用与流式语音 Agent。reasoning_content—— examples/reasoning_contentrunner_example.py 演示 Runner API 中流式/非流式处理推理内容gpt_oss_stream.py 演示经 OpenRouter 使用开源模型时的推理内容流main.py 为基础用法。sandbox隔离工作空间中的 Agentexamples/sandbox/README.md 是理解该目录的入口代表脚本 basic.py 展示了SandboxAgentManifest的核心用法源码中可见其支持docker与modal两种后端Backend Literal[docker, modal]工作区持久化支持tar、snapshot_filesystem、snapshot_directory三种模式WorkspacePersistenceMode并允许挂载自定义能力如WorkspaceShellCapability与 src/agents/sandbox 提供的文件系统工具。目录内还包含Unix 本地沙箱生命周期unix_local_runner.py 与 PTY 变体 unix_local_pty.pyDocker 沙箱examples/sandbox/docker沙箱 Handoffhandoffs.py沙箱记忆与快照恢复memory.py、多 Agent 多轮记忆 memory_multi_agent_multiturn.py、S3 记忆 memory_s3.py、远程快照恢复 sandbox_agent_with_remote_snapshot.py把沙箱 Agent 作为工具暴露sandbox_agents_as_tools.py其他工具化沙箱 Agent sandbox_agent_with_tools.py、能力配置 sandbox_agent_capabilities.py、共享会话工作目录 shared_session_workdirs.py、报税场景 tax_prep.py、扩展与教程 examples/sandbox/extensions 与 examples/sandbox/tutorials。toolsOpenAI 托管工具与实验性 Codexexamples/tools 目录演示了框架对“模型侧托管工具”的封装网络与文件Web 搜索 web_search.py 与带过滤器的 web_search_filters.py、文件搜索 file_search.py、代码解释器 code_interpreter.py补丁应用apply_patch.py文件编辑与审批流程框架侧实现见 src/agents/apply_diff.py 与 src/agents/editor.py壳与技能带审批回调的 Shell shell.py、基于 HITL 中断审批的 Shell shell_human_in_the_loop.py、内联技能的托管容器 Shell container_shell_inline_skill.py、技能引用的容器 Shell container_shell_skill_reference.py、本地技能 Shell local_shell_skill.py技能提示词位于 examples/tools/skills工具检索tool_search.py 演示使用命名空间与懒加载降低工具暴露面编程式工具调用programmatic_tool_calling.py 演示并发结构化工具调用计算机使用computer_use.py底层动作类型定义在 src/agents/computer.py图像生成image_generator.py实验性 Codexcodex.py 与复用同一 Codex 对话线程的 codex_same_thread.py。如何基于示例库构建自己的 Agent 系统结合上面的梳理推荐的阅读与落地路径是先用 examples/basic 打通AgentRunner的最小闭环理解run/run_streamed与输出项类型再按业务形态选模式固定流程走 deterministic.py 的确定性编排需要“调度者 专家”走 Agents as tools需要对话中途换 Agent 走 routing/handoffs加入可靠性组件输入/输出 Guardrail、HITL 审批、重试、会话存储需要外部能力时按需选择 MCPexamples/mcp、examples/hosted_mcp、托管工具examples/tools或沙箱执行examples/sandbox本地验证统一走make examples-run EXAMPLES_ARGS--filter 关键字配合.tmp/examples-start-logs/中的分示例日志排查问题注意交互式/服务器/音频类示例需要显式的--include-*参数或对应环境变量才会纳入运行。所有示例均可直接以python examples/类目/脚本.py方式单独运行需要OPENAI_API_KEY及相应示例声明的额外依赖仓库对示例的持续回归保障也来自 examples/run_examples.py 这套扫描-运行-日志机制阅读示例时与其 runner 实现对照可以快速判断某个示例在自动化环境下是否有特殊的前置条件。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考