openai-agents-python REPL 实用工具用 run_demo_loop 在终端中交互式调试你的 Agent【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonrun_demo_loop是 openai-agents-python SDK 内置的 REPLRead-Eval-Print Loop调试工具让你无需编写额外的 Web 界面或测试脚手架直接在终端里以多轮对话的方式快速验证 Agent 的行为。读完本文你将掌握run_demo_loop的完整用法、全部参数含义、底层流式事件处理机制以及如何用它调试工具调用、Handoff 等复杂场景。一、什么是 run_demo_loopSDK 在 src/agents/repl.py 中提供了run_demo_loop官方文档 docs/repl.md 将其定位为「直接在终端中快速、交互式地测试 Agent 行为」的实用工具。它本质上是一个基于asyncio的死循环不断提示用户输入 → 交给 Runner 执行 → 打印模型输出 → 继续等待下一条输入直到用户主动退出。该函数通过 src/agents/init.py 导出为公开 APIfrom agents import run_demo_loop并收录在 docs/ref/repl.md 的 API 参考中属于稳定的公开接口。二、最小可运行示例官方文档给出的入门示例见 docs/repl.md如下import asyncio from agents import Agent, run_demo_loop async def main() - None: agent Agent(nameAssistant, instructionsYou are a helpful assistant.) await run_demo_loop(agent) if __name__ __main__: asyncio.run(main())将上述代码保存为demo.py在项目目录下运行python demo.py注意运行前需要设置OPENAI_API_KEY环境变量或配置其他模型提供商并确保已安装openai-agents及其依赖。之后run_demo_loop会启动一个交互式聊天会话终端出现提示符等待你输入。三、交互行为详解从 docs/repl.md 的说明和 src/agents/repl.py 的实现来看这个循环具备以下核心行为1. 多轮对话历史自动保留每一轮用户输入都会被追加到input_items列表中并在下一轮执行时作为完整的输入历史传给 Runner。具体来说每轮循环结束时current_agent result.last_agent input_items result.to_input_list()result.to_input_list()会把当前轮的所有输入项用户消息、模型响应、工具调用等序列化为可继续传递的输入列表从而实现跨轮记忆result.last_agent用于处理 Handoff 场景如果 Agent 在对话中把控制权交给了另一个 Agent下一轮对话会自动从新的 Agent 继续此时终端会打印[Agent updated: 新Agent名]提示。因此Agent 能记住整个会话期间讨论过的内容实现真正的多轮上下文。2. 退出方式结束聊天会话有三种方式实现见 src/agents/repl.py方式说明输入quit并按 Enter触发退出不区分大小写QUIT同样有效输入exit并按 Enter同上按Ctrl-DEOF或Ctrl-CKeyboardInterrupt捕获EOFError/KeyboardInterrupt后正常退出并打印一个空行收尾3. 空输入自动跳过如果直接按 Enter 提交空字符串循环会continue跳过该轮不会调用模型、不会产生多余的对话轮次对应测试见 tests/test_repl.py 中的test_run_demo_loop_skips_empty_input。四、完整函数签名与参数说明run_demo_loop的完整签名源码见 src/agents/repl.pyasync def run_demo_loop( agent: Agent[Any], *, stream: bool True, context: TContext | None None, max_turns: int | None DEFAULT_MAX_TURNS, ) - None:参数类型默认值作用agentAgent[Any]必填起始 Agent即对话开始时执行的那个 AgentstreamboolTrue是否流式输出模型结果True时边生成边打印contextTContextNone传递给 Runner 的额外上下文对象可携带会话级状态max_turnsint \| NoneDEFAULT_MAX_TURNS单次运行的最大轮数上限传None表示不限制其中DEFAULT_MAX_TURNS定义在 src/agents/run_config.py默认值为10。这里的「turn」指一次模型调用可能包含若干工具调用注意它是针对单次 Runner 执行的限制而 REPL 的每一条用户输入都会触发一次新的 Runner 执行所以多轮对话总体不受该值限制。关闭流式输出若把stream设为False循环会走非流式路径等待完整结果后一次性打印final_output见 src/agents/repl.pyawait run_demo_loop(agent, streamFalse)这在输出稳定、不需要实时反馈的场景下更省资源。五、流式模式底层机制事件驱动的实时输出当streamTrue默认时run_demo_loop调用Runner.run_streamed(...)然后遍历result.stream_events()产生的事件流按事件类型分别处理见 src/agents/repl.py。事件类型定义于 src/agents/stream_events.py主要包括三类1. RawResponsesStreamEvent原始模型流事件if isinstance(event, RawResponsesStreamEvent): if isinstance(event.data, ResponseTextDeltaEvent): print(event.data.delta, end, flushTrue)这是 LLM 直接透传的原始事件。其中ResponseTextDeltaEvent携带文本增量delta代码用end和flushTrue实现逐字流式打印——这正是「模型输出边生成边实时显示」的原理。2. RunItemStreamEvent语义级运行项事件当 Agent 调用工具时会触发工具调用与工具输出事件REPL 用[tool called]/[tool output: ...]标记打印elif isinstance(event, RunItemStreamEvent): if event.item.type tool_call_item: print(\n[tool called], flushTrue) elif event.item.type tool_call_output_item: print(f\n[tool output: {event.item.output}], flushTrue)这让你在终端中就能实时观察到 Agent 正在调用什么工具、工具返回了什么结果非常适合调试工具链。3. AgentUpdatedStreamEventAgent 切换事件elif isinstance(event, AgentUpdatedStreamEvent): print(f\n[Agent updated: {event.new_agent.name}], flushTrue)当发生 HandoffAgent 把控制权移交给另一个 Agent时打印新 Agent 的名称让你清楚当前对话由谁在应答。上述三条分支在 tests/test_repl.py 的test_run_demo_loop_streaming中被完整覆盖该测试构造了一个单轮内依次触发「工具调用 → 工具输出 → Handoff → 文本回答」的模型脚本断言终端输出同时包含[tool called]、[tool output: tool_result]、[Agent updated: target]和all done。六、用 REPL 调试工具调用与多 Agent 场景流式事件机制让 REPL 成为调试复杂 Agent 的利器。例如一个带工具和 Handoff 的 Agentimport asyncio from agents import Agent, function_tool, run_demo_loop function_tool def get_weather(city: str) - str: 查询指定城市的天气 return f{city} 今天晴25℃ async def main() - None: weather_agent Agent( nameWeatherAgent, instructions使用天气工具回答用户问题。, tools[get_weather], ) research_agent Agent( nameResearchAgent, instructions你是研究助手复杂问题转交给 WeatherAgent。, handoffs[weather_agent], ) await run_demo_loop(research_agent, max_turns5) if __name__ __main__: asyncio.run(main())运行后你会看到典型的交互过程 北京天气如何 [tool called] [tool output: 北京 今天晴25℃] 北京今天天气晴朗气温 25℃。当问题触发 Handoff 时终端会先打印[Agent updated: WeatherAgent]随后由新 Agent 继续应答——相当于在终端里可视化整个多 Agent 协作链路。七、调试与测试保障仓库为run_demo_loop提供了系统性的单元测试见 tests/test_repl.py通过ScriptedModelsrc/agents/testing预置模型响应用monkeypatch模拟builtins.input从而无需真实 API 即可验证 REPL 的全部行为test_run_demo_loop_conversation验证多轮对话历史确实传递给了模型断言第二轮的输入包含第一轮的用户消息与模型回答test_run_demo_loop_streaming验证流式模式下工具调用、工具输出、Agent 切换三条打印分支test_run_demo_loop_exits_on_eof验证Ctrl-DEOF能干净退出且不触发任何模型调用test_run_demo_loop_skips_empty_input验证空输入被跳过、不污染对话历史。这些测试直接印证了上文描述的全部行为如果你想扩展 REPL例如自定义退出指令或增加彩色输出可以参考这些测试来保证新行为的正确性。八、使用建议与注意事项适合快速原型验证在编写正式 CLI、Web 应用或测试用例之前用run_demo_loop几分钟内验证 Agent 的指令、工具和 Handoff 是否符合预期是最快的反馈回路。max_turns限制的是单轮执行若 Agent 单个任务需要多轮工具调用注意DEFAULT_MAX_TURNS 10src/agents/run_config.py可能不够可显式调大或传None。context参数可注入会话状态如果你的工具依赖外部上下文如用户身份、数据库连接可通过context传入Runner 会将其包装进RunContextWrapper供工具访问相关机制见 src/agents/run_context.py。生产环境请自行封装run_demo_loop是面向终端调试的轻量工具生产环境的多轮对话建议使用 docs/sessions.md 中介绍的 Session 持久化方案或基于 Runner.run 构建自己的对话循环。总结run_demo_loop以约 60 行代码src/agents/repl.py实现了终端交互调试所需的全部要素多轮历史记忆、默认流式输出、工具调用可视化、Handoff 感知和三种退出方式。它既是快速上手 openai-agents-python 的入口也是日常开发中验证 Agent 行为最直接的工具。结合官方文档 docs/repl.md、API 参考 docs/ref/repl.md 与测试用例 tests/test_repl.py你可以放心地将它纳入自己的调试工作流。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
openai-agents-python REPL 实用工具：用 run_demo_loop 在终端中交互式调试你的 Agent
openai-agents-python REPL 实用工具用 run_demo_loop 在终端中交互式调试你的 Agent【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonrun_demo_loop是 openai-agents-python SDK 内置的 REPLRead-Eval-Print Loop调试工具让你无需编写额外的 Web 界面或测试脚手架直接在终端里以多轮对话的方式快速验证 Agent 的行为。读完本文你将掌握run_demo_loop的完整用法、全部参数含义、底层流式事件处理机制以及如何用它调试工具调用、Handoff 等复杂场景。一、什么是 run_demo_loopSDK 在 src/agents/repl.py 中提供了run_demo_loop官方文档 docs/repl.md 将其定位为「直接在终端中快速、交互式地测试 Agent 行为」的实用工具。它本质上是一个基于asyncio的死循环不断提示用户输入 → 交给 Runner 执行 → 打印模型输出 → 继续等待下一条输入直到用户主动退出。该函数通过 src/agents/init.py 导出为公开 APIfrom agents import run_demo_loop并收录在 docs/ref/repl.md 的 API 参考中属于稳定的公开接口。二、最小可运行示例官方文档给出的入门示例见 docs/repl.md如下import asyncio from agents import Agent, run_demo_loop async def main() - None: agent Agent(nameAssistant, instructionsYou are a helpful assistant.) await run_demo_loop(agent) if __name__ __main__: asyncio.run(main())将上述代码保存为demo.py在项目目录下运行python demo.py注意运行前需要设置OPENAI_API_KEY环境变量或配置其他模型提供商并确保已安装openai-agents及其依赖。之后run_demo_loop会启动一个交互式聊天会话终端出现提示符等待你输入。三、交互行为详解从 docs/repl.md 的说明和 src/agents/repl.py 的实现来看这个循环具备以下核心行为1. 多轮对话历史自动保留每一轮用户输入都会被追加到input_items列表中并在下一轮执行时作为完整的输入历史传给 Runner。具体来说每轮循环结束时current_agent result.last_agent input_items result.to_input_list()result.to_input_list()会把当前轮的所有输入项用户消息、模型响应、工具调用等序列化为可继续传递的输入列表从而实现跨轮记忆result.last_agent用于处理 Handoff 场景如果 Agent 在对话中把控制权交给了另一个 Agent下一轮对话会自动从新的 Agent 继续此时终端会打印[Agent updated: 新Agent名]提示。因此Agent 能记住整个会话期间讨论过的内容实现真正的多轮上下文。2. 退出方式结束聊天会话有三种方式实现见 src/agents/repl.py方式说明输入quit并按 Enter触发退出不区分大小写QUIT同样有效输入exit并按 Enter同上按Ctrl-DEOF或Ctrl-CKeyboardInterrupt捕获EOFError/KeyboardInterrupt后正常退出并打印一个空行收尾3. 空输入自动跳过如果直接按 Enter 提交空字符串循环会continue跳过该轮不会调用模型、不会产生多余的对话轮次对应测试见 tests/test_repl.py 中的test_run_demo_loop_skips_empty_input。四、完整函数签名与参数说明run_demo_loop的完整签名源码见 src/agents/repl.pyasync def run_demo_loop( agent: Agent[Any], *, stream: bool True, context: TContext | None None, max_turns: int | None DEFAULT_MAX_TURNS, ) - None:参数类型默认值作用agentAgent[Any]必填起始 Agent即对话开始时执行的那个 AgentstreamboolTrue是否流式输出模型结果True时边生成边打印contextTContextNone传递给 Runner 的额外上下文对象可携带会话级状态max_turnsint \| NoneDEFAULT_MAX_TURNS单次运行的最大轮数上限传None表示不限制其中DEFAULT_MAX_TURNS定义在 src/agents/run_config.py默认值为10。这里的「turn」指一次模型调用可能包含若干工具调用注意它是针对单次 Runner 执行的限制而 REPL 的每一条用户输入都会触发一次新的 Runner 执行所以多轮对话总体不受该值限制。关闭流式输出若把stream设为False循环会走非流式路径等待完整结果后一次性打印final_output见 src/agents/repl.pyawait run_demo_loop(agent, streamFalse)这在输出稳定、不需要实时反馈的场景下更省资源。五、流式模式底层机制事件驱动的实时输出当streamTrue默认时run_demo_loop调用Runner.run_streamed(...)然后遍历result.stream_events()产生的事件流按事件类型分别处理见 src/agents/repl.py。事件类型定义于 src/agents/stream_events.py主要包括三类1. RawResponsesStreamEvent原始模型流事件if isinstance(event, RawResponsesStreamEvent): if isinstance(event.data, ResponseTextDeltaEvent): print(event.data.delta, end, flushTrue)这是 LLM 直接透传的原始事件。其中ResponseTextDeltaEvent携带文本增量delta代码用end和flushTrue实现逐字流式打印——这正是「模型输出边生成边实时显示」的原理。2. RunItemStreamEvent语义级运行项事件当 Agent 调用工具时会触发工具调用与工具输出事件REPL 用[tool called]/[tool output: ...]标记打印elif isinstance(event, RunItemStreamEvent): if event.item.type tool_call_item: print(\n[tool called], flushTrue) elif event.item.type tool_call_output_item: print(f\n[tool output: {event.item.output}], flushTrue)这让你在终端中就能实时观察到 Agent 正在调用什么工具、工具返回了什么结果非常适合调试工具链。3. AgentUpdatedStreamEventAgent 切换事件elif isinstance(event, AgentUpdatedStreamEvent): print(f\n[Agent updated: {event.new_agent.name}], flushTrue)当发生 HandoffAgent 把控制权移交给另一个 Agent时打印新 Agent 的名称让你清楚当前对话由谁在应答。上述三条分支在 tests/test_repl.py 的test_run_demo_loop_streaming中被完整覆盖该测试构造了一个单轮内依次触发「工具调用 → 工具输出 → Handoff → 文本回答」的模型脚本断言终端输出同时包含[tool called]、[tool output: tool_result]、[Agent updated: target]和all done。六、用 REPL 调试工具调用与多 Agent 场景流式事件机制让 REPL 成为调试复杂 Agent 的利器。例如一个带工具和 Handoff 的 Agentimport asyncio from agents import Agent, function_tool, run_demo_loop function_tool def get_weather(city: str) - str: 查询指定城市的天气 return f{city} 今天晴25℃ async def main() - None: weather_agent Agent( nameWeatherAgent, instructions使用天气工具回答用户问题。, tools[get_weather], ) research_agent Agent( nameResearchAgent, instructions你是研究助手复杂问题转交给 WeatherAgent。, handoffs[weather_agent], ) await run_demo_loop(research_agent, max_turns5) if __name__ __main__: asyncio.run(main())运行后你会看到典型的交互过程 北京天气如何 [tool called] [tool output: 北京 今天晴25℃] 北京今天天气晴朗气温 25℃。当问题触发 Handoff 时终端会先打印[Agent updated: WeatherAgent]随后由新 Agent 继续应答——相当于在终端里可视化整个多 Agent 协作链路。七、调试与测试保障仓库为run_demo_loop提供了系统性的单元测试见 tests/test_repl.py通过ScriptedModelsrc/agents/testing预置模型响应用monkeypatch模拟builtins.input从而无需真实 API 即可验证 REPL 的全部行为test_run_demo_loop_conversation验证多轮对话历史确实传递给了模型断言第二轮的输入包含第一轮的用户消息与模型回答test_run_demo_loop_streaming验证流式模式下工具调用、工具输出、Agent 切换三条打印分支test_run_demo_loop_exits_on_eof验证Ctrl-DEOF能干净退出且不触发任何模型调用test_run_demo_loop_skips_empty_input验证空输入被跳过、不污染对话历史。这些测试直接印证了上文描述的全部行为如果你想扩展 REPL例如自定义退出指令或增加彩色输出可以参考这些测试来保证新行为的正确性。八、使用建议与注意事项适合快速原型验证在编写正式 CLI、Web 应用或测试用例之前用run_demo_loop几分钟内验证 Agent 的指令、工具和 Handoff 是否符合预期是最快的反馈回路。max_turns限制的是单轮执行若 Agent 单个任务需要多轮工具调用注意DEFAULT_MAX_TURNS 10src/agents/run_config.py可能不够可显式调大或传None。context参数可注入会话状态如果你的工具依赖外部上下文如用户身份、数据库连接可通过context传入Runner 会将其包装进RunContextWrapper供工具访问相关机制见 src/agents/run_context.py。生产环境请自行封装run_demo_loop是面向终端调试的轻量工具生产环境的多轮对话建议使用 docs/sessions.md 中介绍的 Session 持久化方案或基于 Runner.run 构建自己的对话循环。总结run_demo_loop以约 60 行代码src/agents/repl.py实现了终端交互调试所需的全部要素多轮历史记忆、默认流式输出、工具调用可视化、Handoff 感知和三种退出方式。它既是快速上手 openai-agents-python 的入口也是日常开发中验证 Agent 行为最直接的工具。结合官方文档 docs/repl.md、API 参考 docs/ref/repl.md 与测试用例 tests/test_repl.py你可以放心地将它纳入自己的调试工作流。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
