# Chapter and command reference

This reference lists the current repository surfaces that future users and developers are most likely to run or extend.

## Repository structure

| Path | Purpose |
|------|---------|
| `.env.example` | Template for model provider keys and model overrides |
| `requirements.txt` | Shared dependency list, not complete for every optional online example |
| `shared/config.py` | Loads `.env` and exposes provider keys and default model names |
| `shared/skills.py` | Reusable skill and tool registry implementation |
| `shared/declarative_skills/` | Markdown declarative skill library |
| `ch01_*` through `ch21_*` | Chapter examples |
| `ch19_deployment/docker-compose.yml` | Compose sketch for API, worker, Redis, PostgreSQL, and Prometheus |

## Environment variables

| Variable | Default | Required by |
|----------|---------|-------------|
| `OPENAI_API_KEY` | empty | OpenAI examples using `require_key("openai")` |
| `GOOGLE_API_KEY` | empty | Gemini examples and Google provider demos |
| `ANTHROPIC_API_KEY` | empty | Claude examples, evaluation, guardrails, capstone, managed agents |
| `OPENAI_MODEL` | `gpt-4o` | Shared OpenAI examples |
| `GEMINI_MODEL` | `gemini-2.5-flash` | Shared Gemini examples |
| `ANTHROPIC_MODEL` | `claude-sonnet-4-20250514` | Shared Anthropic examples |
| `OLLAMA_MODEL` | `llama3:8b` | Ollama examples |
| `LITELLM_MODEL` | `openai/{OPENAI_MODEL}` | LiteLLM examples |

`shared/config.py` raises an `EnvironmentError` when `require_key()` is called for a missing provider key.

## Main runnable examples

Run these commands from the repository root unless a file docstring says otherwise.

| Command | Purpose | Primary requirements |
|---------|---------|----------------------|
| `python ch01_react_from_scratch\atlas_v01.py "What is MCP?"` | Run the raw OpenAI ReAct research agent | `OPENAI_API_KEY` |
| `python ch02_prompt_architecture\prompt_ab_test.py` | Run prompt variant evaluations | `OPENAI_API_KEY` |
| `python ch03_tools_and_skills\atlas_v03.py "Research LangGraph"` | Run modular skill-backed Atlas | `OPENAI_API_KEY` |
| `python ch04_handoffs\triage.py "I need a refund"` | Run support triage handoffs | `OPENAI_API_KEY`, `openai-agents` |
| `python ch05_state_graphs\code_review_agent.py` | Run LangGraph code review flow | `OPENAI_API_KEY`, LangGraph, LangChain OpenAI |
| `python ch06_multi_agent\newsletter_crew.py` | Run CrewAI newsletter workflow | CrewAI and provider config |
| `python ch07_model_portability\benchmark.py` | Benchmark configured providers | At least one provider key |
| `python ch08_mcp_a2a\mcp_knowledge_server.py` | Start MCP knowledge server over stdio | `mcp` |
| `python ch11_memory\memory_agent.py "Remember that I prefer Python"` | Run memory-backed agent | `ANTHROPIC_API_KEY`, ChromaDB |
| `python ch12_sandboxes\data_analyst.py` | Run sandboxed data analyst example | `ANTHROPIC_API_KEY`, optional E2B |
| `python ch13_multimodal\multimodal_agent.py` | Run multimodal routing demo | `ANTHROPIC_API_KEY`, file inputs |
| `python ch14_guardrails\guardrailed_agent.py` | Run guardrailed agent demo | `ANTHROPIC_API_KEY` |
| `python ch15_agent_harness\harness.py` | Run path, command, and verification harness demo | `ruff` for lint verification |
| `python ch16_always_on_agents\always_on_agent.py --task-dir tasks --interval 10` | Poll a task directory | `ANTHROPIC_API_KEY` |
| `python ch17_managed_agents\managed_agents.py "Research agent sandboxes"` | Use managed Claude agent APIs | `ANTHROPIC_API_KEY`, `requests` |
| `python ch18_evaluation\eval_harness.py --no-judge` | Run evaluation cases without LLM judge | `ANTHROPIC_API_KEY` still used by `mock_agent` |
| `uvicorn ch19_deployment.api:app --host 0.0.0.0 --port 8000 --reload` | Start FastAPI service from repo root | FastAPI, Uvicorn, Anthropic |
| `python ch20_capstone\atlas_capstone.py --issue 42 --repo owner/name --dry-run` | Run capstone issue-to-PR flow without writing PR | `ANTHROPIC_API_KEY`, `gh`, LangGraph |

## CLI flags

| File | Flags |
|------|-------|
| `ch10_claude_code_antigravity/online/autonomy_benchmarker.py` | `--tasks`, `--model`, `--seed` |
| `ch10_claude_code_antigravity/online/spec_validator.py` | `--agents-md`, `--agent-url`, `--output` |
| `ch16_always_on_agents/always_on_agent.py` | `--task-dir`, `--interval` |
| `ch16_always_on_agents/online/heartbeat_monitor.py` | `--mode`, `--url`, `--port`, `--interval`, `--stale-after` |
| `ch17_managed_agents/managed_agents.py` | positional `task`, `--agent-id`, `--env-id`, `--quiet` |
| `ch17_managed_agents/online/bedrock_managed_agent.py` | positional `prompt`, `--setup`, `--agent-id`, `--session-id`, `--end-session` |
| `ch17_managed_agents/online/claude_managed_agent.py` | positional `task`, `--setup`, `--agent-id`, `--env-id`, `--list-sessions` |
| `ch17_managed_agents/online/gemini_managed_agent.py` | positional `prompt`, `--setup`, `--agent-name`, `--session-id`, `--dataset` |
| `ch18_evaluation/eval_harness.py` | `--category`, `--case`, `--no-judge` |
| `ch18_evaluation/online/trajectory_visualizer.py` | positional `file`, `--live`, `--model` |
| `ch19_deployment/online/cloud_run_deploy.py` | `--project`, `--region`, `--service`, `--image-name`, `--tag`, `--memory`, `--skip-build` |
| `ch19_deployment/online/litellm_proxy_server.py` | `--port`, `--test`, `--config` |
| `ch20_capstone/atlas_capstone.py` | `--issue`, `--repo`, `--dry-run` |
| `ch20_capstone/online/atlas_gitlab_adapter.py` | `--issue`, `--project`, `--dry-run` |
| `ch20_capstone/online/atlas_nightly_runner.py` | `--repo`, `--max-issues`, `--dry-run` |
| `ch20_capstone/online/atlas_with_a2a_security.py` | `--issue`, `--repo`, `--security-agent-url`, `--serve-security-agent`, `--port`, `--dry-run` |
| `ch21_future/online/enterprise_ceiling_calculator.py` | `--demo`, `--processes` |
| `ch21_future/online/reasoning_vs_react_benchmark.py` | `--tasks` |
| `ch21_future/online/scaffold_optimizer.py` | `--sessions`, `--demo` |

## API endpoints

### `ch19_deployment/api.py`

| Endpoint | Method | Request | Response |
|----------|--------|---------|----------|
| `/agent/run` | `POST` | `AgentRequest` with `message`, optional `session_id`, optional `webhook_url` | `AgentResponse` with `answer`, `tools_used`, `input_tokens`, `output_tokens` |
| `/agent/stream` | `POST` | `AgentRequest` | Server-sent events with `delta` messages and final `done` usage |
| `/agent/async` | `POST` | `AgentRequest` | `task_id` and `status` |
| `/agent/status/{task_id}` | `GET` | path `task_id` | task state and result if ready |
| `/health` | `GET` | none | `{"status": "ok", "version": "0.19"}` |

### A2A security agent

`ch20_capstone/online/atlas_with_a2a_security.py` exposes:

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/.well-known/agent.json` | `GET` | Agent card discovery |
| `/tasks` | `POST` | Submit code audit tasks |

## Verified checks

Current verification commands:

```powershell
python --version
```

Result:

```text
Python 3.13.5
```

Syntax check:

```powershell
python -m compileall -q .
```

Current result: passes.