# Templates and Examples

`examples/agents/` ships pattern templates as agent directories (`hello-agent`, `minimal-agent`, `full-agent`, `proxy-agent`). Each directory holds a `spec.yaml` (plus an optional `to_home/` sibling) and demonstrates one deployment pattern with the smallest manifest that exercises it. Copy-and-adapt is the intended workflow.

The shipped YAML must round-trip through `load_config` cleanly so YAML-key drift fails loudly in CI rather than at a user’s first `sac agents start`.

## Pattern Templates

Template | Pattern | When to use
--- | --- | ---
`minimal-agent` | Smallest valid `spec.yaml` | Starting point. The fewest fields that load and start.
`hello-agent` | claude-session inside an Apptainer SIF | Default. F-CS17 made sac container-only; this is the canonical single-turn pattern.
`full-agent` | Fully-featured agent | Health, restart, A2A, and `to_home/` wiring all enabled.
`proxy-agent` | `kind: AgentProxy` | HTTP forwarder with no SDK runner — routes `/v1/turn` to another agent.

MCP tool wiring is no longer a separate template — drop a `.mcp.json` into the agent’s `to_home/` directory and it lands at `$HOME/.mcp.json` at start (ADR-0006).

## Instantiating a Template

The v3 loader uses `dir-as-SSoT` — the agent name is derived from the parent directory of the YAML, not from a `metadata.name` field. To instantiate:

    cp -r examples/agents/hello-agent \\
       ~/.scitex/agent-container/agents/my-agent
    # The to_home/ sibling (CLAUDE.md / .mcp.json / .env / state.md /
    # .claude/{commands,skills,hooks}/) is all optional.
    sac agents start my-agent