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 exactAgentBuilderSessionStatus values returned by the session status endpoint. 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 asessionId. 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
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.