---
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 roles: All, App

## Request body

- CreateAgentRunRequest
  - `input` RunAgentInput, required
    - `run_id` string — Optional ID for the run
    - `thread_id` string — Optional ID for the thread
    - `messages` AgentMessage[]
      - `role` 'system' | 'user' | 'assistant', required — The role of the message sender
      - `content` union, required
        - string
        - AgentMessageContent[]
          - `type` 'text'
          - `text` string
    - `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), the RAG search query and the RAG search results are masked with that policy before any external call. 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") - combined with the AgentCore execution mode: `422 AGENTCORE_REDACTION_UNSUPPORTED` - 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. A parent run's policy is not inherited: a child run is redacted only when it specifies `redactionPolicyId` itself.
    - `forwardedProps` object — Forwarded properties for the run (AG-UI standard)
      - `filters` AgentFilters — Filters for agent search and completion
        - `citation` boolean — Whether to include citations in the response
        - `tags` string[] — target tag names to be obtained
        - `tag_ids` string[] — target tag IDs to be obtained
        - `tag_filter_logic` 'AND' | 'OR' — Logical operator for combining filter conditions
        - `source_types` SourceType[]
        - `file_types` FileType[]
        - `date_from` integer — Start date for content search (Unix timestamp in seconds)
        - `date_to` integer — End date for content search (Unix timestamp in seconds)
        - `domains` string[] — Array of domains to search within (supports partial matching)
        - `metadata` MetadataFilterGroup — (reserved for future use) Filter group with nested structure. Supports combining filters with AND/OR logic.
          - `logic` 'AND' | 'OR' — Logical operator for combining filter conditions
          - `filters` MetadataFilter[] — Filters within this group (combined using the logic operator)
            - `key` string, required — Metadata key
            - `val` unknown
            - `type` 'string' | 'integer' | 'float' | 'date' | 'datetime', required — Data type of the metadata value
            - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'between', required — Comparison operator
            - `min` unknown
            - `max` unknown
          - `groups` MetadataFilterGroup[] — Nested subgroups
        - `source_metadata` MetadataFilterGroup — (reserved for future use) Filter group with nested structure. Supports combining filters with AND/OR logic.
          - `logic` 'AND' | 'OR' — Logical operator for combining filter conditions
          - `filters` MetadataFilter[] — Filters within this group (combined using the logic operator)
            - `key` string, required — Metadata key
            - `val` unknown
            - `type` 'string' | 'integer' | 'float' | 'date' | 'datetime', required — Data type of the metadata value
            - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'between', required — Comparison operator
            - `min` unknown
            - `max` unknown
          - `groups` MetadataFilterGroup[] — Nested subgroups
        - `chunk_metadata` MetadataFilterGroup — (reserved for future use) Filter group with nested structure. Supports combining filters with AND/OR logic.
          - `logic` 'AND' | 'OR' — Logical operator for combining filter conditions
          - `filters` MetadataFilter[] — Filters within this group (combined using the logic operator)
            - `key` string, required — Metadata key
            - `val` unknown
            - `type` 'string' | 'integer' | 'float' | 'date' | 'datetime', required — Data type of the metadata value
            - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'between', required — Comparison operator
            - `min` unknown
            - `max` unknown
          - `groups` MetadataFilterGroup[] — Nested subgroups
        - `metadata_filter` MetadataFilterGroup — (reserved for future use) Filter group with nested structure. Supports combining filters with AND/OR logic.
          - `logic` 'AND' | 'OR' — Logical operator for combining filter conditions
          - `filters` MetadataFilter[] — Filters within this group (combined using the logic operator)
            - `key` string, required — Metadata key
            - `val` unknown
            - `type` 'string' | 'integer' | 'float' | 'date' | 'datetime', required — Data type of the metadata value
            - `operator` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'between', required — Comparison operator
            - `min` unknown
            - `max` unknown
          - `groups` MetadataFilterGroup[] — Nested subgroups
        - `use_postfilter` boolean — Whether to bypass LanceDB prefilter and apply WHERE after the vector search (IVF_PQ) returns top-K. Significantly faster for broad filters that cover most of the table, but may return fewer than `limit` results when the hit rate is low.
        - `limit` integer — Maximum number of chunks to retrieve as context for the agent
      - `authz_policy` string — (reserved for future use) Name of the registered authz policy to evaluate when the agent retrieves context. Defaults to the reserved "default" policy when omitted. Ignored when authz is disabled.
      - `principal_id` string — Identifier of the end-user (principal) on whose behalf this request is made. Used to look up the principal's authz subject attributes for policy evaluation. When omitted, subject attributes are empty (most restrictive). Ignored when authz is disabled.
      - `grounding` boolean — Whether to enable Gemini's Google Search grounding during the agent run. Only effective when the agent model is a Gemini model and the `gemini_grounding` feature is enabled on the server; otherwise this flag is ignored. Mirrors the `/completions` `grounding` parameter.
  - `idempotency_key` string — Optional idempotency key for reusing an existing asynchronous run.

## Response `202`

Agent run accepted

- AgentRun
  - `run_id` string, required
  - `thread_id` string
  - `workflow_type` string, required
  - `provider` 'ANTHROPIC_DIRECT' | 'BEDROCK' | 'VERTEX_AI', required
  - `execution_mode` 'LOCAL' | 'AGENTCORE', required
  - `status` string, required — Agent run status. Values are QUEUED, RUNNING, SUCCEEDED, FAILED, or CANCELLED.
  - `runtime_arn` string
  - `runtime_session_id` string
  - `mcp_session_id` string
  - `trace_id` string
  - `idempotency_key` string
  - `created_at` string, date-time
  - `started_at` string, date-time
  - `finished_at` string, date-time
  - `input` object — Original RunAgentInput. Used to reconstruct a thread's transcript on restore.
  - `parent_run_id` string, nullable — Run this run branched from within the thread (null for the thread root).
  - `result` object
  - `error` object

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `422` — Unprocessable Entity. Returned when `redactionPolicyId` is an unknown policy ID (`UNKNOWN_REDACTION_POLICY`) or when it is combined with the AgentCore execution mode (`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.
- `500` — Internal Server Error
- `503` — Service Unavailable. Returned when `redactionPolicyId` is specified but the local redactor is not configured or not reachable; `error.type` is `REDACTION_UNAVAILABLE`. The request is never forwarded unmasked. Requests without `redactionPolicyId` are unaffected.

---

[API](https://skmtc.net/qlonolink/apis/qaip-apis.md) · [All operations](https://skmtc.net/qlonolink/apis/qaip-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qlonolink/qaip-apis/versions/f5f5994dfe05/schema)