---
title: Agent Lifecycle
description: Understanding agent states and transitions
---

import { Aside } from '@astrojs/starlight/components';

Every agent in Astromesh Cloud exists in one of three states. Understanding the lifecycle helps you manage deployments, make edits safely, and avoid downtime.

## State Machine

```
         POST /agents (create)
                  │
                  ▼
              [draft]
                  │
        POST .../deploy
                  │
                  ▼
           [deployed] ◄──────────────────┐
                  │                      │
       POST .../pause             POST .../deploy
                  │                      │
                  ▼                      │
            [paused] ────────────────────┘

         DELETE /agents/{'{name}'} works from any state
```

## States

### draft

The initial state when an agent is created with `POST /orgs/{'{slug}'}/agents`.

- The `WizardConfig` is stored but not compiled to runtime YAML
- The agent is not registered in the shared runtime
- No requests are accepted
- Config can be freely edited with `PUT /orgs/{'{slug}'}/agents/{'{name}'}`
- You can use `POST .../test` after deploying, but editing is only safe in draft state

**Use draft when:** You are iterating on the system prompt, model selection, tools, or guardrails and don't need the agent to accept live traffic.

---

### deployed

The active state. The `WizardConfig` has been compiled to an Astromesh runtime YAML and the agent is registered in the shared runtime under the ID `{'{org_slug}'}__{'{agent_name}'}`.

- The agent accepts requests via `POST .../run` and WebSocket `.../stream`
- Usage counts against the org's daily limit
- Config **cannot** be edited directly — you must pause first
- `POST .../test` runs queries that do not count against usage

**What happens during deploy:**

1. Cloud API validates the `WizardConfig`
2. Generates an Astromesh agent YAML with the org-namespaced agent ID
3. Injects the org's provider keys into the model router config
4. Calls `AgentRuntime.load_agent()` on the shared runtime
5. Returns `{ "status": "deployed", "agent_id": "org__name" }`

**Use deployed when:** The agent is ready for production or staging traffic.

---

### paused

The agent is deregistered from the runtime but the `WizardConfig` is fully preserved. No requests are accepted.

- Re-deploying from paused is faster than a fresh deploy (config already validated)
- Safe to edit the `WizardConfig` while paused
- `GET /orgs/{'{slug}'}/agents/{'{name}'}` still returns the agent with full config

**Use paused when:** You need to make config changes to a deployed agent, temporarily reduce runtime load, or take an agent offline for maintenance.

---

## Transitions Reference

| From | To | Endpoint | Effect |
|---|---|---|---|
| `draft` | `deployed` | `POST .../deploy` | Compile YAML, register in runtime |
| `deployed` | `paused` | `POST .../pause` | Deregister from runtime |
| `paused` | `deployed` | `POST .../deploy` | Re-register in runtime |
| any | deleted | `DELETE /agents/{'{name}'}` | Pause if needed, then remove config |

## Editing a Deployed Agent

You cannot edit an agent that is in `deployed` state. The correct workflow is:

```bash
# 1. Pause the agent
curl -X POST "https://api.astromesh.io/api/v1/orgs/$ORG/agents/my-bot/pause" \
  -H "Authorization: Bearer $TOKEN"

# 2. Update the config
curl -X PUT "https://api.astromesh.io/api/v1/orgs/$ORG/agents/my-bot" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"step2": {"system_prompt": "Updated prompt..."}}'

# 3. Redeploy
curl -X POST "https://api.astromesh.io/api/v1/orgs/$ORG/agents/my-bot/deploy" \
  -H "Authorization: Bearer $TOKEN"
```

<Aside>
  There is a brief period between pause and redeploy where the agent is unavailable. For zero-downtime updates, create a new agent with a different name, test it, then swap traffic.
</Aside>

## Test vs Deploy

Both `test` and `run` execute the agent through the full Astromesh pipeline (guardrails, memory, model router, tools). The difference is accounting:

| | `POST .../test` | `POST .../run` |
|---|---|---|
| Executes agent | Yes | Yes |
| Counts against daily limit | No | Yes |
| Requires deployed state | Yes | Yes |
| Included in usage stats | No | Yes |

Use `test` during development and QA. Use `run` (or the WebSocket stream) for production traffic.
