> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent lifecycle

> How an agent goes from creation to deployment, execution, scheduling, and termination.

An agent is a saved, versioned configuration — a goal, instructions, a model, and a set of tools, skills, and delegates — that runs on a knowledge base. This page walks the full lifecycle so you can design integrations that create agents, run them interactively or on a schedule, and handle every terminal state predictably.

## Lifecycle at a glance

<Steps>
  <Step title="Create">
    `POST /agents` validates the configuration and creates **version 1**.
  </Step>

  <Step title="Configure & deploy">
    `POST /agents/:id/deploy` publishes changes and **increments the version**.
  </Step>

  <Step title="Run">
    `POST /agents/:id/messages` (or `/messages/stream`) starts a run and an associated chat.
  </Step>

  <Step title="Schedule">
    Attach a cron schedule so the agent runs headless on a recurring basis.
  </Step>

  <Step title="Stop">
    `POST /agents/:id/runs/:runId/stop` ends an in-flight run; every run resolves to a terminal state.
  </Step>
</Steps>

## Create

`POST /agents` creates an agent and its first version. On creation the platform validates the whole configuration up front so a run never starts against an invalid setup:

* The **knowledge base** exists and is accessible with your key.
* The **model** is a supported, available model.
* Any **connected apps** the agent references are authenticated and ready to call.
* The **schedule** (if provided) is a valid cron expression.
* Any **delegates** (other agents this one can hand off to) resolve.

A successful call returns the agent `id` and `agentVersion: 1`.

<Info>
  The knowledge base is **fixed at creation** and defines the agent's private retrieval corpus for its whole lifetime. To point an agent at different content, create a new agent on that knowledge base. See [Agents overview](/agents/overview).
</Info>

## Configure & deploy

Editing an agent's goal, instructions, model, or tool set and calling `POST /agents/:id/deploy` publishes a **new version**. Versioning is what makes agents safe to iterate on: each deploy is an immutable, numbered snapshot, and in-flight runs are unaffected by a deploy that lands mid-run.

<Tip>
  Deploy is also how you promote configuration between iterations. Because the knowledge base is set at creation, deploys change *behavior* (instructions, model, tools) rather than *content* — treat the two concerns separately in your release flow.
</Tip>

## Run

A run is a single execution of the agent. Start one with `POST /agents/:id/messages` for a complete response, or `POST /agents/:id/messages/stream` for live progress and final content over SSE (see [Chat lifecycle](/developers/lifecycles/chat-lifecycle) for the event model). Starting a run creates both a **run** record and an associated **chat**.

### Reproducibility

Each run **pins a snapshot** of the agent's goal, instructions, model, and tools at the moment it starts. This makes the run attributable to a stable core configuration even if you deploy a new version while it is still going; model output itself can still vary.

Two elements resolve to their **latest** definition at run time rather than being pinned:

* **Skills** — reusable capabilities resolve to their current version when the run begins.
* **Delegates** — the target agents of any handoff resolve at call time.

This keeps shared capabilities current across every agent that uses them while the core configuration stays frozen for the run.

### Continuing a run

To add turns to an existing run, pass its `chat_id` on your next message. New turns attach to the same run and chat, preserving the conversation and its pinned snapshot.

<Note>
  A single agent supports **single-hop delegation** — an agent can delegate to another agent to complete part of a task, and that delegate returns its result to the caller.
</Note>

## Schedule & scheduled execution

Attach a cron schedule to run an agent headless on a recurring basis. The scheduler owns the trigger, so you can **enable or disable a schedule without redeploying** the agent.

When a scheduled run fires, it executes with these guarantees:

<CardGroup cols={2}>
  <Card title="Bound identity" icon="id-badge">
    The run executes under a fixed, bound identity so access and attribution are consistent on every trigger.
  </Card>

  <Card title="Credit pre-check" icon="coins">
    Available credits are checked before work begins, so a run only starts with a positive balance.
  </Card>

  <Card title="Idempotent triggers" icon="rotate">
    Each scheduled occurrence runs once. Retries reuse the same occurrence, so a retry never double-runs.
  </Card>

  <Card title="Headless" icon="robot">
    No client connection is required — results are persisted to the run and its chat for you to read later.
  </Card>
</CardGroup>

See [Scheduling agents](/agents/scheduling) for cron syntax and enable/disable controls.

## Stop & terminal states

Stop an in-flight run with `POST /agents/:id/runs/:runId/stop`. Every run resolves to exactly one terminal state.

```
                ┌──────────────► completed   (final answer produced)
                │
running ────────┼──────────────► failed      (ended before a final answer;
                │                              partial output is preserved)
                │
                └──────────────► cancelled    (stopped via the stop endpoint)
```

<AccordionGroup>
  <Accordion title="completed" icon="circle-check">
    The run produced a final answer and finished normally.
  </Accordion>

  <Accordion title="failed" icon="circle-exclamation">
    The run ended before producing a final answer. Any work completed up to that point — intermediate output, sources, and usage — is **preserved on the run**, so you can inspect what was produced. Best practice: treat `failed` as "no final answer yet" and read the partial output before deciding whether to start a fresh run.
  </Accordion>

  <Accordion title="cancelled" icon="ban">
    The run was stopped explicitly through the stop endpoint.
  </Accordion>
</AccordionGroup>

## Endpoint summary

| Action                   | Method & path                              |
| ------------------------ | ------------------------------------------ |
| Create agent (version 1) | `POST /agents`                             |
| Deploy (new version)     | `POST /agents/:id/deploy`                  |
| Run (complete response)  | `POST /agents/:id/messages`                |
| Run (streamed response)  | `POST /agents/:id/messages/stream`         |
| Continue a run           | `POST /agents/:id/messages` with `chat_id` |
| Stop a run               | `POST /agents/:id/runs/:runId/stop`        |

## Next steps

<CardGroup cols={2}>
  <Card title="Agents overview" icon="robot" href="/agents/overview">
    How agents fit into knowledge bases and the platform.
  </Card>

  <Card title="Agents API" icon="code" href="/developers/api/agents">
    Full request and response schemas for every agent endpoint.
  </Card>

  <Card title="Delegation" icon="share-nodes" href="/agents/delegation">
    Compose agents with single-hop handoffs.
  </Card>

  <Card title="Chat lifecycle" icon="comments" href="/developers/lifecycles/chat-lifecycle">
    Understand the run's underlying conversation and streaming.
  </Card>
</CardGroup>