---
title: "Create agent run"
method: POST
path: "/agent/runs"
tags: ["agent"]
---

# Create agent run

`POST /agent/runs`

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

Required scope: \`inference:run\`

## Headers

- `Idempotency-Key` string

## Request body

- CreateAgentRunRequest
  - `input` CreateAgentRunInput, required
    - `threadId` string — Server-issued thread ID to continue. Omit to create a new thread.
    - `parentRunId` string — Server-issued run ID to branch from. Its thread must match threadId when both are supplied.
    - `state` object, nullable — AG-UI state supplied to the run.
    - `messages` object[]
    - `tools` object[]
    - `context` object[]
    - `resume` object[], nullable
    - `redactionPolicyId` string, nullable — ID of a versioned redaction policy to apply before sending the conversation to the external model / embedding provider. When omitted or `null` (the default), **no redaction is performed and the input is sent to the external provider as-is**. This is an explicit API contract, not a fail-open behavior: omitting the field never silently sanitizes the input. When a known ID is given, the conversation history (all roles, string/array/dict content, tool call arguments, string metadata and source URLs), RAG search query and results, Google web search query and results, external table results, and all other tool results are masked with that policy before they reach the corresponding external model or embedding provider. The original text is still stored in `agent_runs.input` and emitted in `RUN_STARTED` for UI display; only the copy sent to the external provider is masked. Restoration mappings are never stored. Errors: - unknown ID or an empty string: `422` (never interpreted as "no redaction") - used on a deployment whose AgentCore runtime has no redactor wired up: `422 AGENTCORE_REDACTION_UNSUPPORTED`. Where the wiring is in place, the AgentCore execution mode applies the same redaction as the local mode - redactor unavailable / timeout / failure: `503 REDACTION_UNAVAILABLE` before the run starts, or a `RUN_ERROR` with code `REDACTION_FAILED` during the run. The request is never forwarded unmasked as a fallback. - concurrent redaction runs saturated in the AgentCore execution mode: `503 REDACTION_CAPACITY_EXCEEDED` before the run starts. Each run executes in its own microVM, so the per-process concurrency limit cannot bound the load on the shared redactor; the number of concurrent policy-bearing runs is capped instead. Retrying later succeeds. A parent run's policy is not inherited: a child run is redacted only when it specifies `redactionPolicyId` itself.
    - `forwardedProps` object — AG-UI extension properties forwarded to the run. This remains a free-form object because AG-UI clients and server-side integrations may add extension keys. Known QAIP keys include `filters`, `authz_policy`, `principal_id`, `grounding`, and `retrieval_mode`; their values are validated by the run service before use. `retrieval_mode` controls only the built-in QAIP knowledge-base `search` tool. Its accepted values are `required` (the default when omitted) and `disabled`. In `disabled` mode the tool and its retrieval/citation system instructions are both omitted. It does not disable explicitly configured external-table tools or Google grounding.

## Response `202`

Agent run accepted

- AgentRun
  - `run_id` string, required
  - `thread_id` string, required
  - `workflow_type` string, required
  - `provider` 'ANTHROPIC_DIRECT' | 'BEDROCK' | 'OPENAI' | 'VERTEX_AI', required
  - `execution_mode` 'LOCAL' | 'AGENTCORE', required
  - `status` 'QUEUED' | 'RUNNING' | 'CANCELLING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED', required — Agent run lifecycle state.
  - `runtime_arn` string, nullable
  - `mcp_session_id` string, nullable
  - `trace_id` string, nullable
  - `idempotency_key` string, nullable
  - `created_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable
  - `input` object, nullable — Server-enriched agent input used to reconstruct the thread transcript.
  - `parent_run_id` string, nullable — Run this run branched from within the thread (null for the thread root).
  - `result` object, nullable
  - `error` object, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `409` — The thread already has an active run.
- `413` — Request body exceeds the 1 MiB agent run limit.
- `422` — Unprocessable Entity. Returned when `redactionPolicyId` is an unknown policy ID (`UNKNOWN_REDACTION_POLICY`), or when it is used on a deployment whose AgentCore runtime has no redactor wired up (`AGENTCORE_REDACTION_UNSUPPORTED`); the machine-readable code is in `error.type`. An empty or blank string is rejected by schema validation and returns the framework's validation error shape (`detail` array) instead of this schema. In every case no run record or event is created and no external provider is called.
- `429` — The authenticated tenant has reached its concurrent agent run limit.
- `500` — Internal Server Error
- `503` — Service Unavailable. Returned when the deployment-wide Agent run capacity is saturated (`AGENT_RUN_CAPACITY_EXCEEDED`), or when `redactionPolicyId` is specified but the redaction request cannot be accepted. In the latter case, `error.type` is `REDACTION_UNAVAILABLE` when the redactor is not configured or not reachable, and `REDACTION_CAPACITY_EXCEEDED` when the redactor is healthy but the concurrent redaction run limit is saturated (AgentCore execution mode only). The request is never forwarded unmasked. The redaction-specific rejection modes do not affect requests without `redactionPolicyId`; deployment-wide capacity applies to every Agent run request.

## Changes

> 65 revisions in range; 12 not diffed.

- **2026-07-29** `f5f5994dfe05` — 3 info
  - added the new optional request property `input/redactionPolicyId`
  - added the non-success response with the status `422`
  - added the non-success response with the status `503`
- **2026-07-23** `09c7c8b9121d` — 1 info
  - added the new optional request property `input/forwardedProps/filters/metadata_filter`
- **2026-07-10** `05d4c3bc46f2` — 2 info
  - added the optional property `input` to the response with the `202` status
  - added the optional property `parent_run_id` to the response with the `202` status
- **2026-06-26** `5b90237b6d51` — 1 info
  - added the new optional request property `input/forwardedProps/grounding`
- **2026-06-17** `05add33422b2` — 2 info
  - added the new optional request property `input/forwardedProps/authz_policy`
  - added the new optional request property `input/forwardedProps/principal_id`

[Full history](https://skmtc.dev/qlonolink/apis/qaip-apis/changes/agent/runs/post.md)

---

[API](https://skmtc.dev/qlonolink/apis/qaip-apis.md) · [All operations](https://skmtc.dev/qlonolink/apis/qaip-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/qlonolink/apis/qaip-apis/revisions/430440bbcc56?raw)