Sign in
latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-0393116227.2 KB

f5f5994dfe05

agent

Create agent run

Create an asynchronous agent run and start execution in the background.

Required roles: All, App

post/agent/runs

Request body

idempotency_keystring

Optional idempotency key for reusing an existing asynchronous run.

Example request

{
  "input": {
    "redactionPolicyId": "pii-standard",
    "forwardedProps": {
      "principal_id": "user-123"
    }
  }
}

Response

Agent run accepted

run_idstring required
thread_idstring
workflow_typestring required
provider'ANTHROPIC_DIRECT' | 'BEDROCK' | 'VERTEX_AI' required
execution_mode'LOCAL' | 'AGENTCORE' required
statusstring required

Agent run status. Values are QUEUED, RUNNING, SUCCEEDED, FAILED, or CANCELLED.

runtime_arnstring
runtime_session_idstring
mcp_session_idstring
trace_idstring
idempotency_keystring
created_atstring date-time
started_atstring date-time
finished_atstring date-time
inputobject

Original RunAgentInput. Used to reconstruct a thread's transcript on restore.

parent_run_idstring nullable

Run this run branched from within the thread (null for the thread root).

resultobject
errorobject