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

# Sessions

> The Agent Builder session lifecycle, in detail.

A **session** is the lifecycle of the Agent Builder. While the session is running, Agent Builder plans the navigation, browses the target site, extracts sample records, and saves the Agent when the build completes.

<Note>
  Agent Builder is currently **single-shot**. If the result is not right, start a new session with a clearer prompt or use the Editor to manually fine-tune the agent.
</Note>

## Lifecycle

Most sessions move through three phases:

<CardGroup cols={3}>
  <Card title="Building" icon="wand-magic-sparkles">
    Agent Builder is loading the site, planning steps, extracting records, and testing the result.
  </Card>

  <Card title="Ready" icon="clock">
    A draft Agent exists, but the session may still be finalizing.
  </Card>

  <Card title="Run" icon="circle-play">
    When the build completes, run, schedule, or edit the Agent.
  </Card>
</CardGroup>

## Statuses

These are the exact `AgentBuilderSessionStatus` values returned by the [session status endpoint](/api-reference/agent-builder/session-status). They are serialized as lowercase strings on the wire.

| Status       | Meaning                                                                      |
| ------------ | ---------------------------------------------------------------------------- |
| `processing` | Build is still running. Keep waiting.                                        |
| `ready`      | A draft Agent exists. Wait for `completed` before treating it as finished.   |
| `completed`  | Build finished and the response includes `agentId` and `agentName`.          |
| `error`      | Build failed. Start a new session with a clearer prompt or a simpler target. |
| `cancelled`  | The session was stopped before it completed.                                 |

## Polling

When you start a session from the API, the response gives you a `sessionId`. Poll the session until it reaches `completed`, then use `agentId` to run the Agent. Treat `error` and `cancelled` as finished states that do not produce a runnable Agent.

## Stopping a build

Stop a session when the build was started by mistake, the prompt is clearly wrong, or the caller no longer needs the Agent. Stopping a session does not delete existing Agents; it only interrupts the in-progress build.

## Related API references

<CardGroup cols={3}>
  <Card title="Start a session" icon="play" href="/api-reference/agent-builder/start-session">
    Send a prompt and receive a `sessionId`.
  </Card>

  <Card title="Get session status" icon="clock" href="/api-reference/agent-builder/session-status">
    Poll until the session finishes.
  </Card>

  <Card title="Stop a session" icon="square" href="/api-reference/agent-builder/session-stop">
    Cancel a build that is still in progress.
  </Card>
</CardGroup>