HTTP-Protokollvertrag

Machen Sie sich mit den Anforderungen für die Implementierung des HTTP-Protokolls in Ihrer Agentenanwendung vertraut. Verwenden Sie das HTTP-Protokoll, um direkte REST-API-Endpunkte für herkömmliche request/response Muster und WebSocket Endpunkte für bidirektionale Streaming-Verbindungen in Echtzeit zu erstellen.

Beispielcode finden Sie unter Erste Schritte mit der AgentCore CLI.

Anforderungen an Container

Ihr Agent muss als containerisierte Anwendung bereitgestellt werden, die die folgenden Spezifikationen erfüllt:

Pfadanforderungen

/invocations — POST

Dies ist der primäre Endpunkt für Agenteninteraktionen mit JSON-Eingabe und -Ausgabe. JSON/SSE

Zweck

Empfängt eingehende Anfragen von Benutzern oder Anwendungen und verarbeitet sie mithilfe der Geschäftslogik Ihres Agenten

Anwendungsfälle

Der /invocations Endpunkt dient mehreren wichtigen Zwecken:

Beispiel für ein Anforderungsformat

Content-Type: application/json

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

Antwortformate

Ihr Agent kann je nach Anwendungsfall mit einem der folgenden Formate antworten:

JSON-Antwort (kein Streaming)

Zweck

Bietet vollständige Antworten auf Anfragen, die schnell bearbeitet werden können

Anwendungsfälle

JSON-Antworten sind ideal für:

Beispiel für ein JSON-Antwortformat

Content-Type: application/json

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

SSE-Antwort (Streaming)

Server-sent Mit Events (SSE) können Sie Streaming-Antworten in Echtzeit bereitstellen. Weitere Informationen finden Sie in der Server-sent Ereignisspezifikation.

Zweck

Ermöglicht die inkrementelle Bereitstellung von Antworten bei lang andauernden Vorgängen und verbessert die Benutzererfahrung

Anwendungsfälle

SSE-Antworten sind ideal für:

Beispiel für ein SSE-Antwortformat

Content-Type: text/event-stream

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

/ws — WebSocket (optional)

Dies ist der primäre WebSocket Verbindungsendpunkt für bidirektionale Echtzeitkommunikation.

Zweck

Akzeptiert WebSocket Upgrade-Anfragen und unterhält persistente Verbindungen für Streaming-Agent-Interaktionen

Anwendungsfälle

Der /ws Endpunkt dient mehreren wichtigen Zwecken:

Verbindungsaufbau

WebSocket Verbindungen beginnen mit einer HTTP-Upgrade-Anfrage:

Beispiel für eine HTTP-Upgrade-Anfrage

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

Beispiel für eine WebSocket Upgrade-Antwort

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

Anforderungen an die Nachrichtenverarbeitung

Ihr WebSocket Endpunkt muss Folgendes verarbeiten:

Nachrichtenformate

Textnachrichten

JSON-Format (empfohlen)

Zweck

Strukturierter Datenaustausch für Agenteninteraktionen

Beispiel für eine Nachricht

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

Beispielantwort

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

Nur-Text-Format

Zweck

Einfache textbasierte Kommunikation

Beispiel

Hello, can you help me with this question?

Binäre Nachrichten

Zweck

Support für Nicht-Textdaten wie Bilder, Audio oder andere Binärformate

Anwendungsfälle

Binäre Nachrichten unterstützen mehrere Szenarien:

Anforderungen an den Umgang

Für die Verarbeitung binärer Nachrichten ist Folgendes erforderlich:

Lebenszyklus einer Verbindung

Verbindungsaufbau

Austausch von Nachrichten

/ping — GET

Zweck

Überprüft, ob Ihr Agent betriebsbereit und bereit ist, Anfragen zu bearbeiten

Anwendungsfälle

Der /ping Endpunkt dient mehreren wichtigen Zwecken:

Format der Antwort

Gibt einen Statuscode zurück, der den Zustand Ihres Agenten angibt:

Wenn Ihr Agent Hintergrundaufgaben bearbeiten muss, können Sie dies mit dem /ping Status angeben. Wenn der Ping-Status lautetHealthyBusy, wird die Runtime-Sitzung als aktiv betrachtet.

Beispiel für ein Ping-Antwortformat

{
  "status": "<status_value>"
}

Antworten zur OAuth-Authentifizierung

OAuth-configured Agenten folgen den Authentifizierungsstandards RFC 6749 (OAuth 2.0). Fehlt die Authentifizierung, gibt der Dienst eine Antwort 401 Unauthorized mit einem WWW-Authenticate Header (gemäß RFC 7235) zurück, sodass Clients die Endpunkte des Autorisierungsservers über die API ermitteln können. GetRuntimeProtectedResourceMetadata

401 Nicht autorisiert

Wird zurückgegeben, wenn der Authorization-Header fehlt.

Beinhaltet den 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}"