Skip to navigation

Execute agent

Execute an agent with a message array. Streams a Server-Sent Events response when streamResponse is true (default); otherwise returns a JSON result. Send the RFC 7240 Prefer: respond-async header to receive a durable execution handle immediately, then poll its status URL for completion. The optional durability body field pins the lane for this request (forced: durable or in_process) or bounds its attached watch (watchLeaseMs), and outranks the saved agent config.

Authentication

AuthorizationBearer
API key or Clerk session token

Path parameters

idstringRequired

Headers

x-runtype-concurrencyenumOptional

How a durable turn handles overlap. reject (default) answers CONVERSATION_BUSY naming the occupant execution, its phase, and a Retry-After; supersede cancels and replaces; queue runs afterward; steer durably appends new user-message deltas to the same execution at a safe boundary, attaches through the host’s slot claim when the host has not started yet, or starts the next execution if completion wins. Steer requires a conversationId, preserves configuration and authority, cannot combine with coalesce, and rejects unsupported lanes. auto sends the same user-message deltas as steer and lets a classifier choose: while a turn runs, a message that belongs to it steers and an independent one queues as the next turn; with nothing running it is an ordinary turn with no route report. A routed or downgraded answer reports the route in X-Runtype-Busy-Message-Route / -Source (plus -Probability and -Model when the classifier answered) and, on JSON bodies, busyMessageRoute. Where auto cannot route (in-process execution, stored history, no conversationId, coalesce, Prefer: respond-async) it keeps the default admission and reports source disabled. Other policies remain ignored on in-process execution.

Allowed values:
x-runtype-coalesceenumOptional

Send true to fold this request into an already-pending turn for the same conversation instead of starting a second one. The response is the pending execution. Any other value (or omitting the header) starts a new turn.

Allowed values:
idempotency-keystringOptional

Caller-chosen key that makes admission idempotent: a retry with the same key returns the ORIGINAL execution rather than starting a second turn, and consumes no additional quota. Scoped to the durable lane.

Request

This endpoint expects a map from strings to any.

Response

Server-Sent Events stream of agent execution events (or a JSON result when streamResponse is false)

object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object
OR
object

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error