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

1

Create

POST /agents validates the configuration and creates version 1.
2

Configure & deploy

POST /agents/:id/deploy publishes changes and increments the version.
3

Run

POST /agents/:id/messages (or /messages/stream) starts a run and an associated chat.
4

Schedule

Attach a cron schedule so the agent runs headless on a recurring basis.
5

Stop

POST /agents/:id/runs/:runId/stop ends an in-flight run; every run resolves to a terminal state.

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

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

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

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

Bound identity

The run executes under a fixed, bound identity so access and attribution are consistent on every trigger.

Credit pre-check

Available credits are checked before work begins, so a run only starts with a positive balance.

Idempotent triggers

Each scheduled occurrence runs once. Retries reuse the same occurrence, so a retry never double-runs.

Headless

No client connection is required — results are persisted to the run and its chat for you to read later.
See Scheduling agents 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)
The run produced a final answer and finished normally.
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.
The run was stopped explicitly through the stop endpoint.

​
Endpoint summary

ActionMethod & 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 runPOST /agents/:id/messages with chat_id
Stop a runPOST /agents/:id/runs/:runId/stop

​
Next steps

Agents overview

How agents fit into knowledge bases and the platform.

Agents API

Full request and response schemas for every agent endpoint.

Delegation

Compose agents with single-hop handoffs.

Chat lifecycle

Understand the run’s underlying conversation and streaming.