The agent lifecycle

An agent moves through the same seven stages every time: you create a project, develop it locally, give it capabilities, publish it as a blueprint, deploy the blueprint, operate the deployment, and watch what it does. This page is the map. Each stage links to the page that covers it in full.

1. Create a project

A project is a local codebase with an astropods.yml spec at its root. The spec is the single declaration of what your agent is: its container image, its models, its knowledge stores, its interfaces, and its ingestion jobs.

ast project create my-agent --model gateway

The --model gateway flag wires the agent to the AI Gateway, so you get managed model access without holding a provider key. Pick --template mastra or --template langchain to choose the framework harness.

2. Develop locally

ast project start runs your agent and its sidecars in containers, exactly as they run in production. The messaging sidecar comes up alongside the agent, so the local chat at http://localhost:3100 drives the same code path a deployed agent uses.

ast project configure   # set credentials and variables
ast project start       # run it, tail the agent log

Variables you set with ast project configure are stored locally and reloaded on every start, so you configure once rather than per run. See ast project for the full command set.

3. Add capabilities

Everything an agent can do beyond answering from the model is declared in the spec and injected as environment variables at deploy. The four you reach for most:

Beyond those, an agent can serve its own web UI, store data in SQLite, or reach an OAuth-protected MCP server.

4. Publish a blueprint

A blueprint is a versioned snapshot of the project in the Astropods registry. Publishing builds the container image and pushes it with the spec.

ast spec validate       # exit code 0 means the spec is well-formed
ast blueprint push my-agent --visibility private

Validate before you push. ast spec validate checks YAML syntax, schema conformance, and semantic rules, and returns 0 on success, so it drops straight into CI.

An AGENT.md agent card controls how the blueprint appears in the catalog. See Your first blueprint for the full walkthrough.

5. Deploy

Deploying turns a blueprint into a live agent with its own URL. One blueprint can back many deployments, which is how staging and production stay on the same image.

ast blueprint deploy my-agent \
  --var OPENAI_API_KEY=@OPENAI_KEY \
  --adapter web \
  --wait

KEY=@SECRET_NAME resolves the value from the account vault instead of putting it on the command line. --wait blocks until the public URL is ready. See Deploy your first agent and ast blueprint.

6. Operate

Once an agent is live, you inspect and control it without touching the blueprint:

Managing your agents covers the same operations from the web console. When a deploy never goes live, Troubleshooting stuck deployments walks the recovery path. Spend and quota live under Usage and Usage limits.

7. Observe

A deployed agent emits OpenTelemetry traces covering token usage, tool calls, and latency. Framework integrations instrument this for you: AI SDK, Mastra, and the Claude Agent SDK.

Traces connect back to the conversation through trace context, so a thumbs-down on a reply resolves to the exact turn that produced it. Tools running outside the platform, like Claude Code, report into the same dashboard.

Next steps

• Install the CLI: the prerequisite for every stage above
• Your first project: walk stages 1 and 2 end to end
• Astropods Spec: the full reference for what a spec can declare