v0.3.0

Version 0.3.0 turns the template from "one agent plus three stubs" into a library of seventeen working
patterns that you add to your own project with one command, each run against a real model, with a
documentation site.

Upgrade notes

• The template no longer ships an agent. agent/agents/ is empty and there is no
  canonical run_agent / AgentOutput / AgentDeps / agent re-export. Run
  uv run python scripts/add_agent.py (once per agent) and import each agent from its own
  module, e.g. from agent.agents.triage import .... Code importing the canonical names from
  agent.agents must change.
• scripts/choose_pattern.py is gone. add_agent.py replaces it and the old
  add_agent.py <name> scaffold: add_agent.py supervisor --name triage, or
  add_agent.py blank --name newsletter for what the old script produced. Existing clones are
  unaffected until you pull this change; if you already chose a pattern, your agent keeps
  working but agent/agents/__init__.py no longer needs the canonical import.
• evals/test_pass_fail.py, evals/test_llm_judge.py and evals/fixtures/example.json are
  removed. Each agent now gets evals/test_<name>.py and evals/fixtures/<name>.json from
  add_agent.py; the shared evaluators moved to evals/helpers.py. Copy your fixtures to the
  new file name.
• agent/prompts/system.txt is gone. Each agent has agent/prompts/<name>.txt.
• run_* helpers return a RunResult, not the bare output. Read .output for what you
  used to get back: result = await run_agent(...), then result.output. result.usage is the
  total usage and result.steps records each agent run (result.steps[0].result is the native
  Pydantic AI result). Applies to run_agent, run_tool_agent, run_supervisor and every new
  example's helper; agents you copy with add_agent.py get the same shape.
• The agent-web-ui skill's chat.py imports one agent module you point it at (see the
  skill's "Before you start"), instead of the canonical names.
• Python 3.13 is still the minimum, and 3.14 is now supported. Python 3.15 is not yet.
• Some examples read their own environment variables (an embedding model, the address of a service). They are
  optional, and only matter if you add that example; see "Configuration" in the README and .env.example.

Added

• Seventeen example patterns in examples/, each with its source, prompt, README, offline and live tests, and a
  recorded run against a real model:
  • Basics: blank, single, conversation (message history, a bounded window, streaming).
  • Tools and data: tool_calling, extraction (an output validator and a retry budget), rag (documents embedded
    and searched by meaning in Chroma, with citations checked against what was retrieved), mcp_tools (the tools of
    an MCP server running as a Docker service) and code_mode (the model writes Python that calls your tools, in a
    sandbox).
  • Several agents: supervisor, planner_executor (a plan written as data, checked and run by code), router,
    pipeline, fan_out and evaluator_optimizer.
  • Safety and reliability: human_in_the_loop (pause a risky action for approval), guardrails (checks on input and
    output, failures turned into safe answers) and temporal (a durable workflow: failing tools are retried, a dead
    worker is replaced).
• scripts/add_agent.py, the one way to add an agent: an interactive menu, or add_agent.py <example> --name <name>.
  It copies the example and its prompt, scaffolds a smoke test and an eval starter, installs the example's extra
  packages, copies its service (if it has one) to services/<name>/, and tells you which environment variables to set.
  --prune removes the examples you did not use, and the docs and release tooling with them.
• RunResult and Flow (agent/runs.py): every run_* helper returns the output, the total usage and one step per
  agent run, whatever the pattern, so a call site does not change when an agent grows from one step to several.
• A documentation site at https://tmtabor.io/agent-template/, generated from the README, the examples and the other
  documents, so nothing is written twice. Each pattern has a page with an explanation, when to use it and when not to,
  its source, and its recorded run. Two guides: "Which pattern should I use?" and an FAQ.
• CONTRIBUTING.md, MAINTAINING.md and SECURITY.md (private vulnerability reporting is on), a logo, and a coverage
  badge in the README. --prune removes them, since they are about the template and not your project.
• Python 3.14 support: pyproject.toml lists it, CI runs lint and the offline suite on 3.13 and 3.14, and
  tests/test_python_versions.py keeps the README badge, the classifiers and the CI matrix in agreement.
• A release check (scripts/release_check.py) for maintainers: the offline suite, then each example against a real
  model in its own environment (its live tests, a smoke run, its Docker service started and stopped for it), a gate that
  every line of every example's code ran, and the recorded runs. It is manual and local, and is not part of CI.
• Examples can need more than the template. example.toml declares extra dependencies (installed only when you add
  that example), test_dependencies, services (a docker-compose.yml the release check starts), smoke-test
  overrides, expected_tools and a cost_budget_usd.
• Smaller additions: agent_label(__name__) labels each agent's traces with its own name (triage, triage.worker);
  evals/trace.py reports every agent and tool call a run made, from its spans; evals/helpers.py holds the shared
  evaluators and runner; Flow.run can resume a run with no new prompt (message_history=, deferred_tool_results=);
  load_prompt searches PROMPTS_DIRS so examples run in place.

Changed

• A new README and documentation home. They open with a logo, the line "Pick a pattern, edit the prompt, ship it.",
  badges and a pitch, then a three-step "Get started", the use cases, the four opinions baked in, and next steps. The
  maintainer sections moved to MAINTAINING.md.
• tool_calling and supervisor now do real work. Their placeholder tool and worker were replaced (a real model
  looped on the old echoing tool until it hit the request limit): tool_calling looks up Python release notes with a
  tool that shows all three error outcomes, and supervisor coordinates a real analyst and writer.
• The three pattern stubs moved from agent/agents/ to examples/ and are copied into your project on demand.
• The unit-test safety net also covers examples/ and agents held in module-level dicts, lists and tuples, and
  tests/test_safety_net.py no longer depends on a chosen agent.
• The GitHub Actions in .github/workflows/ are on their current major versions (Node 24).

Fixed

• The offline test suite is hermetic. A root conftest.py forces AGENT_MODEL=test unless the command line selects the
  live tests (-m eval), so uv run pytest passes with no provider key whatever .env configures. Before, it crashed on
  import if .env named a provider whose key was missing.

Removed

• scripts/choose_pattern.py, the canonical re-export in agent/agents/__init__.py, and tests/test_stubs.py (replaced by
  tests/test_examples.py).

Full changelog: v0.2.0...v0.3.0