# Understand the AgentCore Runtime service contract
<a name="runtime-service-contract"></a>

The AgentCore Runtime service contract defines the standardized communication protocol that your agent application must implement to integrate with the Amazon Bedrock agent hosting infrastructure. This contract ensures seamless communication between your custom agent code and AWS's managed hosting environment.

**Topics**
+ [

## Supported protocols
](#supported-protocols)
+ [

## Compare supported protocols
](#protocol-comparison)
+ [

# HTTP protocol contract
](runtime-http-protocol-contract.md)
+ [

# MCP protocol contract
](runtime-mcp-protocol-contract.md)
+ [

# A2A protocol contract
](runtime-a2a-protocol-contract.md)
+ [

# AGUI protocol contract
](runtime-agui-protocol-contract.md)

## Supported protocols
<a name="supported-protocols"></a>

The AgentCore Runtime service contract supports the following communication protocols:
+  [HTTP](runtime-http-protocol-contract.md) : Direct REST API endpoints for traditional request/response patterns
+  [MCP](runtime-mcp-protocol-contract.md) : Model Context Protocol for tools and agent servers
+  [A2A](runtime-a2a-protocol-contract.md) : Agent-to-Agent protocol for multi-agent communication and discovery
+  [AGUI](runtime-agui-protocol-contract.md) : Agent-to-User Interface protocol for interactive agent experiences with UI rendering

## Compare supported protocols
<a name="protocol-comparison"></a>

Compare the HTTP, MCP, A2A, and AGUI protocols to understand the differences and use cases.


| Feature | HTTP Protocol | MCP Protocol | A2A Protocol | AGUI Protocol | 
| --- | --- | --- | --- | --- | 
|   **Port**   |  8080  |  8000  |  9000  |  8080  | 
|   **Mount Path**   |  /invocations (HTTP), /ws (WebSocket)  |  /mcp  |  / (root)  |  /invocations (SSE), /ws (WebSocket)  | 
|   **Message Format**   |  REST JSON/SSE, WebSocket (text/binary)  |  JSON-RPC  |  JSON-RPC 2.0  |  Event streams (SSE/WebSocket)  | 
|   **Discovery**   |  N/A  |  Tool listing  |  Agent Cards  |  N/A  | 
|   **Authentication**   |  SigV4, OAuth 2.0; WebSocket supports SigV4 by headers and query params  |  SigV4, OAuth 2.0  |  SigV4, OAuth 2.0  |  SigV4, OAuth 2.0  | 
|   **Use Case**   |  Direct API calls, real-time streaming  |  Tool servers  |  Agent-to-agent communication  |  Interactive UI experiences  | 

# HTTP protocol contract
<a name="runtime-http-protocol-contract"></a>

Understand the requirements for implementing the HTTP protocol in your agent application. Use the HTTP protocol to create direct REST API endpoints for traditional request/response patterns and WebSocket endpoints for real-time bidirectional streaming connections.

**Note**  
Both HTTP ( `/invocations` ) and WebSocket ( `/ws` ) endpoints can be deployed on the same container using port 8080, allowing a single agent implementation to support both traditional API interactions and real-time bidirectional streaming.

For example code, see [Get started with the AgentCore CLI](runtime-get-started-cli.md).

**Topics**
+ [

## Container requirements
](#container-requirements-http)
+ [

## Path requirements
](#path-requirements-http)
+ [

## OAuth Authentication Responses
](#http-oauth-authentication-responses)

## Container requirements
<a name="container-requirements-http"></a>

Your agent must be deployed as a containerized application meeting these specifications:
+  **Host** : `0.0.0.0` 
+  **Port** : `8080` - Standard port for HTTP-based agent communication
+  **Platform** : ARM64 container - Required for compatibility with the AgentCore Runtime environment

## Path requirements
<a name="path-requirements-http"></a>

### /invocations - POST
<a name="invocations-endpoint"></a>

This is the primary agent interaction endpoint with JSON input and JSON/SSE output.

 **Purpose** 

Receives incoming requests from users or applications and processes them through your agent’s business logic

 **Use cases** 

The `/invocations` endpoint serves several key purposes:
+ Direct user interactions and conversations
+ API integrations with external systems
+ Batch processing of multiple requests
+ Real-time streaming responses for long-running operations

 **Example Request format** 

```
Content-Type: application/json

{
  "prompt": "What's the weather today?"
}
```

 **Response formats** 

Your agent can respond using either of the following formats depending on the use case:

#### JSON response (non-streaming)
<a name="json-response"></a>

 **Purpose** 

Provides complete responses for requests that can be processed quickly

 **Use cases** 

JSON responses are ideal for:
+ Simple question-answering scenarios
+ Deterministic computations
+ Quick data lookups
+ Status confirmations

 **Example JSON response format** 

```
Content-Type: application/json

{
  "response": "Your agent's response here",
  "status": "success"
}
```

#### SSE response (streaming)
<a name="sse-response"></a>

Server-sent events (SSE) let you deliver real-time streaming responses. For more information, see the [Server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) specification.

 **Purpose** 

Enables incremental response delivery for long-running operations and improved user experience

 **Use cases** 

SSE responses are ideal for:
+ Real-time conversational experiences
+ Progressive content generation
+ Long-running computations with intermediate results
+ Live data feeds and updates

 **Example SSE response format** 

```
Content-Type: text/event-stream

data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}
```

### /ws - WebSocket (Optional)
<a name="ws-endpoint"></a>

This is the primary WebSocket connection endpoint for real-time bidirectional communication.

 **Purpose** 

Accepts WebSocket upgrade requests and maintains persistent connections for streaming agent interactions

 **Use cases** 

The `/ws` endpoint serves several key purposes:
+ Real-time conversational interfaces
+ Interactive agent sessions with immediate feedback
+ Streaming data processing with bidirectional communication

 **Connection establishment** 

WebSocket connections begin with an HTTP upgrade request:

 **Example HTTP Upgrade Request** 

```
GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid
```

 **Example WebSocket Upgrade Response** 

```
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
```

 **Message handling requirements** 

Your WebSocket endpoint must handle:
+  **Connection acceptance** : Call `await websocket.accept()` to establish the connection
+  **Message reception** : Support text or binary message types based on your application requirement
+  **Message processing** : Handle incoming messages according to your agent’s business logic
+  **Response sending** : Send appropriate responses using `send_text()` or `send_bytes()` 
+  **Connection lifecycle** : Manage connection establishment, maintenance, and termination

#### Message formats
<a name="websocket-message-formats"></a>

##### Text Messages
<a name="websocket-text-messages"></a>

##### JSON Format (Recommended)
<a name="websocket-json-format"></a>

 **Purpose** 

Structured data exchange for agent interactions

 **Example message** 

```
{
  "prompt": "Hello, can you help me with this question?",
  "session_id": "session-uuid",
  "message_type": "user_message"
}
```

 **Example response** 

```
{
  "response": "I'd be happy to help you with your question!",
  "session_id": "session-uuid",
  "message_type": "agent_response"
}
```

##### Plain Text Format
<a name="websocket-plain-text-format"></a>

 **Purpose** 

Simple text-based communication

 **Example** 

```
Hello, can you help me with this question?
```

##### Binary Messages
<a name="websocket-binary-messages"></a>

 **Purpose** 

Support for non-text data such as images, audio, or other binary formats

 **Use cases** 

Binary messages support several scenarios:
+ Multi-modal agent interactions
+ File uploads and downloads
+ Compressed data transmission
+ Binary protocol data

 **Handling requirements** 

Binary message handling requires:
+ Use `receive_bytes()` and `send_bytes()` methods
+ Implement appropriate binary data processing
+ Consider message size limitations

#### Connection lifecycle
<a name="websocket-connection-lifecycle"></a>

##### Connection Establishment
<a name="websocket-connection-establishment"></a>

1.  **HTTP Handshake** : Client sends WebSocket upgrade request

1.  **Upgrade Response** : Agent accepts and returns 101 Switching Protocols

1.  **WebSocket Active** : Bidirectional communication begins

1.  **Session Binding** : Associate connection with session identifier

##### Message Exchange
<a name="websocket-message-exchange"></a>

1.  **Continuous Loop** : Implement message listening loop

1.  **Message Processing** : Handle incoming messages asynchronously

1.  **Response Generation** : Send appropriate responses

1.  **Error Handling** : Manage exceptions and connection issues

### /ping - GET
<a name="ping-endpoint"></a>

 **Purpose** 

Verifies that your agent is operational and ready to handle requests

 **Use cases** 

The `/ping` endpoint serves several key purposes:
+ Service monitoring to detect and remediate issues
+ Automated recovery through AWS's managed infrastructure

 **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

If your agent needs to process background tasks, you can indicate it with the `/ping` status. If the ping status is `HealthyBusy` , the runtime session is considered active.

 **Example Ping response format** 

```
{
  "status": "<status_value>",
  "time_of_last_update": <unix_timestamp>
}
```

 **status**   
 `Healthy` - System is ready to accept new work  
 `HealthyBusy` - System is operational but currently busy with async tasks

 **time\$1of\$1last\$1update**   
Used to determine how long the system has been in its current state

## OAuth Authentication Responses
<a name="http-oauth-authentication-responses"></a>

OAuth-configured agents follow [RFC 6749 (OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749) authentication standards. When authentication is missing, the service returns a 401 Unauthorized response with a WWW-Authenticate header (per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) ), enabling clients to discover the authorization server endpoints through the GetRuntimeProtectedResourceMetadata API.

### 401 Unauthorized
<a name="http-401-unauthorized"></a>

Returned when Authorization header is missing.

Includes WWW-Authenticate header:

```
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```

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

# MCP protocol contract
<a name="runtime-mcp-protocol-contract"></a>

Understand the requirements for implementing the Model Context Protocol (MCP) so that agents can call tools and agent servers.

For example code, see [Deploy MCP servers in AgentCore Runtime](runtime-mcp.md).

**Topics**
+ [

## Protocol implementation requirements
](#protocol-implementation-requirements)
+ [

## Container requirements
](#container-requirements-mcp)
+ [

## Path requirements
](#path-requirements-mcp)
+ [

## OAuth Authentication Responses
](#mcp-oauth-authentication-responses)

## Protocol implementation requirements
<a name="protocol-implementation-requirements"></a>

Your MCP server must implement these specific protocol requirements:
+  **Transport** : Streamable-http transport is required. By default, use stateless mode ( `stateless_http=True` ) for compatibility with AWS's session management and load balancing.
+  **Session Management** : Platform automatically adds `Mcp-Session-Id` header for session isolation. In stateless mode, servers must support stateless operation so as to not reject platform generated `Mcp-Session-Id` header.

**Tip**  
Amazon Bedrock AgentCore also supports stateful MCP servers ( `stateless_http=False` ) that enable capabilities such as elicitation (multi-turn user interactions) and sampling (LLM-generated content). Stateful mode is required when your MCP server needs to maintain session context across multiple requests within the same tool invocation. For more information and examples, see [Stateful MCP server features](mcp-stateful-features.md).

### MCP session management and microVM stickiness
<a name="mcp-session-management"></a>

The Model Context Protocol (MCP) uses the `Mcp-Session-Id` header to manage session state and route requests. For the MCP specification, see [MCP Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).

 **MicroVM Stickiness** : Amazon Bedrock AgentCore uses the `Mcp-Session-Id` header to route requests to the same microVM instance. Clients must capture the `Mcp-Session-Id` returned in the response and include it in all subsequent requests to ensure session affinity. Without a consistent session ID, each request may be routed to a new microVM, which may result in additional latency due to cold starts.

 **Stateless MCP** ( `stateless_http=True` ):
+ Platform generates the `Mcp-Session-Id` and includes it in the request to your MCP server.
+ Your MCP server must accept the platform-provided session ID (do not reject it).
+ Platform returns the same `Mcp-Session-Id` to the client in the response.
+ Client must include this session ID in all subsequent requests for microVM affinity.

 **Stateful MCP** ( `stateless_http=False` ):
+ Client sends the initialize request without an `Mcp-Session-Id` header.
+ Platform returns `Mcp-Session-Id` in the response.
+ Client must include this `Mcp-Session-Id` in all subsequent requests for both session state and microVM affinity.

For more details on stateful MCP session management, see the [MCP session management specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#session-management).

**Note**  
In both modes, Amazon Bedrock AgentCore always returns an `Mcp-Session-Id` header to clients. Always capture and reuse this header for optimal performance.

## Container requirements
<a name="container-requirements-mcp"></a>

Your MCP server must be deployed as a containerized application meeting these specifications:
+  **Host** : `0.0.0.0` 
+  **Port** : `8000` - Standard port for MCP server communication (different from HTTP protocol)
+  **Platform** : ARM64 container - Required for compatibility with AWS Amazon Bedrock AgentCore runtime environment

## Path requirements
<a name="path-requirements-mcp"></a>

### /mcp - POST
<a name="mcp-endpoint"></a>

 **Purpose** 

Receives MCP RPC messages and processes them through your agent’s tool capabilities, complete pass-through of [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) API payload with standard MCP RPC messages

 **Response format** 

JSON-RPC based request/response format, supporting both `application/json` and `text/event-stream` as response content-types

 **Use cases** 

The `/mcp` endpoint serves several key purposes:
+ Tool invocation and management
+ Agent capability discovery
+ Resource access and manipulation
+ Multi-step agent workflows

## OAuth Authentication Responses
<a name="mcp-oauth-authentication-responses"></a>

OAuth-configured agents follow [RFC 6749 (OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749) authentication standards. When authentication is missing, the service returns a 401 Unauthorized response with a WWW-Authenticate header (per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) ), enabling clients to discover the authorization server endpoints through the GetRuntimeProtectedResourceMetadata API.

### 401 Unauthorized
<a name="mcp-401-unauthorized"></a>

Returned when the Authorization header is missing or empty.

Response includes WWW-Authenticate header:

```
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```

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

# A2A protocol contract
<a name="runtime-a2a-protocol-contract"></a>

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

For example code, see [Deploy A2A servers in AgentCore Runtime](runtime-a2a.md).

**Topics**
+ [

## Protocol implementation requirements
](#protocol-implementation-requirements)
+ [

## Container requirements
](#container-requirements)
+ [

## Path requirements
](#path-requirements)
+ [

## Authentication requirements
](#authentication-requirements)
+ [

## Error handling
](#error-handling)
+ [

## OAuth Authentication Responses
](#a2a-oauth-authentication-responses)

## Protocol implementation requirements
<a name="protocol-implementation-requirements"></a>

Your A2A server must implement these specific protocol requirements:
+  **Transport** : [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over HTTP - Enables standardized agent-to-agent communication
+  **Session Management** : Platform automatically adds `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header for session isolation
+  **Agent Discovery** : Must provide Agent Card at `/.well-known/agent-card.json` endpoint

## Container requirements
<a name="container-requirements"></a>

Your A2A server must be deployed as a containerized application meeting these specifications:
+  **Host** : `0.0.0.0` 
+  **Port** : `9000` - Standard port for A2A server communication (different from HTTP and MCP protocols)
+  **Platform** : ARM64 container - Required for compatibility with AWS Amazon Bedrock AgentCore runtime environment

## Path requirements
<a name="path-requirements"></a>

### / - POST
<a name="root-post-endpoint"></a>

#### Purpose
<a name="root-endpoint-purpose"></a>

Receives JSON-RPC 2.0 messages and processes them through your agent’s capabilities, complete pass-through of [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) API payload with A2A protocol messages

#### Use cases
<a name="root-endpoint-use-cases"></a>

The root endpoint serves several key purposes:
+ Agent-to-agent communication and collaboration
+ Multi-step agent workflows and task delegation
+ Real-time conversational experiences between agents
+ Tool invocation and capability sharing

#### Request format
<a name="root-endpoint-request-format"></a>

A2A servers expect JSON-RPC 2.0 formatted requests:

```
Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Your message content here"
        }
      ],
      "messageId": "unique-message-id"
    }
  }
}
```

#### Response format
<a name="root-endpoint-response-format"></a>

A2A servers respond with JSON-RPC 2.0 formatted responses containing tasks and artifacts:

```
Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "artifacts": [
      {
        "artifactId": "unique-artifact-id",
        "name": "agent_response",
        "parts": [
          {
            "kind": "text",
            "text": "Agent response content"
          }
        ]
      }
    ]
  }
}
```

### /.well-known/agent-card.json - GET
<a name="agent-card-endpoint"></a>

#### Purpose
<a name="agent-card-purpose"></a>

Provides Agent Card metadata for agent discovery and capability advertisement

#### Use cases
<a name="agent-card-use-cases"></a>

The Agent Card endpoint serves several key purposes:
+ Agent discovery in multi-agent systems
+ Capability and skill advertisement
+ Authentication requirement specification
+ Service endpoint configuration

#### Response format
<a name="agent-card-response-format"></a>

Returns JSON metadata describing the agent’s identity and capabilities:

```
Content-Type: application/json
{
  "name": "Agent Name",
  "description": "Agent description and purpose",
  "version": "1.0.0",
  "url": "https://bedrock-agentcore.region.amazonaws.com/runtimes/agent-arn/invocations/",
  "protocolVersion": "0.3.0",
  "preferredTransport": "JSONRPC",
  "capabilities": {
    "streaming": true
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "skill-id",
      "name": "Skill Name",
      "description": "Skill description and capabilities",
      "tags": []
    }
  ]
}
```

### /ping - GET
<a name="ping-endpoint"></a>

#### Purpose
<a name="ping-purpose"></a>

Verifies that your A2A server is operational and ready to handle requests

#### Response format
<a name="ping-response-format"></a>

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",
  "time_of_last_update": 1640995200
}
```

## Authentication requirements
<a name="authentication-requirements"></a>

A2A servers support multiple authentication mechanisms:

### OAuth 2.0 Bearer Tokens
<a name="oauth-bearer-tokens"></a>

For A2A client authentication, include the Bearer token in request headers:

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

### SigV4 Authentication
<a name="sigv4-authentication"></a>

Standard AWS SigV4 authentication is also supported for programmatic access.

## Error handling
<a name="error-handling"></a>

A2A servers return errors as standard JSON-RPC 2.0 error responses with HTTP 200 status codes to maintain protocol compliance:


| JSON-RPC Error Code | Runtime Exception | HTTP Error Code | JSON-RPC Error Message | 
| --- | --- | --- | --- | 
|  -32501  |  ResourceNotFoundException  |  404  |  Resource not found - Requested resource does not exist  | 
|  -32052  |  ValidationException  |  400  |  Validation error - Invalid request data  | 
|  -32053  |  ThrottlingException  |  429  |  Rate limit exceeded - Too many requests  | 
|  -32054  |  ResourceConflictException  |  409  |  Resource conflict - Resource already exists  | 
|  -32055  |  RuntimeClientError  |  424  |  Runtime client error - Please check your CloudWatch logs for more information  | 

Example error response:

```
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32052,
    "message": "Validation error - Invalid request data"
  }
}
```

## OAuth Authentication Responses
<a name="a2a-oauth-authentication-responses"></a>

OAuth-configured agents follow [RFC 6749 (OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749) authentication standards. When authentication is missing, the service returns a 401 Unauthorized response with a WWW-Authenticate header (per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) ), enabling clients to discover the authorization server endpoints through the GetRuntimeProtectedResourceMetadata API.

### 401 Unauthorized - Missing Authentication
<a name="a2a-401-unauthorized"></a>

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```

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

# AGUI protocol contract
<a name="runtime-agui-protocol-contract"></a>

The AGUI 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 AGUI agent must implement.

For example code, see [Deploy AGUI servers in AgentCore Runtime](runtime-agui.md).

**Topics**
+ [

## Protocol implementation requirements
](#agui-protocol-implementation-requirements)
+ [

## Container requirements
](#agui-container-requirements)
+ [

## Path requirements
](#agui-path-requirements)
+ [

## Authentication requirements
](#agui-authentication-requirements)
+ [

## Error handling
](#agui-error-handling)
+ [

## OAuth authentication responses
](#agui-oauth-authentication-responses)

## Protocol implementation requirements
<a name="agui-protocol-implementation-requirements"></a>

Your AGUI 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
<a name="agui-container-requirements"></a>

Your AGUI agent must be deployed as a containerized application meeting these specifications:
+  **Host** : `0.0.0.0` 
+  **Port** : `8080` - Standard port for AGUI agent communication (same as HTTP protocol)
+  **Platform** : ARM64 container - Required for compatibility with AWS Amazon Bedrock AgentCore runtime environment

## Path requirements
<a name="agui-path-requirements"></a>

### /invocations - POST
<a name="agui-invocations-endpoint"></a>

#### Purpose
<a name="agui-invocations-purpose"></a>

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

#### Use cases
<a name="agui-invocations-use-cases"></a>

The invocations endpoint serves several key purposes:
+ Streaming chat responses
+ Agent status and thinking steps
+ Tool calls and results

#### Request format
<a name="agui-invocations-request-format"></a>

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

AGUI-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 [AGUI Types](https://docs.ag-ui.com/sdk/js/core/types).

#### Response format
<a name="agui-invocations-response-format"></a>

AGUI 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
<a name="agui-ws-endpoint"></a>

#### Purpose
<a name="agui-ws-purpose"></a>

Provides bidirectional real-time communication between clients and agents

#### Use cases
<a name="agui-ws-use-cases"></a>

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
<a name="agui-ping-endpoint"></a>

#### Purpose
<a name="agui-ping-purpose"></a>

Verifies that your AGUI agent is operational and ready to handle requests

#### Response format
<a name="agui-ping-response-format"></a>

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",
  "time_of_last_update": 1640995200
}
```

## Authentication requirements
<a name="agui-authentication-requirements"></a>

AGUI agents support multiple authentication mechanisms:

### OAuth 2.0 Bearer Tokens
<a name="agui-oauth-bearer-tokens"></a>

For AGUI client authentication, include the Bearer token in request headers:

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

### SigV4 Authentication
<a name="agui-sigv4-authentication"></a>

Standard AWS SigV4 authentication is also supported for programmatic access.

## Error handling
<a name="agui-error-handling"></a>

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.


| AGUI 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
<a name="agui-oauth-authentication-responses"></a>

OAuth-configured agents return authentication errors with standard HTTP status codes. The response includes a `WWW-Authenticate` header (per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) ) 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.