> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Execute agent

POST https://api.runtype.com/v1/agents/{id}/execute
Content-Type: application/json

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.

Reference: https://docs.runtype.com/api-reference/runtype-api/agents/execute-agent

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Path parameters

- `id` (string, required)

### Headers

- `x-runtype-concurrency` (enum, optional) — 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: `reject`, `supersede`, `queue`, `steer`, `auto`
- `x-runtype-coalesce` (enum, optional) — 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: `true`
- `idempotency-key` (string, optional) — 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.

### Body (application/json)

This endpoint expects a map from string to any.

- `map from string to any`

## Response

### 200

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

- Streaming response of `ExecutionStreamEvent`.
- ExecutionStreamEvent0
- ExecutionStreamEvent1
- ExecutionStreamEvent2
- ExecutionStreamEvent3
- ExecutionStreamEvent4
- ExecutionStreamEvent5
- ExecutionStreamEvent6
- ExecutionStreamEvent7
- ExecutionStreamEvent8
- ExecutionStreamEvent9
- ExecutionStreamEvent10
- ExecutionStreamEvent11
- ExecutionStreamEvent12
- ExecutionStreamEvent13
- ExecutionStreamEvent14
- ExecutionStreamEvent15
- ExecutionStreamEvent16
- ExecutionStreamEvent17
- ExecutionStreamEvent18
- ExecutionStreamEvent19
- ExecutionStreamEvent20
- ExecutionStreamEvent21
- ExecutionStreamEvent22
- ExecutionStreamEvent23
- ExecutionStreamEvent24
- ExecutionStreamEvent25
- ExecutionStreamEvent26
- ExecutionStreamEvent27
- ExecutionStreamEvent28
- ExecutionStreamEvent29
- ExecutionStreamEvent30
- ExecutionStreamEvent31
- ExecutionStreamEvent32
- ExecutionStreamEvent33
- ExecutionStreamEvent34
- ExecutionStreamEvent35
- ExecutionStreamEvent36
- ExecutionStreamEvent37

### 202

Durable fire-and-forget handle accepted via `Prefer: respond-async`. Poll statusUrl for completion. Carries a `Preference-Applied: respond-async` header.

- Streaming response of `AsyncDispatchHandle`.
- `executionId` (string, required) — The durable execution handle — poll with this.
- `status` (enum, required) — Host lifecycle at acceptance or idempotent delivery replay.
  - Allowed values: `queued`, `running`, `paused`, `completed`, `failed`, `cancelled`, `interrupted`
- `statusUrl` (string, required) — Relative URL for polling this execution.
- `targetKind` (enum, required) — Kind of execution target.
  - Allowed values: `flow`, `agent`
- `accepted` (boolean, optional)
- `busyMessageRoute` (BusyMessageRouteReport, optional)
- `claudeManagedAgentId` (string, optional) — Present only for ephemeral inline-create dispatch.
- `conversationId` (string, optional) — Conversation id, when the request belongs to a conversation.
- `deliveryId` (string, optional) — Stable input-delivery identity, distinct from the host execution.
- `deliveryStatus` (enum, optional)
  - Allowed values: `pending`, `applied`, `settled`, `not_applied`
- `deliveryStatusUrl` (string, optional) — Poll this receipt to distinguish pending, applied, settled, and not-applied input.
- `eventsUrl` (string, optional)
- `targetId` (string, optional) — Saved flow or agent id, when known.

## Errors

### 400 Bad Request Error

Invalid agent ID or request body, or an external agent that opts into identity assertion called with no identity to assert (IDENTITY_ASSERTION_UNAVAILABLE; the agent was not called)

- `ExecuteAgentRequestBadRequestError`
  - Error: Error
  - IdentityAssertionUnavailableError: IdentityAssertionUnavailableError

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 403 Forbidden Error

Insufficient permissions

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 404 Not Found Error

Agent not found, a version selector that names no pointer (alias_not_found, alias_archived, alias_expired, version_not_found), or a saved agent with no runnable live version (AGENT_NOT_DEPLOYED)

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 409 Conflict Error

Organization model configuration needs configuration, the durable conversation is busy (CONVERSATION_BUSY names the occupant execution and its phase; honor Retry-After or steer it with x-runtype-concurrency: steer), or a `history: "stored"` turn lost the compare-and-swap on its conversation (CONVERSATION_MODIFIED; nothing ran, re-read the conversation and retry)

- `ExecuteAgentRequestConflictError`
  - ExecuteAgentRequestConflictError0
  - ConversationBusyError: ConversationBusyError
  - ConversationModifiedError: ConversationModifiedError

### 413 Content Too Large Error

A `history: "stored"` turn could not be stored: the conversation is already at the record payload limit. Nothing ran.

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 500 Internal Server Error

Internal server error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 502 Bad Gateway Error

An external agent call failed upstream: rejected credentials, rate limited, an HTTP error, a network failure, or an invalid response

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 503 Service Unavailable Error

Asynchronous execution unavailable

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 504 Gateway Timeout Error

An external agent call timed out

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

## Types

### ExecutionStreamEvent0

- `executionId` (string, required)
- `kind` (enum, required)
  - Allowed values: `agent`, `flow`
- `seq` (double, required)
- `startedAt` (string, required)
- `type` (enum, required)
  - Allowed values: `execution_start`
- `agentId` (string, optional)
- `agentName` (string, optional)
- `config` (map from string to any, optional)
- `flowId` (string, optional)
- `flowName` (string, optional)
- `maxTurns` (double, optional)
- `resumed` (boolean, optional)
- `source` (string, optional)
- `totalSteps` (double, optional)

### ExecutionStreamEvent1

- `executionId` (string, required)
- `kind` (enum, required)
  - Allowed values: `agent`, `flow`
- `seq` (double, required)
- `success` (boolean, required)
- `type` (enum, required)
  - Allowed values: `execution_complete`
- `claudeManagedAgentId` (string, optional)
- `completedAt` (string, optional)
- `durationMs` (double, optional)
- `externalAgent` (ExecutionStreamEventOneOf1ExternalAgent, optional)
- `failedSteps` (double, optional)
- `finalOutput` (string, optional)
- `iterations` (double, optional)
- `outcome` (enum, optional) — How the execution ended: `completed`, `error`, or `aborted` (cancelled, interrupted, or superseded by the caller or host). Absent on frames from older producers: treat `execution_error` as `error` and `execution_complete` as `completed`, or `error` when `success` is false.
  - Allowed values: `completed`, `error`, `aborted`
- `stepErrorCount` (double, optional)
- `stopReason` (string, optional)
- `successfulSteps` (double, optional)
- `totalCost` (double, optional)
- `totalSteps` (double, optional)
- `totalTokens` (ExecutionStreamEventOneOf1TotalTokens, optional)
- `totalTokensUsed` (double, optional)

### ExecutionStreamEvent2

- `error` (ExecutionStreamEventOneOf2Error, required)
- `executionId` (string, required)
- `kind` (enum, required)
  - Allowed values: `agent`, `flow`
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `execution_error`
- `blockReason` (string, optional)
- `code` (string, optional)
- `completedAt` (string, optional)
- `finalOutput` (string, optional)
- `outcome` (enum, optional) — How the execution ended: `completed`, `error`, or `aborted` (cancelled, interrupted, or superseded by the caller or host). Absent on frames from older producers: treat `execution_error` as `error` and `execution_complete` as `completed`, or `error` when `success` is false.
  - Allowed values: `completed`, `error`, `aborted`
- `stopReason` (string, optional)
- `upgradeUrl` (string, optional)

### ExecutionStreamEvent3

- `executionId` (string, required)
- `id` (string, required)
- `role` (enum, required)
  - Allowed values: `user`, `assistant`, `system`
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `turn_start`
- `iteration` (double, optional)
- `subagent` (ExecutionStreamEventOneOf3Subagent, optional)
- `turnIndex` (double, optional)

### ExecutionStreamEvent4

- `executionId` (string, required)
- `id` (string, required)
- `role` (enum, required)
  - Allowed values: `user`, `assistant`, `system`
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `turn_complete`
- `attributes` (map from string to ExecutionStreamEventOneOf4Attributes, optional)
- `completedAt` (string, optional)
- `content` (string, optional)
- `cost` (double, optional)
- `estimatedContextBreakdown` (ExecutionStreamEventOneOf4EstimatedContextBreakdown, optional)
- `fallback` (ExecutionStreamEventOneOf4Fallback, optional)
- `iteration` (double, optional)
- `stopReason` (enum, optional)
  - Allowed values: `end_turn`, `max_tool_calls`, `length`, `content_filter`, `error`, `unknown`
- `subagent` (ExecutionStreamEventOneOf4Subagent, optional)
- `tokens` (ExecutionStreamEventOneOf4Tokens, optional)

### ExecutionStreamEvent5

- `executionId` (string, required)
- `id` (string, required)
- `ordinal` (integer, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `model_call_start`
- `iteration` (double, optional)
- `model` (string, optional)
- `provider` (string, optional)
- `startedAt` (string, optional)
- `stepId` (string, optional)
- `subagent` (ExecutionStreamEventOneOf5Subagent, optional)
- `turnId` (string, optional)

### ExecutionStreamEvent6

- `executionId` (string, required)
- `id` (string, required)
- `ordinal` (integer, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `model_call_complete`
- `attributes` (map from string to ExecutionStreamEventOneOf6Attributes, optional)
- `completedAt` (string, optional)
- `cost` (double, optional)
- `durationMs` (double, optional)
- `finishReason` (string, optional)
- `iteration` (double, optional)
- `model` (string, optional)
- `provider` (string, optional)
- `responseModel` (string, optional)
- `subagent` (ExecutionStreamEventOneOf6Subagent, optional)
- `success` (boolean, optional)
- `tokens` (ExecutionStreamEventOneOf6Tokens, optional)
- `turnId` (string, optional)

### ExecutionStreamEvent7

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `step_start`
- `index` (double, optional)
- `name` (string, optional)
- `outputVariable` (string, optional)
- `startedAt` (string, optional)
- `stepType` (string, optional)
- `subagent` (ExecutionStreamEventOneOf7Subagent, optional)
- `totalSteps` (double, optional)

### ExecutionStreamEvent8

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `step_complete`
- `completedAt` (string, optional)
- `cost` (double, optional)
- `durationMs` (double, optional)
- `error` (string, optional)
- `fallback` (ExecutionStreamEventOneOf8Fallback, optional)
- `name` (string, optional)
- `result` (any, optional)
- `stepType` (string, optional)
- `stopReason` (enum, optional)
  - Allowed values: `end_turn`, `max_tool_calls`, `length`, `content_filter`, `error`, `unknown`
- `subagent` (ExecutionStreamEventOneOf8Subagent, optional)
- `success` (boolean, optional)
- `tokensUsed` (double, optional)
- `unresolvedVariables` (list of string, optional)

### ExecutionStreamEvent9

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `step_skip`
- `index` (double, optional)
- `name` (string, optional)
- `skippedAt` (string, optional)
- `stepType` (string, optional)
- `totalSteps` (double, optional)
- `when` (string, optional)

### ExecutionStreamEvent10

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `text_start`
- `parentToolCallId` (string, optional)
- `role` (enum, optional)
  - Allowed values: `user`, `assistant`, `system`
- `stepId` (string, optional)
- `subagent` (ExecutionStreamEventOneOf10Subagent, optional)
- `turnId` (string, optional)

### ExecutionStreamEvent11

- `delta` (string, required)
- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `text_delta`
- `subagent` (ExecutionStreamEventOneOf11Subagent, optional)

### ExecutionStreamEvent12

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `text_complete`
- `subagent` (ExecutionStreamEventOneOf12Subagent, optional)
- `text` (string, optional)

### ExecutionStreamEvent13

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `reasoning_start`
- `parentToolCallId` (string, optional)
- `scope` (enum, optional)
  - Allowed values: `turn`, `loop`
- `subagent` (ExecutionStreamEventOneOf13Subagent, optional)

### ExecutionStreamEvent14

- `delta` (string, required)
- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `reasoning_delta`
- `subagent` (ExecutionStreamEventOneOf14Subagent, optional)

### ExecutionStreamEvent15

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `reasoning_complete`
- `scope` (enum, optional)
  - Allowed values: `turn`, `loop`
- `subagent` (ExecutionStreamEventOneOf15Subagent, optional)
- `text` (string, optional)

### ExecutionStreamEvent16

- `executionId` (string, required)
- `id` (string, required)
- `mediaType` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `media_start`
- `role` (enum, optional)
  - Allowed values: `user`, `assistant`, `system`
- `toolCallId` (string, optional)

### ExecutionStreamEvent17

- `delta` (string, required)
- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `media_delta`

### ExecutionStreamEvent18

- `executionId` (string, required)
- `id` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `media_complete`
- `data` (string, optional)
- `mediaType` (string, optional)
- `toolCallId` (string, optional)
- `url` (string, optional)

### ExecutionStreamEvent19

- `artifactType` (enum, required)
  - Allowed values: `markdown`, `component`
- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `artifact_start`
- `component` (string, optional)
- `executionId` (string, optional)
- `file` (ExecutionStreamEventOneOf19File, optional)
- `seq` (double, optional)
- `title` (string, optional)

### ExecutionStreamEvent20

- `delta` (string, required)
- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `artifact_delta`
- `executionId` (string, optional)
- `seq` (double, optional)

### ExecutionStreamEvent21

- `component` (string, required)
- `id` (string, required)
- `props` (map from string to any, required)
- `type` (enum, required)
  - Allowed values: `artifact_update`
- `executionId` (string, optional)
- `seq` (double, optional)

### ExecutionStreamEvent22

- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `artifact_complete`
- `executionId` (string, optional)
- `seq` (double, optional)

### ExecutionStreamEvent23

- `executionId` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `source`
- `id` (string, optional)
- `sourceType` (string, optional)
- `title` (string, optional)
- `url` (string, optional)

### ExecutionStreamEvent24

- `executionId` (string, required)
- `seq` (double, required)
- `state` (map from string to any, required)
- `type` (enum, required)
  - Allowed values: `state_snapshot`
- `iteration` (double, optional)

### ExecutionStreamEvent25

- `executionId` (string, required)
- `patch` (list of ExecutionStreamEventOneOf25PatchItems, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `state_delta`
- `iteration` (double, optional)

### ExecutionStreamEvent26

- `executionId` (string, required)
- `seq` (double, required)
- `toolCallId` (string, required)
- `toolName` (string, required)
- `toolType` (string, required)
- `type` (enum, required)
  - Allowed values: `tool_start`
- `annotations` (ExecutionStreamEventOneOf26Annotations, optional)
- `hiddenParameterNames` (list of string, optional)
- `iteration` (double, optional)
- `origin` (enum, optional)
  - Allowed values: `webmcp`, `sdk`
- `pageOrigin` (string, optional)
- `parameters` (map from string to any, optional)
- `startedAt` (string, optional)
- `stepId` (string, optional)
- `subagent` (ExecutionStreamEventOneOf26Subagent, optional)

### ExecutionStreamEvent27

- `delta` (string, required)
- `executionId` (string, required)
- `seq` (double, required)
- `toolCallId` (string, required)
- `type` (enum, required)
  - Allowed values: `tool_input_delta`
- `subagent` (ExecutionStreamEventOneOf27Subagent, optional)

### ExecutionStreamEvent28

- `executionId` (string, required)
- `parameters` (map from string to any, required)
- `seq` (double, required)
- `toolCallId` (string, required)
- `type` (enum, required)
  - Allowed values: `tool_input_complete`
- `hiddenParameterNames` (list of string, optional)
- `subagent` (ExecutionStreamEventOneOf28Subagent, optional)
- `toolName` (string, optional)

### ExecutionStreamEvent29

- `delta` (string, required)
- `executionId` (string, required)
- `seq` (double, required)
- `toolCallId` (string, required)
- `type` (enum, required)
  - Allowed values: `tool_output_delta`

### ExecutionStreamEvent30

- `executionId` (string, required)
- `seq` (double, required)
- `success` (boolean, required)
- `toolCallId` (string, required)
- `type` (enum, required)
  - Allowed values: `tool_complete`
- `error` (string, optional)
- `executionTime` (double, optional)
- `iteration` (double, optional)
- `result` (any, optional)
- `stepId` (string, optional)
- `subagent` (ExecutionStreamEventOneOf30Subagent, optional)
- `toolCost` (double, optional)
- `toolName` (string, optional)

### ExecutionStreamEvent31

- `approvalId` (string, required)
- `executionId` (string, required)
- `seq` (double, required)
- `toolName` (string, required)
- `type` (enum, required)
  - Allowed values: `approval_start`
- `description` (string, optional)
- `externalAgent` (ExecutionStreamEventOneOf31ExternalAgent, optional)
- `iteration` (double, optional)
- `parameters` (map from string to any, optional)
- `reason` (string, optional)
- `startedAt` (string, optional)
- `subagent` (ExecutionStreamEventOneOf31Subagent, optional)
- `timeout` (double, optional)
- `toolCallId` (string, optional)
- `toolType` (string, optional)

### ExecutionStreamEvent32

- `approvalId` (string, required)
- `decision` (enum, required)
  - Allowed values: `approved`, `denied`, `timeout`
- `executionId` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `approval_complete`
- `completedAt` (string, optional)
- `resolvedBy` (enum, optional)
  - Allowed values: `user`, `system`

### ExecutionStreamEvent33

- `executionId` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `await`
- `annotations` (ExecutionStreamEventOneOf33Annotations, optional)
- `awaitReason` (string, optional)
- `awaitedAt` (string, optional)
- `crawlId` (string, optional)
- `elicitation` (ExecutionStreamEventOneOf33Elicitation, optional)
- `externalAgent` (ExecutionStreamEventOneOf33ExternalAgent, optional)
- `origin` (enum, optional)
  - Allowed values: `webmcp`, `sdk`
- `pageOrigin` (string, optional)
- `parameters` (map from string to any, optional)
- `stepId` (string, optional)
- `toolCallId` (string, optional)
- `toolId` (string, optional)
- `toolName` (string, optional)

### ExecutionStreamEvent34

- `error` (ExecutionStreamEventOneOf34Error, required)
- `executionId` (string, required)
- `seq` (double, required)
- `type` (enum, required)
  - Allowed values: `error`
- `recoverable` (boolean, optional)

### ExecutionStreamEvent35

- `epoch` (integer, required)
- `executionId` (string, required)
- `kind` (enum, required)
  - Allowed values: `compaction`
- `phase` (enum, required)
  - Allowed values: `start`, `complete`
- `reason` (enum, required)
  - Allowed values: `threshold`, `overflow`, `manual`, `surface_policy`, `provider_mismatch`
- `seq` (double, required)
- `strategy` (enum, required)
  - Allowed values: `provider_native`, `summary`
- `tier` (integer, required)
- `type` (enum, required)
  - Allowed values: `context_notice`
- `outcome` (enum, optional)
  - Allowed values: `ok`, `failed`, `gap`, `skipped`
- `tokensAfter` (double, optional)
- `tokensBefore` (double, optional)

### ExecutionStreamEvent36

- `executionId` (string, required)
- `seq` (double, required)
- `timestamp` (string, required)
- `type` (enum, required)
  - Allowed values: `ping`

### ExecutionStreamEvent37

- `name` (string, required)
- `type` (enum, required)
  - Allowed values: `custom`
- `executionId` (string, optional)
- `seq` (double, optional)
- `value` (any, optional)

### BusyMessageRouteReport

- `route` (enum, required) — Where the message went: into the running execution, or after it.
  - Allowed values: `steer`, `queue`
- `source` (enum, required) — Why this route applied.
  - Allowed values: `classifier`, `abstained`, `timeout`, `error`, `unanswered`, `circuit_open`, `disabled`
- `model` (string, optional) — The decision model that answered.
- `probability` (double, optional) — Probability the message belongs to the running work (classifier only).
- `steerUnavailable` (boolean, optional) — The classifier chose steer but the running execution could no longer take input.

### Error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### IdentityAssertionUnavailableError

- `code` (enum, required) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
  - Allowed values: `IDENTITY_ASSERTION_UNAVAILABLE`
- `error` (string, required)
- `message` (string, required) — What to change: pass endUser or tenant, set a tenancyStrategy, or use an org.
- `details` (list of IdentityAssertionUnavailableErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### ExecuteAgentRequestConflictError0

- `candidateCount` (integer, required)
- `code` (enum, required)
  - Allowed values: `ORGANIZATION_MODEL_CONFIG_NEEDS_CONFIGURATION`
- `configId` (string, required)
- `details` (string, required)
- `error` (string, required)
- `modelId` (string, required)
- `provider` (string, required)

### ConversationBusyError

- `code` (enum, required)
  - Allowed values: `CONVERSATION_BUSY`
- `error` (string, required)
- `executionId` (string, optional) — The execution holding the conversation slot. Poll /v1/executions/\{executionId}/status, or send x-runtype-concurrency: steer to attach to it.
- `phase` (enum, optional) — Where the occupant is: `claiming` (admitted, not yet started; a steer attaches through the claim), `running`, `paused` (a steer stays pending until an authorized resume), or `queued` (an earlier queue-only turn is waiting).
  - Allowed values: `claiming`, `running`, `paused`, `queued`

### ConversationModifiedError

- `code` (enum, required) — The stored transcript changed between the read and the write; re-read and retry.
  - Allowed values: `CONVERSATION_MODIFIED`
- `error` (string, required)
- `details` (list of ConversationModifiedErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### ExecutionStreamEventOneOf1ExternalAgent

- `contextId` (string, optional)
- `taskId` (string, optional)

### ExecutionStreamEventOneOf1TotalTokens

- `input` (double, required)
- `output` (double, required)

### ExecutionStreamEventOneOf2Error

- string
- ExecutionStreamEventOneOf2Error1

### ExecutionStreamEventOneOf3Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf4Attributes

- string
- double
- boolean

### ExecutionStreamEventOneOf4EstimatedContextBreakdown

- `categories` (map from string to ExecutionStreamEventOneOf4EstimatedContextBreakdownCategories, required)
- `estimatedTotalTokens` (double, required)
- `contextWindowSize` (double, optional)
- `estimatedUtilizationPercent` (double, optional)

### ExecutionStreamEventOneOf4Fallback

- `attempts` (list of ExecutionStreamEventOneOf4FallbackAttemptsItems, required)
- `exhausted` (boolean, required)
- `used` (boolean, required)
- `model` (string, optional)
- `reason` (string, optional, nullable)

### ExecutionStreamEventOneOf4Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf4Tokens

- `input` (double, required)
- `output` (double, required)

### ExecutionStreamEventOneOf5Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf6Attributes

- string
- double
- boolean

### ExecutionStreamEventOneOf6Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf6Tokens

- `input` (double, required)
- `output` (double, required)
- `cacheRead` (double, optional)
- `cacheWrite` (double, optional)
- `reasoning` (double, optional)

### ExecutionStreamEventOneOf7Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf8Fallback

- `attempts` (list of ExecutionStreamEventOneOf8FallbackAttemptsItems, required)
- `exhausted` (boolean, required)
- `used` (boolean, required)
- `model` (string, optional)
- `reason` (string, optional, nullable)

### ExecutionStreamEventOneOf8Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf10Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf11Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf12Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf13Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf14Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf15Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf19File

- `mimeType` (string, required)
- `path` (string, required)
- `language` (string, optional)

### ExecutionStreamEventOneOf25PatchItems

- `op` (enum, required)
  - Allowed values: `add`, `remove`, `replace`, `move`, `copy`, `test`
- `path` (string, required)
- `from` (string, optional)
- `value` (any, optional)

### ExecutionStreamEventOneOf26Annotations

- `consequentialHint` (boolean, optional)
- `debugging` (boolean, optional)
- `destructiveHint` (boolean, optional)
- `idempotentHint` (boolean, optional)
- `openWorldHint` (boolean, optional)
- `readOnlyHint` (boolean, optional)
- `untrustedContentHint` (boolean, optional)

### ExecutionStreamEventOneOf26Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf27Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf28Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf30Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf31ExternalAgent

- `contextId` (string, optional)
- `taskId` (string, optional)

### ExecutionStreamEventOneOf31Subagent

- `toolName` (string, required)
- `agentName` (string, optional)
- `parentToolCallId` (string, optional)

### ExecutionStreamEventOneOf33Annotations

- `consequentialHint` (boolean, optional)
- `debugging` (boolean, optional)
- `destructiveHint` (boolean, optional)
- `idempotentHint` (boolean, optional)
- `openWorldHint` (boolean, optional)
- `readOnlyHint` (boolean, optional)
- `untrustedContentHint` (boolean, optional)

### ExecutionStreamEventOneOf33Elicitation

- `message` (string, required)
- `mode` (enum, required)
  - Allowed values: `form`, `url`
- `pauseCount` (double, optional)
- `requestedSchema` (map from string to any, optional)
- `requests` (list of ExecutionStreamEventOneOf33ElicitationRequestsItems, optional)
- `serverName` (string, optional)
- `url` (string, optional)

### ExecutionStreamEventOneOf33ExternalAgent

- `contextId` (string, optional)
- `taskId` (string, optional)

### ExecutionStreamEventOneOf34Error

- string
- ExecutionStreamEventOneOf34Error1

### IdentityAssertionUnavailableErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### ConversationModifiedErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### ExecutionStreamEventOneOf2Error1

- `code` (string, required)
- `message` (string, required)
- `details` (map from string to any, optional)

### ExecutionStreamEventOneOf4EstimatedContextBreakdownCategories

- `chars` (double, required)
- `estimatedTokens` (double, required)

### ExecutionStreamEventOneOf4FallbackAttemptsItems

- `attempt` (double, required)
- `success` (boolean, required)
- `type` (enum, required)
  - Allowed values: `retry`, `model`, `message`, `flow`
- `error` (string, optional)
- `model` (string, optional)

### ExecutionStreamEventOneOf8FallbackAttemptsItems

- `attempt` (double, required)
- `success` (boolean, required)
- `type` (enum, required)
  - Allowed values: `retry`, `model`, `message`, `flow`
- `error` (string, optional)
- `model` (string, optional)

### ExecutionStreamEventOneOf33ElicitationRequestsItems

- `message` (string, required)
- `mode` (enum, required)
  - Allowed values: `form`, `url`
- `name` (string, required)
- `requestedSchema` (map from string to any, optional)
- `url` (string, optional)

### ExecutionStreamEventOneOf34Error1

- `code` (string, required)
- `message` (string, required)
- `details` (map from string to any, optional)

## Examples

### Execute Agent

**Request**

```json
{
  "messages": [
    {
      "content": "Help me with my order",
      "role": "user"
    }
  ],
  "options": {
    "streamResponse": true
  }
}
```

**SDK Code**

```python Execute Agent
import requests

url = "https://api.runtype.com/v1/agents/id/execute"

payload = {
    "messages": [
        {
            "content": "Help me with my order",
            "role": "user"
        }
    ],
    "options": { "streamResponse": True }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Execute Agent
const url = 'https://api.runtype.com/v1/agents/id/execute';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Help me with my order","role":"user"}],"options":{"streamResponse":true}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Execute Agent
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents/id/execute"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Execute Agent
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents/id/execute")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Execute Agent
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.runtype.com/v1/agents/id/execute")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}")
  .asString();
```

```php Execute Agent
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.runtype.com/v1/agents/id/execute', [
  'body' => '{
  "messages": [
    {
      "content": "Help me with my order",
      "role": "user"
    }
  ],
  "options": {
    "streamResponse": true
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Execute Agent
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents/id/execute");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Execute Agent
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "messages": [
    [
      "content": "Help me with my order",
      "role": "user"
    ]
  ],
  "options": ["streamResponse": true]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents/id/execute")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Execute Agent

**Request**

```json
{
  "messages": [
    {
      "content": "Help me with my order",
      "role": "user"
    }
  ],
  "options": {
    "streamResponse": true
  }
}
```

**SDK Code**

```python Execute Agent
import requests

url = "https://api.runtype.com/v1/agents/id/execute"

payload = {
    "messages": [
        {
            "content": "Help me with my order",
            "role": "user"
        }
    ],
    "options": { "streamResponse": True }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Execute Agent
const url = 'https://api.runtype.com/v1/agents/id/execute';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Help me with my order","role":"user"}],"options":{"streamResponse":true}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Execute Agent
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents/id/execute"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Execute Agent
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents/id/execute")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Execute Agent
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.runtype.com/v1/agents/id/execute")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}")
  .asString();
```

```php Execute Agent
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.runtype.com/v1/agents/id/execute', [
  'body' => '{
  "messages": [
    {
      "content": "Help me with my order",
      "role": "user"
    }
  ],
  "options": {
    "streamResponse": true
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Execute Agent
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents/id/execute");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Help me with my order\",\n      \"role\": \"user\"\n    }\n  ],\n  \"options\": {\n    \"streamResponse\": true\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Execute Agent
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "messages": [
    [
      "content": "Help me with my order",
      "role": "user"
    ]
  ],
  "options": ["streamResponse": true]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents/id/execute")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```