[Feature Request] Add REPL-style `run_demo_loop` utility for rapid agent testing and debugging

[solyarisoftware]

[Feature Request] Add REPL-style run_demo_loop utility for rapid agent testing and debugging

---

Summary

I would like to request the addition of a REPL-style utility function—analogous to swarm.repl.run_demo_loop—to the OpenAI Agents SDK. This function would facilitate rapid, interactive testing of agent behaviors from the command line, ideally supporting streaming output and preserving conversation state across multiple user-agent exchanges.

---

Motivation

In the previous OpenAI Swarm experimental framework, the run_demo_loop(agent, stream=True) function proved invaluable for quickly validating agent behaviors, tool invocations, and instruction tuning in a lightweight, interactive shell. This was especially useful during iterative development and debugging cycles.

As of now, the Agents SDK provides robust agent orchestration capabilities via Runner.run(), run_sync(), and run_streamed(), but lacks a simple, built-in interactive loop to simulate turn-based conversation flows in a terminal environment.

While some third-party developers have implemented ad-hoc REPL interfaces, an officially supported method would be preferable for maintainability, ergonomics, and consistency with SDK design patterns.

---

Requested Feature

• A built-in utility (e.g., agents.repl.run_demo_loop(agent, stream=True)) to:
  • Prompt the developer for input in a terminal loop
  • Stream or render agent responses in real time
  • Retain context across turns (i.e., use conversation state)
  • Optionally display tool calls and trace metadata

---

Benefits

• Enhances developer productivity for rapid prototyping and validation
• Improves debugging workflows without the need to write boilerplate scaffolding
• Encourages wider adoption by lowering the barrier to entry for experimentation

---

Example Usage

...
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    tools=[...],
)

run_demo_loop(agent, stream=True)

---

thanks
giorgio

[rm-openai]

@solyarisoftware just added. Can you try it out and let me know if it fits your needs?

[solyarisoftware]

Hi Rohan,
first of all, thank you for your contribution!

I haven't had a chance to run your code yet, but I’ve reviewed it here:
https://github.com/openai/openai-agents-python/pull/811/files/f33e41a2b64d7ef80d60f5de61c8596a1ac339ad#diff-cf9f3a1d3fc6e40be8f19012c069772d67b7993491b0324924b86731fa2efb72

I noticed that the original version of the file in the swarm repo:
https://github.com/openai/swarm/blob/main/swarm/repl/repl.py
includes some coloring features that can be quite helpful during quick prototyping in the command line.

More broadly, I think it would be valuable to consider adding observability utilities to trace events via the CLI. Having a robust CLI-based tracing/logging system could significantly enhance the development and debugging experience, especially during the prototyping phase.
Just a thought!

Thanks again,
Giorgio

[st3fan]

@rm-openai With 0.0.19 the run_demo_loop() function always returns the output twice ...

> hello

[Agent updated: Assistant]
Hi! How can I assist you today?Hi! How can I assist you today?

 > why did the python cross the road?

[Agent updated: Assistant]
Why did the Python cross the road?

To import the chicken module! 🐍🐔

Got any other fun questions or need help with something else?Why did the Python cross the road?

To import the chicken module! 🐍🐔

Got any other fun questions or need help with something else?

My code is super simple:

import asyncio

from agents import Agent, run_demo_loop


async def main():
    agent = Agent(
        name="Assistant",
        model="gpt-4o",
        instructions="You are a Canadian assistant.",
    )
    await run_demo_loop(agent)


if __name__ == "__main__":
    asyncio.run(main())

[DanieleMorotti]

Hi, if I'm not wrong the error is present on line 55 of agents/repl.py:

...
elif event.item.type == "message_output_item":
    message = ItemHelpers.text_message_output(event.item)
    print(message, end="", flush=True)

because it prints the message again after the streaming:

if isinstance(event, RawResponsesStreamEvent):
    if isinstance(event.data, ResponseTextDeltaEvent):
        print(event.data.delta, end="", flush=True)

If you're interested, I can change the code to avoid this. At the moment I haven't figured out if the removal of those lines may affect some other situations.

[rm-openai]

Yes please do @DanieleMorotti - thanks!

[DanieleMorotti]

Happy to help! Done