Sign in

f5f5994dfe05

latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-0393116227.2 KB
agent

Run agent

Run the agent with the given input and stream the events.

Required roles: All, App

post/agent/run

Request body

run_idstring

Optional ID for the run

thread_idstring

Optional ID for the thread

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

Example request

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

Response

Successful agent run (stream)