Agent anatomy

Every agent created by Cast lives at ~/.cast/agents/<name>/. The directory is both the agent’s source of truth and its working tree — when you edit an agent with edit and the Builder writes changes, those changes show up as files on disk.

~/.cast/agents/email-assistant/
├── agent.yaml             # the agent's config
├── instructions.md        # the agent's system prompt ("the brain")
├── tools/                 # custom Python tools
│   └── summarize_thread.py
├── mcp/                   # MCP server configs (one YAML per server)
│   └── gmail.yaml
├── tests/
│   ├── cli/               # TypeScript CLI tests
│   └── agent/             # Python agent tests
│       └── scenarios/
│           └── triage.yaml
├── .cast/                 # Cast-managed metadata (do not hand-edit)
│   ├── changes/           # automatic snapshots
│   │   ├── changes.json
│   │   ├── 001.tar.gz
│   │   └── 002.tar.gz
│   └── releases/          # semantic releases
│       ├── releases.json
│       ├── 1.0.tar.gz
│       └── 1.6.tar.gz
├── .git/                  # if cast git init was run
├── Dockerfile             # written by cast deploy --provider docker
├── requirements.txt       # written by cast deploy
└── README.md              # written by cast git init

The files you own

• agent.yaml — the agent’s configuration. Edit it with update or by hand; Cast will re-read it on the next change/release.
• instructions.md — the system prompt the runtime sends to the LLM. This is where the agent’s “personality” and capabilities live.
• tools/ — drop in .py files that define new LangChain tools. Cast picks them up automatically; no registration step.
• mcp/ — one YAML file per MCP server. The Builder Agent scaffolds these during cast new/cast edit.
• tests/ — TypeScript tests for the CLI integration and Python tests for agent behaviour. cast meta test runs the meta-builder against these.

The files Cast owns

• .cast/changes/ — the internal change log (undo log). You don’t touch this directly. The changes.json manifest is the source of truth for “v3 was created at because ”. Cast consumes it through cast undo / cast redo and through cast release’s auto-changelog generator. See Undo and redo.
• .cast/releases/ — the intentional release log. Same idea but for semantic versions; cast release writes here. See Releases.
• Dockerfile, requirements.txt, docker-compose.yml — generated on each cast deploy (or cast upgrade) and overwritten on the next deploy. Do not hand-edit.
• .git/ — present if you ran cast git init. cast git commit and cast git push operate on it.

What agent.yaml controls

Use cast describe <name> to see the full rendered file with defaults filled in. Use cast update <name> --<flag> ... to mutate it from the CLI without opening a text editor.