AG-UI protocol contract

The AG-UI protocol contract defines the requirements for implementing agent-to-user interface communication in Amazon Bedrock AgentCore Runtime. This contract specifies the technical requirements, endpoints, and communication patterns that your AG-UI agent must implement.

For example code, see Deploy AG-UI servers in AgentCore Runtime.

Protocol implementation requirements

Your AG-UI agent must implement these specific protocol requirements:

Container requirements

Your AG-UI agent must be deployed as a containerized application meeting these specifications:

Path requirements

/invocations - POST

Purpose

Receives user requests and streams responses as Server-Sent Events (SSE)

Use cases

The invocations endpoint serves several key purposes:

Request format

Amazon Bedrock AgentCore passes request payloads directly to your container without validation. To be AG-UI-compliant, your requests should follow the RunAgentInput format. Your container implementation determines which fields are required and how validation errors are handled.

AG-UI-compliant agents expect a RunAgentInput JSON payload. Example:

{
  "threadId": "thread-123",
  "runId": "run-456",
  "messages": [{"id": "msg-1", "role": "user", "content": "Hello, agent!"}],
  "tools": [],
  "context": [],
  "state": {},
  "forwardedProps": {}
}

For the complete RunAgentInput schema and message format details, see AG-UI Types.

Response format

AG-UI agents respond with SSE-formatted event streams:

Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-789","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-789","delta":"Processing your request"}

data: {"type":"TOOL_CALL_START","toolCallId":"tool-001","toolCallName":"search","parentMessageId":"msg-789"}

data: {"type":"TOOL_CALL_RESULT","messageId":"msg-789","toolCallId":"tool-001","content":"Search completed"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-789"}

data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"}

/ws - WebSocket

Purpose

Provides bidirectional real-time communication between clients and agents

Use cases

The WebSocket endpoint serves several key purposes:

/ping - GET

Purpose

Verifies that your AG-UI agent is operational and ready to handle requests

Response format

Returns a status code indicating your agent’s health:

{
  "status": "Healthy"
}

status is required and is one of Healthy or HealthyBusy. While the status is HealthyBusy, the runtime session is kept alive.

An optional time_of_last_update field (a Unix timestamp in seconds) may be included to report when the status last changed.

Authentication requirements

AG-UI agents support multiple authentication mechanisms:

OAuth 2.0 Bearer Tokens

For AG-UI client authentication, include the Bearer token in request headers:

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

SigV4 Authentication

Standard AWS SigV4 authentication is also supported for programmatic access.

Error handling

AG-UI serializes every error as an SSE RUN_ERROR event (Content-Type: text/event-stream), whether the error occurs before or during streaming. The categories differ only in the HTTP status code that accompanies the event:

The following table maps each runtime exception to its AG-UI SSE error code, HTTP status code, and message. Some exceptions share an SSE error code but return different messages, so they are listed as separate rows.

ConflictException and RetryableConflictException both use the SESSION_BUSY SSE error code (HTTP 409) but are distinguished by their message. The service returns RetryableConflictException (Session operation in progress, please retry) when a second operation reaches a session while the service is provisioning or tearing down that session. It is transient and retryable — retry with short exponential backoff, because AG-UI clients do not auto-retry it.

Example runtime error (agent failure):

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"AGENT_ERROR","message":"Agent execution failed"}

Example session-busy error (retryable conflict):

HTTP/1.1 409 Conflict
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"SESSION_BUSY","message":"Session operation in progress, please retry"}

OAuth authentication responses

OAuth-configured agents return authentication errors with standard HTTP status codes. The response includes a WWW-Authenticate header (per RFC 7235 ) for OAuth discovery through the GetRuntimeProtectedResourceMetadata API.

Example OAuth authentication error:

HTTP/1.1 401 Unauthorized
Content-Type: text/event-stream
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"UNAUTHORIZED","message":"Authentication required"}

SigV4-configured agents return HTTP 403 with an ACCESS_DENIED error and do not include WWW-Authenticate headers.