Skip to main content
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.
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.

​
Lifecycle

Most sessions move through three phases:

Building

Agent Builder is loading the site, planning steps, extracting records, and testing the result.

Ready

A draft Agent exists, but the session may still be finalizing.

Run

When the build completes, run, schedule, or edit the Agent.

​
Statuses

These are the exact AgentBuilderSessionStatus values returned by the session status endpoint. They are serialized as lowercase strings on the wire.

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

Start a session

Send a prompt and receive a sessionId.

Get session status

Poll until the session finishes.

Stop a session

Cancel a build that is still in progress.