Getting started

Setup and commands

# Install dependencies
uv sync --group dev

# After uv sync, install Claude Code skills for pydantic-ai and logfire
uvx library-skills install --all --claude

# Copy and configure environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Add an agent: pick a pattern from the menu (or name one, e.g.
# `add_agent.py supervisor --name triage`); see "Agents" below
uv run python scripts/add_agent.py

# Run unit tests (no API calls, no API key needed)
uv run pytest

# Run evals — requires a real API key, see Evals below
uv run pytest -m eval

# Lint
uv run ruff check .

# Format
uv run ruff format .

Project structure

agent/
├── config.py          # Settings — validates the AGENT_MODEL provider at import time (raises if misconfigured)
├── logging.py          # Logfire setup — configure_logging(), get_logger()
├── agents/             # YOUR agents, one module each — empty until you run add_agent.py
├── tools/example.py    # Canonical tool pattern — copy and adapt
└── prompts/
    ├── <name>.txt       # One prompt per agent, written by add_agent.py
    └── templates.py      # load_prompt() loader

examples/               # The pattern library: blank, single, supervisor, tool_calling, … (see its README)
└── <pattern>/           #   agent.py, prompts/, example.toml, README.md, sample_run.md, tests
scripts/add_agent.py     # Add an agent from an example pattern — see "Agents" below
tests/    # Unit tests against TestModel — no API calls, no API key needed
evals/    # Per-agent eval starters + shared helpers — real API calls, run with -m eval
docs/ + mkdocs.yml          # The documentation site, generated from this README and examples/
.github/workflows/ci.yml    # CI: ruff check, format check, unit tests (no secrets needed)
.github/workflows/docs.yml  # Builds the docs site and publishes it to GitHub Pages