How autonomous AI agents orchestrate tools, handoffs, and guardrails — explained with animated diagrams
The core runtime cycle. The model generates a response, and if it includes tool calls or a handoff, the system executes them and loops back. The loop continues until the model produces a final text output.
The Python SDK provides primitives — Agent, Runner, Tools, Handoffs, and Guardrails — that compose into multi-agent systems. The Runner orchestrates everything.
An agent is a configuration: a model, instructions (system prompt), tools it can invoke, handoffs it can make, and guardrails that constrain it. It's declarative — the Runner brings it to life.
The Runner manages the agent loop: calls the model, executes tools, processes handoffs, checks guardrails, and manages state. Use Runner.run() for one-shot or Runner.run_streamed() for streaming.
Function tools (your Python functions), hosted tools (web search, file search, code interpreter), and computer-use tools. Each gets auto-converted to the model's tool schema.
An agent can hand control to another agent. The conversation history transfers, and the new agent takes over the loop. Enables specialization — a triage agent routes to domain experts.
A real-world pattern: a triage agent receives user input, determines intent, and hands off to a specialized agent that uses tools to fulfill the request.
Agents — LLM + instructions + tools. Handoffs — delegate to another agent. Guardrails — validate input/output. Tracing — built-in observability for debugging and eval.
Web Search — browse the internet. File Search — RAG over uploaded files. Code Interpreter — sandboxed Python execution. Computer Use — GUI interaction via screenshots.
Runner.run_streamed() yields events as they happen: RawResponsesStreamEvent for model tokens, RunItemStreamEvent for tool calls and messages, enabling real-time UIs.
Orchestrator — a central agent delegates. Pipeline — agents in sequence. Parallel — fan out to multiple agents. Evaluator — one agent checks another's output.