HTTP protocol contract

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.

For example code, see Get started with the Amazon Bedrock AgentCore starter toolkit.

Container requirements

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

Path requirements

/invocations - POST

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:

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)

Purpose

Provides complete responses for requests that can be processed quickly

Use cases

JSON responses are ideal for:

Content-Type: application/json

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

SSE response (streaming)

Server-sent events (SSE) let you deliver real-time streaming responses. For more information, see the Server-sent events specification.

Purpose

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

Use cases

SSE responses are ideal for:

Content-Type: text/event-stream

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

/ping - GET

Purpose

Verifies that your agent is operational and ready to handle requests

Use cases

The /ping endpoint serves several key purposes:

Response format

Returns a status code indicating your agent's health:

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.

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