---
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.

Use \`inputHistoryMode=delta\_v1\` to send only \`newUserMessage\` and let the server reconstruct a bounded rolling context. A continuation supplies the thread's authoritative \`current\_run\_id\` as \`baseRunId\`.

Required scope: \`inference:run\`

## Headers

- `Idempotency-Key` string

## Request body

- CreateAgentRunRequest
  - `input` union, required — Agent run input. `legacy_full` accepts a complete AG-UI history; `delta_v1` accepts only the newest user turn and lets the server rebuild a bounded rolling context.
    - LegacyFullAgentRunInput
      - `inputHistoryMode` 'legacy_full' — Complete-history compatibility mode. May be omitted.
      - `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.
      - `agentId` string, uuid — Agent that owns the thread. Required by the service when first-class history is used.
      - `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.
    - DeltaV1AgentRunInput
      - `inputHistoryMode` 'delta_v1', required — Server-managed rolling-window history mode.
      - `agentId` string, uuid, required — Agent that owns the new or continued thread.
      - `threadId` string — Server-issued thread ID to continue. Omit together with `baseRunId` to create a new thread.
      - `baseRunId` string — Authoritative `current_run_id` returned by `GET /agent/threads`. Required when `threadId` is present and rejected for a new thread. A stale value returns `409 THREAD_ADVANCED`.
      - `retryRunId` string — Retry the current failed or cancelled run without duplicating its user turn. When present, it must equal `baseRunId` and use the same `newUserMessage`.
      - `newUserMessage` AgentDeltaUserMessage, required
        - `id` string, required
        - `role` 'user', required
        - `content` union, required — AG-UI user message text or multimodal content-part array.
          - string
          - AgentDeltaContentPart[]
            - `type` 'text' | 'image' | 'audio' | 'video' | 'document' | 'binary', required
            - `text` string
            - `source` object
            - `metadata` object
            - `mimeType` string
            - `id` string
            - `url` string
            - `data` string
            - `filename` string
        - `name` string, nullable
        - `encryptedValue` string, nullable
      - `uiStateDelta` object, nullable — Current-turn UI state delta. Omit when no state changed.
      - `messages` object[] — Compatibility field; if present it must be an empty array.
      - `tools` object[]
      - `context` object[]
      - `resume` object[], nullable
      - `redactionPolicyId` string, nullable — Versioned redaction policy applied before external provider calls. Omitted or `null` means no redaction. Unknown IDs return `422 UNKNOWN_REDACTION_POLICY`; unavailable redaction returns 503 and never falls back to unmasked forwarding.
      - `forwardedProps` object — AG-UI extension properties. `retrieval_mode` accepts `required` (default) or `disabled`; the server validates known QAIP keys before use.

## 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 — 保存済みW3C trace contextから導出したlowercase OpenTelemetry trace ID。移行前の行はnull。
  - `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).
  - `input_history_mode` 'legacy_full' | 'delta_v1', required — How the request supplied conversation history for this run.
  - `context_start_run_id` string, nullable, required — Oldest run included in the reconstructed rolling context, or null when none was needed.
  - `context_truncated` boolean, required — Whether older turns were omitted to stay within the server context budget.
  - `result` object, nullable
  - `error` object, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `409` — Thread conflict: an active run exists (`THREAD_ACTIVE`), `baseRunId` is stale (`THREAD_ADVANCED`), the retry is not allowed (`RETRY_NOT_ALLOWED`), or the idempotency key was reused with different semantics (`IDEMPOTENCY_CONFLICT`).
- `413` — Request body exceeds the 1 MiB agent run limit.
- `422` — Unprocessable Entity. `delta_v1` requires a non-blank `Idempotency-Key` (`IDEMPOTENCY_KEY_REQUIRED`) and must satisfy its mode-specific input contract. Also returned when `redactionPolicyId` is unknown (`UNKNOWN_REDACTION_POLICY`) or the AgentCore runtime has no redactor wired up (`AGENTCORE_REDACTION_UNSUPPORTED`). The machine-readable code is in `error.type` for service errors; schema validation uses the framework's `detail` array. 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

> 71 revisions in range; 18 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-service-production.skmtc.workers.dev/v1/apis/qlonolink/qaip-apis/revisions/61dc40676905/schema)