Build an agent end-to-end

A worked example: you go from “I want an agent” to “I’m chatting with the deployed version” in seven steps. Each step is one command and a link to the page that documents the depth.

1. Scaffold the agent

cast new

cast new launches the Builder wizard. Tell it what the agent should do, and it writes the scaffold to ~/.cast/agents/<name>/.

See Create an agent for the wizard reference and Agent anatomy for the resulting directory layout.

2. Refine it

cast edit <name>

cast edit re-opens the Builder against an existing agent. Adjust the model, instructions, tools, and permissions until the agent behaves the way you want.

See Edit an agent.

3. Test it in the TUI

cast dev <name>

cast dev boots the runtime locally and drops you into the TUI. Chat with the agent, try /mode to switch between PLAN and BUILD, and use /undo / /redo if it goes off the rails.

See TUI overview, TUI modes, and Slash commands.

4. Make a release

cast release <name> 1.0

cast release snapshots the current state into releases/1.0.tar.gz and updates agent.yaml’s version. The auto-generated changelog is your record of what changed since the last release.

See Releases.

5. Ship it

cast deploy <name> --version 1.0

cast deploy packages the release tarball into a container and pushes it to your provider. A unique deployment SHA is returned.

See Deployment overview.

6. Chat with the deployed agent

cast connect <name>

cast connect opens the TUI against the deployed A2A server. The header shows the deployed version (e.g. v1.0).

See Connect, shutdown, upgrade.

7. Iterate

cast edit <name>            # tweak
cast release <name> 1.1     # snapshot
cast upgrade <name> --version 1.1   # redeploy in place

Edit the agent locally, make a new release, and push it without losing any persistent memory — cast upgrade redeploys but keeps the same volume mount.

See Connect, shutdown, upgrade.

Where to go next

You now have the full loop. The reference pages you’ll come back to: