AgentCore:AG-UI protocol reference

Request headers

Request body

{
  "threadId": "session-001",
  "runId": "run-001",
  "messages": [
    {
      "id": "message-001",
      "role": "user",
      "content": "Introduce your capabilities in three bullet points."
    }
  ],
  "state": {},
  "tools": [],
  "context": [],
  "forwardedProps": {}
}

Message fields

developer messages are treated as system messages. Historical messages of type activity and reasoning are not used as model input for the current run.

Multimodal input

A user message can contain text, images, audio, video, or documents. Actual support depends on the selected Harness and model.

The following is an image message placed in the messages array of the request:

{
  "id": "message-002",
  "role": "user",
  "content": [
    {"type": "text", "text": "Analyze the anomaly in the image"},
    {
      "type": "image",
      "source": {
        "type": "url",
        "value": "https://example.com/error.png",
        "mimeType": "image/png"
      }
    }
  ]
}

To pass Base64 content, set source.type=data and put the data in source.value. Other content types are audio, video, and document.

Client tools

tools declares tools provided by the caller, which differ from MCP tools bound in the console. Example of a single tool:

{
  "name": "get_order",
  "description": "Query an order by order number",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {"type": "string"}
    },
    "required": ["orderId"]
  }
}

If the selected Harness or Agent configuration does not support client tools, the request may return EXECUTOR_INPUT_UNSUPPORTED.

SSE format

AG-UI always returns SSE and does not provide a stream:false switch. To display a complete answer at once, the application should first receive and concatenate the text, then display it after confirming successful execution.

Example response headers:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
X-AgentCore-Session-ID: session-001

Each event consists of id and data, separated by blank lines. data is JSON. The first RUN_STARTED uses id: 0; subsequent event IDs increment.

Example text reply:

id: 0
data: {"type":"RUN_STARTED","threadId":"session-001","runId":"run-001"}

id: 1
data: {"type":"TEXT_MESSAGE_START","messageId":"assistant-001","role":"assistant"}

id: 2
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"assistant-001","delta":"I can help with Q&A, files, and tool calls."}

id: 3
data: {"type":"TEXT_MESSAGE_END","messageId":"assistant-001"}

id: 4
data: {"type":"RUN_FINISHED","threadId":"session-001","runId":"run-001","outcome":{"type":"success"}}

Event types

outcome.type=interrupt means the run requires external input; this behavior requires support from the selected Harness.

Result handling

1. Check the HTTP status code and response type before parsing SSE.

2. Split complete events by blank lines.

3. Concatenate text by messageId, and concatenate tool arguments and record results by toolCallId; events of different messages and tools may interleave.

4. After each event is fully processed, save its id for reconnection.

5. On RUN_FINISHED, check outcome; on RUN_ERROR, record the error.

If the connection closes before an end event is received, record it as a connection interruption.

File results

When file publishing is enabled, files are returned via temporary download links. TOOL_CALL_RESULT.content is a JSON string; the parsed structure is as follows:

{
  "status": "success",
  "files": [
    {
      "fileName": "report.csv",
      "mimeType": "text/csv",
      "downloadUrl": "https://example.com/temporary-download-link",
      "expiresInSeconds": 3600
    }
  ]
}

On file publishing failure, status=error and an error message are returned; unconverted non-text output may trigger AG_UI_OUTPUT_UNSUPPORTED.

Before the event stream is established

On request failure, errors are returned via HTTP status codes and JSON:

{
  "error": {
    "code": "SESSION_ID_MISMATCH",
    "message": "X-AgentCore-Session-ID must equal RunAgentInput.threadId."
  }
}

Authentication, access permissions, and gateway limits may also return errors before the request reaches the Agent; check the endpoint configuration and the actual response.

After the event stream is established

On execution failure or cancellation, the error is returned via RUN_ERROR, then the event stream is closed:

id: 6
data: {"type":"RUN_ERROR","code":"RUN_CANCELLED","message":"Run cancelled."}