Multi-agent research-and-report pipeline with handoffs, guardrails, and tracing

What they did

They started from the OpenAI Agents SDK quickstart, created a Python 3.10+ virtualenv, and installed openai-agents. They defined a triage Agent with instructions that classify an incoming request, then registered two specialist agents (a researcher and a writer) and exposed them to the triage agent via handoffs so delegation happens inside a single Runner.run call. Each specialist got function tools for the actual work: a web-search-style lookup tool and a file-write tool, plus an output guardrail that rejects drafts missing required sections. They enabled Sessions so conversation history persists across runs, and relied on built-in Tracing to inspect each handoff and tool call in the trace UI. They also experimented with agents-as-tools for a summarizer sub-agent that returns a compact digest rather than taking over the conversation. Finally they wrapped the whole flow in a small CLI that takes a topic string, runs the pipeline, and prints the final output plus a trace link.

How it went

The pipeline runs end to end: a single prompt produces a researched draft with a visible trace showing triage, handoff, tool calls, and guardrail checks. Polish is prototype-level — prompts are hand-tuned, the guardrail is a simple keyword check, and there is no retry or cost control. It works well as a demo and a base to extend.

Worth knowing

Requires an OPENAI_API_KEY and network access; the sandbox examples need macOS/Linux or a Docker extra on Windows. Guardrails here are shallow and won't catch subtle errors. No evaluation harness, rate-limit handling, or persistence beyond in-memory sessions, and handoff loops are possible if triage instructions are vague.

Wiring

Install with `pip install openai-agents` (or `uv add openai-agents`) in a Python 3.10+ environment and export OPENAI_API_KEY. Define tools as plain Python functions decorated with @function_tool, then attach them to Agent(tools=[...]). Create specialist agents first, then a triage Agent whose handoffs=[researcher, writer] list enables delegation; Runner.run_sync(triage, input) drives the whole flow. Add input_guardrails/output_guardrails on the relevant agents, pass a Session (e.g. SQLiteSession) to Runner.run for history, and read the trace from the run result or the tracing dashboard. Optional extras: `openai-agents[voice]` for voice pipelines, `openai-agents[redis]` for Redis sessions, `openai-agents[docker]` for DockerSandboxClient on Windows.

Try it yourself

Set up a Python 3.11 venv and install openai-agents. Build a multi-agent pipeline in a single module: a triage Agent that classifies a user request and hands off to either a Researcher agent (with a stub search tool returning canned results) or a Writer agent (with a tool that writes markdown to ./out). Add an output guardrail on the Writer that rejects drafts under 200 words, enable Sessions for conversation history, and add a CLI entrypoint `python -m pipeline "<topic>"` that prints the final output and the trace ID. Include a README with setup steps and one example run.