Patterns

Working example agents for common patterns, each with its source, tests and a recorded run against a real model. Run one in place, read it, or copy it into your project:

uv run python scripts/add_agent.py                      # pick one from a menu
uv run python scripts/add_agent.py router --name support

Pattern	What it shows
Blank	An empty agent: one output type, one prompt, no tools. Start here and build from scratch.
Single agent	One agent handles the whole task, with structured output and a prompt file.
Tool-calling agent	An agent that calls tools against external systems, with the three-outcome error convention.
Structured extraction	Turn free text into a validated schema, with an output validator that sends bad answers back for correction.
Retrieval (RAG)	Answer from your own documents by meaning, with embeddings in a Chroma vector database running as a service, and cite only passages the model really retrieved.
MCP tools	Give an agent the tools of a Model Context Protocol server running as its own service: discovered at run time, called over the network, with server errors the model can correct.
Code mode	Let the model write Python that calls your tools in a sandbox (Monty): many tool calls and exact arithmetic in one or two model requests, with hard limits on what the code can do.
Temporal	Run an agent as a durable Temporal workflow: failing tools are retried and a crashed worker is replaced, without repeating the model calls that already finished.
Conversation	Remember earlier turns with message history, bound the context window by turns, and stream replies as they are generated.
Human in the loop	Pause a risky tool call until a person approves it; reject impossible requests before anyone is asked; resume the same run.
Guardrails	Check input in code and with a small guard model, validate output, and turn provider filters and budget limits into safe answers.
Supervisor / workers	A supervisor decides which specialized workers to call, and in what order, then synthesizes their results.
Planner-executor	A planner writes the whole plan as data, code checks it and runs it (independent steps in parallel, each executor seeing only what it needs), and a last agent writes the answer.
Router	A classifier picks a category and plain code dispatches to a specialist agent; routing is a lookup, not an LLM loop.
Pipeline	Fixed sequential steps in code, each agent's typed output feeding the next, with gates between them.
Fan-out / fan-in	Run workers in parallel with asyncio.gather, tolerate a failed worker, then aggregate their findings.
Evaluator–optimizer	A generator drafts and a critic reviews against criteria; they loop until it passes or a round cap is hit.

Every one returns a RunResult: the output, the total usage, and one step per agent run.