Agent Lifecycle

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:

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

Note

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.

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.