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`
## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/qaip/openapi.documented.yml post /agent/runs openapi: 3.0.3 info: title: QAIP APIs version: 1.0.0 servers: - url: https://developer.qaip.com/api/v1 description: API base path security: - ApiKeyAuth: [] tags: - name: completions description: Generate completions - name: search description: Search content - name: query description: Query materialized external tables - name: extract description: Data extraction using LLM - name: tags description: List available tags - name: agent description: (Experimental) Agent operations - name: tag-source-groups description: Tag and source group associations - name: source-groups description: Source group (job) management and metadata - name: sources description: Sources management and metadata - name: local-file-groups description: Local file group management - name: secrets description: Secret management - name: google-drives description: Google Drive data source management - name: google-drive-settings description: Google Drive data source setting management - name: crawls description: Web crawl data source management - name: crawl-settings description: Web crawl setting management - name: githubs description: GitHub data source management - name: github-settings description: GitHub data source setting management - name: notions description: Notion data source management - name: notion-settings description: Notion data source setting management - name: authz-subject-attributes description: >- Authorization subject attribute management (requires the `authz:grant` scope) - name: redaction-policies description: >- Tenant redaction policy management (requires the `policy:redaction:manage` scope) - name: api-keys description: API key issuance (requires the `apikeys:issue` scope) paths: /agent/runs: post: tags: - agent summary: Create agent run description: >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`
operationId: createAgentRun parameters: - name: Idempotency-Key in: header required: false description: > Retry key scoped to the authenticated tenant and principal. Required and non-blank for every `delta_v1` request; optional for `legacy_full`. schema: type: string minLength: 1 maxLength: 256 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRunRequest' responses: '202': description: Agent run accepted content: application/json: schema: $ref: '#/components/schemas/AgentRun' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: > 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`). content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: Request body exceeds the 1 MiB agent run limit. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: > 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. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: The authenticated tenant has reached its concurrent agent run limit. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: > 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. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] x-codeSamples: - lang: Python source: |- import os from qaip import Qaip client = Qaip( api_key=os.environ.get("QAIP_API_KEY"), # This is the default and can be omitted ) agent_run = client.agent.create_run( input={}, ) print(agent_run.context_start_run_id) components: schemas: CreateAgentRunRequest: type: object additionalProperties: false required: - input properties: input: $ref: '#/components/schemas/CreateAgentRunInput' AgentRun: type: object required: - run_id - thread_id - workflow_type - provider - execution_mode - status - input_history_mode - context_start_run_id - context_truncated properties: run_id: type: string thread_id: type: string workflow_type: type: string provider: $ref: '#/components/schemas/AgentProvider' execution_mode: $ref: '#/components/schemas/AgentExecutionMode' status: $ref: '#/components/schemas/AgentRunStatus' runtime_arn: type: string nullable: true mcp_session_id: type: string nullable: true trace_id: type: string nullable: true pattern: ^[0-9a-f]{32}$ description: >- 保存済みW3C trace contextから導出したlowercase OpenTelemetry trace ID。移行前の行はnull。 example: 4bf92f3577b34da6a3ce929d0e0e4736 idempotency_key: type: string nullable: true created_at: type: string format: date-time nullable: true started_at: type: string format: date-time nullable: true finished_at: type: string format: date-time nullable: true input: type: object additionalProperties: true nullable: true description: >- Server-enriched agent input used to reconstruct the thread transcript. parent_run_id: type: string nullable: true description: >- Run this run branched from within the thread (null for the thread root). input_history_mode: $ref: '#/components/schemas/AgentInputHistoryMode' context_start_run_id: type: string nullable: true description: >- Oldest run included in the reconstructed rolling context, or null when none was needed. context_truncated: type: boolean description: >- Whether older turns were omitted to stay within the server context budget. result: type: object additionalProperties: true nullable: true error: type: object additionalProperties: true nullable: true Error: type: object required: - error properties: error: type: object required: - message - type properties: message: type: string description: Human-readable error message type: type: string description: Machine-readable error code CreateAgentRunInput: oneOf: - $ref: '#/components/schemas/LegacyFullAgentRunInput' - $ref: '#/components/schemas/DeltaV1AgentRunInput' description: > 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. AgentProvider: type: string enum: - ANTHROPIC_DIRECT - BEDROCK - OPENAI - VERTEX_AI AgentExecutionMode: type: string enum: - LOCAL - AGENTCORE AgentRunStatus: type: string description: Agent run lifecycle state. enum: - QUEUED - RUNNING - CANCELLING - SUCCEEDED - FAILED - CANCELLED AgentInputHistoryMode: type: string description: How the request supplied conversation history for this run. enum: - legacy_full - delta_v1 LegacyFullAgentRunInput: type: object additionalProperties: false properties: inputHistoryMode: type: string enum: - legacy_full default: legacy_full description: Complete-history compatibility mode. May be omitted. threadId: type: string minLength: 1 description: Server-issued thread ID to continue. Omit to create a new thread. parentRunId: type: string minLength: 1 description: >- Server-issued run ID to branch from. Its thread must match threadId when both are supplied. agentId: type: string format: uuid description: >- Agent that owns the thread. Required by the service when first-class history is used. state: type: object additionalProperties: true nullable: true description: AG-UI state supplied to the run. messages: type: array items: type: object additionalProperties: true description: AG-UI message object. tools: type: array items: type: object additionalProperties: true description: AG-UI tool declaration. context: type: array items: type: object additionalProperties: true description: AG-UI context object. resume: type: array nullable: true items: type: object additionalProperties: true description: AG-UI resume entry. redactionPolicyId: type: string minLength: 1 pattern: ^[A-Za-z0-9._-]+$ nullable: true description: > 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. example: pii-standard forwardedProps: type: object description: > 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. additionalProperties: true DeltaV1AgentRunInput: type: object additionalProperties: false required: - inputHistoryMode - agentId - newUserMessage properties: inputHistoryMode: type: string enum: - delta_v1 description: Server-managed rolling-window history mode. agentId: type: string format: uuid description: Agent that owns the new or continued thread. threadId: type: string minLength: 1 description: > Server-issued thread ID to continue. Omit together with `baseRunId` to create a new thread. baseRunId: type: string minLength: 1 description: > 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: type: string minLength: 1 description: > Retry the current failed or cancelled run without duplicating its user turn. When present, it must equal `baseRunId` and use the same `newUserMessage`. newUserMessage: $ref: '#/components/schemas/AgentDeltaUserMessage' uiStateDelta: type: object additionalProperties: true nullable: true description: Current-turn UI state delta. Omit when no state changed. messages: type: array maxItems: 0 description: Compatibility field; if present it must be an empty array. items: type: object additionalProperties: true tools: type: array items: type: object additionalProperties: true description: AG-UI tool declaration used for this run. context: type: array items: type: object additionalProperties: true description: AG-UI context object used for this run. resume: type: array nullable: true items: type: object additionalProperties: true description: AG-UI resume entry. redactionPolicyId: type: string minLength: 1 pattern: ^[A-Za-z0-9._-]+$ nullable: true description: > 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: type: object additionalProperties: true description: > AG-UI extension properties. `retrieval_mode` accepts `required` (default) or `disabled`; the server validates known QAIP keys before use. AgentDeltaUserMessage: type: object additionalProperties: false required: - id - role - content properties: id: type: string minLength: 1 role: type: string enum: - user content: oneOf: - type: string - type: array items: $ref: '#/components/schemas/AgentDeltaContentPart' description: AG-UI user message text or multimodal content-part array. name: type: string nullable: true encryptedValue: type: string nullable: true AgentDeltaContentPart: type: object additionalProperties: false required: - type properties: type: type: string enum: - text - image - audio - video - document - binary text: type: string source: type: object additionalProperties: true metadata: type: object additionalProperties: true mimeType: type: string id: type: string url: type: string data: type: string filename: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication ````