View a markdown version of this page

AG-UI protocol contract - Amazon Bedrock AgentCore
Protocol implementation requirementsContainer requirementsPath requirementsAuthentication requirementsError handlingOAuth authentication responses

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:

  • Transport : Server-Sent Events (SSE) or WebSocket - SSE provides unidirectional streaming from server to client, while WebSocket enables bidirectional real-time communication

  • Session Management : Platform automatically adds X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header for session isolation

Container requirements

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

  • Host : 0.0.0.0

  • Port : 8080 - Standard port for AG-UI agent communication (same as HTTP protocol)

  • Platform : ARM64 container - Required for compatibility with AWS Amazon Bedrock AgentCore runtime environment

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:

  • Streaming chat responses

  • Agent status and thinking steps

  • Tool calls and results

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:

  • Real-time conversational interfaces

  • Interactive agent sessions with user interrupts

  • Multi-turn conversations with persistent connections

/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:

  • Content-Type : application/json

  • HTTP Status Code : 200 for healthy, appropriate error codes for unhealthy states

{
  "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.

Warning

Do not set time_of_last_update to the current time on every ping. A timestamp that advances on every ping signals a continuous status change, which prevents the idle session timeout from ever firing — sessions then persist until MaxLifetime and can exhaust your session quota. If you omit the field, the platform tracks status changes on its own. If you use the Bedrock AgentCore SDK, the ping response is handled for you.

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

Errors are classified into two categories based on when they occur:

  • Connection-level errors : Occur before the request reaches your container (authentication, validation, throttling). These return standard HTTP status codes.

  • Runtime errors : Occur during agent execution after the stream has started. These surface as RUN_ERROR events in the SSE stream rather than HTTP status codes.

AG-UI Error Code HTTP Status Description

UNAUTHORIZED

401

Authentication required or invalid credentials

ACCESS_DENIED

403

Insufficient permissions for requested operation

VALIDATION_ERROR

400

Invalid request data or parameters

RATE_LIMIT_EXCEEDED

429

Too many requests from client

AGENT_ERROR

200

Agent code failed during execution – check your CloudWatch logs

Example runtime error (agent failure):

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

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

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: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

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.