> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# 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.

| Stage            | Command                | Covered in                                |
| ---------------- | ---------------------- | ----------------------------------------- |
| Create           | `ast project create`   | [Your first project](/get-started)        |
| Develop          | `ast project start`    | [Your first project](/get-started)        |
| Add capabilities | Spec edits             | [Astropods Spec](/astropods-package-spec) |
| Publish          | `ast blueprint push`   | [Your first blueprint](/blueprints)       |
| Deploy           | `ast blueprint deploy` | [Deploy your first agent](/deploy-agent)  |
| Operate          | `ast agent …`          | [Managing your agents](/managing-agents)  |
| Observe          | Traces and feedback    | [Monitor your agents](/monitor-agents)    |

## 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.

```bash
ast project create my-agent --model gateway
```

The `--model gateway` flag wires the agent to the [AI Gateway](/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.

```bash
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`](/cli/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:

#### [Models](/ai-gateway)

Call managed models through an OpenAI-compatible API.

#### [Knowledge stores](/knowledge-stores)

Connect a database once and share it across agents.

#### [Secrets](/secrets)

Store credentials in the account vault, reference them at deploy.

#### [Messaging](/messaging-sdk)

Serve Slack, web chat, and other platforms over gRPC.

Beyond those, an agent can [serve its own web UI](/frontend-agents), [store data in SQLite](/agent-sqlite), or [reach an OAuth-protected MCP server](/mcp-oauth).

## 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.

```bash
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](/agent-card) controls how the blueprint appears in the catalog. See [Your first blueprint](/blueprints) 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.

```bash
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](/deploy-agent) and [`ast blueprint`](/cli/blueprint).

## 6. Operate

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

| Task                     | Command                                |
| ------------------------ | -------------------------------------- |
| See what's deployed      | `ast agent list`                       |
| Read logs                | `ast agent logs --name <name> --tail`  |
| Stop and restart traffic | `ast agent pause` / `ast agent resume` |
| Ship a new build         | `ast agent redeploy --name <name>`     |
| Tear it down             | `ast agent delete --name <name>`       |

[Managing your agents](/managing-agents) covers the same operations from the web console. When a deploy never goes live, [Troubleshooting stuck deployments](/troubleshooting-deployments) walks the recovery path. Spend and quota live under [Usage](/usage) and [Usage limits](/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](/monitor-ai-sdk), [Mastra](/monitor-mastra), and the [Claude Agent SDK](/monitor-claude-agent-sdk).

Traces connect back to the conversation through [trace context](/messaging-sdk/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](/monitor-claude-code), report into the same dashboard.

## Next steps

* [Install the CLI](/install-cli): the prerequisite for every stage above
* [Your first project](/get-started): walk stages 1 and 2 end to end
* [Astropods Spec](/astropods-package-spec): the full reference for what a spec can declare