# AGENTS.md: CrewAI project

## Commands
- `crewai install` (uv-based) · `crewai run` · `crewai test -n 3` · `uv run pytest -q`
- CrewAI releases often; check `pyproject.toml` for the pinned version and its docs before using new APIs.

## Structure (from `crewai create crew`)
- `src/<project>/config/agents.yaml`: role, goal, backstory per agent. `config/tasks.yaml`: description, expected_output, agent.
- `crew.py`: `@CrewBase` class with `@agent`, `@task`, `@crew` methods that load the YAML. `main.py`: inputs and kickoff.
- Custom tools in `tools/` subclassing `BaseTool` with a Pydantic `args_schema`.

## Rules
- Each agent has one clear responsibility; prefer 2-4 agents over many overlapping ones.
- Tasks state a concrete `expected_output` (format, length, fields). Use `output_pydantic` for structured results that code consumes.
- Use `Process.sequential` unless a manager really adds value; hierarchical runs cost more.
- Use Flows (`@start`, `@listen`, `@router`, typed state) for deterministic orchestration; put crews inside flow steps for the fuzzy parts.
- LLMs configured per agent via `LLM(model=...)` from config/env; set `max_iter` and `max_rpm` to cap loops and spend.
- Tools that write, send, or spend need explicit human input (`human_input=True` on the task) or an allowlist.
- Enable `memory`/knowledge only when needed; it adds embedding calls.

## Done
Tool unit tests pass; one `crewai test` run on sample inputs produces outputs matching `expected_output`. Report token usage from `crew.usage_metrics`.