agent2: Instructions file for Codex

Agent2

Agent2 turns domain experts into production AI agents. The goal is not to build deterministic scripts with a thin prompt on top. The goal is to clone how a professional works: their workspace, books, tools, memory, review process, judgment calls, clarification loops, and final typed work product.

Read llms.txt for the compact map and llms-full.txt for expanded framework context.

Build and test

uv sync --extra dev
uv run pytest tests/ -v

# Agent2 v0.3 CLI
uv run agent2 setup --dry-run
uv run agent2 onboard --from-spec tests/fixtures/roofing-agent-spec.json --no-llm --overwrite
uv run agent2 doctor --json

# Core stack
docker compose up -d

# Full stack with RAG, Knowledge MCP, OCR, and full-pattern examples
docker compose --profile full up -d

Agent2 mental model

• A domain agent is a professional at a desk, not a rules engine.
• The prompt teaches the expert's Sachbearbeiter Chain-of-Thought; books contain what the expert knows.
• Domain knowledge belongs in R2R knowledge collections, not hardcoded lookup tables or giant prompts.
• Every serious domain agent should have three mutually exclusive outcomes: complete/approved, needs_clarification, or rejected.
• Pydantic schemas are contracts. Use model_validator to prevent contradictory states such as approved plus rejection reason.
• Side effects are sandboxed. Agents propose pending_actions; hosts or humans execute them through the approval workflow.
• Multi-turn work resumes through message_history, not by reprocessing the case from scratch.

Runtime rules

• shared/ is framework code.
• Agent business logic lives in agents/<name>/.
• agent2.yaml is the global source of truth for default model, provider policy, stack profile, telemetry, and framework ports.
• Build agents with create_agent() from shared/runtime.py.
• Build apps with create_app() from shared/api.py.
• Use agent2 setup for local .env/agent2.yaml generation and agent2 onboard for Brain Clone agent scaffolding before hand-editing files.
• Use instructions=, not system_prompt=, for new code.
• system_prompt= exists only as a compatibility alias.
• Use toolsets=[] when no MCP tools are attached.
• Use before_run() for dynamic _instructions, request-scoped knowledge collections, resume hints, input guards, and per-run _toolsets.
• Per-run _toolsets from before_run() are supported by the API runtime and passed to Agent.run(toolsets=...); they are stripped from the user prompt.
• Model resolution order is explicit runtime argument, agent config.yaml, agent2.yaml, then env fallback.
• Errors must be RFC 7807 application/problem+json.