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
id
Headers
x-runtype-concurrency
How a durable turn handles overlap. `reject` (default) answers CONVERSATION_BUSY; `supersede` cancels and replaces; `queue` runs afterward; `join` durably appends new user-message deltas to the same execution at a safe boundary, or starts the next execution if completion wins. Join requires a conversationId, preserves configuration and authority, cannot combine with coalesce, and rejects unsupported lanes. Other policies remain ignored on in-process execution.
Allowed values:
x-runtype-coalesce
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-key
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)
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
Errors
400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
500
Internal Server Error
503
Service Unavailable Error