Agents

Create, validate, import, export, publish, and execute agents.

📄️List agents

Returns the agents visible to the caller, filtered by `type` (default `CUSTOM`). With `applicationId` it returns the agents of that application, without it only company-scoped agents (agents that belong to no application) are returned. Disabled agents are excluded unless `includeDisabled=true`.

📄️Chat with the AI agent builder

Streams an AI-SDK UI-message response. Body: `{ messages?, assistantContext: { applicationId, ... }, data? }`.

📄️Import an agent bundle

Imports an exported agent bundle (root agent plus sub-agents) into an application. The body is NOT a bare AgentSpec: to import a spec you authored, wrap it as `{ 'exportVersion': 1, 'agent': { 'name': '<name>', 'spec': <AgentSpec> } }`. Accepts `application/json` or `multipart/form-data` with a `file` field. `applicationId` comes from the payload or the query string.

📄️Check whether agents of an import bundle already exist

Inspects an export bundle and reports whether the root agent and its sub-agents already exist in the target application. Accepts `application/json` or `multipart/form-data` with a `file` field. `applicationId` comes from the payload or the query string.

📄️Get the AgentSpec V2 JSON Schema

Returns the JSON Schema (draft 2020-12) of the agent spec, derived from the canonical zod definition. Served as `application/schema+json` with a public cache policy.

📄️Validate an agent spec

Validates an agent spec against the AgentSpec V2 JSON Schema (see `GET /api/v1/agents/schema/`) without persisting anything. Accepts either `{ 'spec': <agent-spec> }` or the spec object at the top level.

📄️Get the AgentEvalSpec JSON Schema

Returns the JSON Schema (draft 2020-12) of the agent eval spec, derived from the canonical zod definition. Served as `application/schema+json` with a public cache policy.

📄️Get an agent

Returns one agent in the same item shape as the `GET /api/agents/` list.

📄️Export an agent bundle

Exports the agent (and, recursively, its sub-agents) as a portable bundle with inline evaluation criteria, evals and routines. Served as a JSON file download (`Content-Disposition: attachment`).

📄️Publish the latest saved agent spec

Promotes the most recently saved spec artifact to be the published version. Accepts an optional JSON body `{ name?, description? }` with version metadata. Idempotent: republishing the already-live version answers `alreadyPublished: true`.

📄️Update agent thread metadata

Updates `specThreadId` and/or `sandboxThreadId` in the agent metadata. Fields set to `null` are cleared; omitted fields are left untouched.

📄️Run an agent in sandbox mode

Streams an AI-SDK UI-message response of a sandbox agent run, including node lifecycle events and trace data. Body: `{ messages?, assistantContext: { applicationId, ... }, data? }`.

📄️Execute a published agent asynchronously

Validates the request, schedules a background run of the published agent version and returns immediately. Body: `{ prompt: string, threadId?: string, context?: object }`. Supports the `Idempotency-Key` header: a retry with the same key and body replays the stored ack instead of running the agent a second time.

📄️List sandbox threads of an agent

Without `threadGroupId` the agent sandbox group (`agent-sandbox:{agentId}`) is listed with type AGENT_SANDBOX. Passing `threadGroupId` lists that group instead, optionally narrowed by `type`. `q` filters threads by the display text of their first user message.

📄️List messages of an agent sandbox thread

Without `threadGroupId` the thread is looked up in the agent sandbox group (`agent-sandbox:{agentId}`) with type AGENT_SANDBOX; pass `threadGroupId` (and optionally `type`) to fetch builder or other thread groups.

📄️Cancel a scheduled follow-up of an agent

Deletes the follow-up scheduler job so it never fires and marks the source execution node as cancelled. Idempotent: cancelling a follow-up whose job is already gone still succeeds. To trigger the follow-up instead, use `POST /api/v1/agents/{agentId}/follow-ups/{followUpId}/fire-now/`.

📄️Fire a scheduled follow-up of an agent immediately

Runs the follow-up scheduler job now instead of waiting for its scheduled time. The schedule itself is not modified, but the later scheduled tick is absorbed by the worker because the manual run has already produced an assistant message. To stop the follow-up instead, use `POST /api/v1/agents/{agentId}/follow-ups/{followUpId}/cancel/`.