# 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. **Anmerkung** Sowohl HTTP (`/invocations`) als auch WebSocket (`/ws`) -Endpunkte können über Port 8080 auf demselben Container bereitgestellt werden, sodass eine Implementierung mit einem einzigen Agenten sowohl traditionelle API-Interaktionen als auch bidirektionales Streaming in Echtzeit unterstützt. Beispielcode finden Sie unter [Erste Schritte mit der AgentCore CLI](runtime-get-started-cli.md). **Topics** + [Anforderungen an Container](#container-requirements-http) + [Pfadanforderungen](#path-requirements-http) + [Antworten zur OAuth-Authentifizierung](#http-oauth-authentication-responses) ## Anforderungen an Container Ihr Agent muss als containerisierte Anwendung bereitgestellt werden, die die folgenden Spezifikationen erfüllt: + **Gastgeber:** `0.0.0.0` + **Port**: `8080` - Standardport für die HTTP-based Agentenkommunikation + **Plattform**: ARM64-Container — Aus Gründen der Kompatibilität mit der AgentCore Runtime-Umgebung erforderlich ## 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: + Direkte Benutzerinteraktionen und Konversationen + API-Integrationen mit externen Systemen + Stapelverarbeitung mehrerer Anfragen + Real-time Streaming-Antworten für lang andauernde Operationen **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: + Einfache Szenarien zur Beantwortung von Fragen + Deterministische Berechnungen + Schnelle Datensuche + Statusbestätigungen **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](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events). **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: + Real-time Konversationserlebnisse + Progressive Generierung von Inhalten + Long-running Berechnungen mit Zwischenergebnissen + Live-Datenfeeds und Updates **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: + Real-time Benutzeroberflächen für Konversationen + Interaktive Agentensitzungen mit sofortigem Feedback + Streaming-Datenverarbeitung mit bidirektionaler Kommunikation **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: + **Annahme der Verbindung**: Rufen Sie an`await websocket.accept()`, um die Verbindung herzustellen + **Nachrichtenempfang**: Support Text- oder Binärnachrichtentypen je nach Ihren Anwendungsanforderungen + **Nachrichtenverarbeitung**: Behandeln Sie eingehende Nachrichten gemäß der Geschäftslogik Ihres Agenten + **Senden von Antworten**: Senden Sie entsprechende Antworten mit `send_text()` oder `send_bytes()` + **Verbindungslebenszyklus**: Verwalten Sie den Verbindungsaufbau, die Wartung und die Beendigung #### 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: + Multi-modal Interaktionen mit Agenten + Uploads und Downloads von Dateien + Komprimierte Datenübertragung + Binäre Protokolldaten **Anforderungen an den Umgang** Für die Verarbeitung binärer Nachrichten ist Folgendes erforderlich: + Verwendung `receive_bytes()` und `send_bytes()` Methoden + Implementieren Sie eine geeignete binäre Datenverarbeitung + Beachten Sie die Beschränkungen der Nachrichtengröße #### Lebenszyklus einer Verbindung ##### Verbindungsaufbau 1. **HTTP-Handshake**: Der Client sendet eine WebSocket Upgrade-Anfrage 1. **Upgrade-Antwort**: Der Agent akzeptiert 101 Switching-Protokolle und gibt sie zurück 1. **WebSocket Aktiv**: Die bidirektionale Kommunikation beginnt 1. **Sitzungsbindung**: Verknüpfen Sie die Verbindung mit der Sitzungs-ID ##### Austausch von Nachrichten 1. **Kontinuierliche Schleife**: Implementieren Sie eine Nachrichtenabhörschleife 1. **Nachrichtenverarbeitung**: Behandeln Sie eingehende Nachrichten asynchron 1. **Generierung von Antworten**: Senden Sie entsprechende Antworten 1. **Fehlerbehandlung**: Ausnahmen und Verbindungsprobleme verwalten ### /ping — GET **Zweck** Überprüft, ob Ihr Agent betriebsbereit und bereit ist, Anfragen zu bearbeiten **Anwendungsfälle** Der `/ping` Endpunkt dient mehreren wichtigen Zwecken: + Serviceüberwachung zur Erkennung und Behebung von Problemen + Automatisierte Wiederherstellung über die AWS verwaltete Infrastruktur **Format der Antwort** Gibt einen Statuscode zurück, der den Zustand Ihres Agenten angibt: + **Content-Type** : `application/json` + **HTTP-Statuscode**: `200` für fehlerfreie Zustände, entsprechende Fehlercodes für fehlerhafte Zustände Wenn Ihr Agent Hintergrundaufgaben bearbeiten muss, können Sie dies mit dem `/ping` Status angeben. Wenn der Ping-Status lautet`HealthyBusy`, wird die Runtime-Sitzung als aktiv betrachtet. **Beispiel für ein Ping-Antwortformat** ``` { "status": "" } ``` **Status** (erforderlich) `Healthy`- Das System ist bereit, neue Arbeiten anzunehmen `HealthyBusy`- Das System ist betriebsbereit, aber derzeit mit asynchronen Aufgaben beschäftigt. Solange der Status lautet`HealthyBusy`, wird die Runtime-Sitzung als aktiv betrachtet und aktiv gehalten. **time\_of\_last\_update** (optional) Unix-Zeitstempel (in Sekunden), wann die letzte Änderung vorgenommen wurde. `status` Stellen Sie ihn nur bei einer tatsächlichen Statusänderung ein. Stellen Sie nicht `time_of_last_update` bei jedem Ping die aktuelle Uhrzeit ein. Ein Zeitstempel, der bei jedem Ping weitergeht, signalisiert eine kontinuierliche Statusänderung, wodurch verhindert wird, dass das Timeout für inaktive Sitzungen jemals ausgelöst wird. Die Sitzungen dauern dann an, bis Ihr Sitzungskontingent ausgeschöpft ist `MaxLifetime` und diese möglicherweise aufgebraucht sind. Wenn Sie das Feld weglassen, verfolgt die Plattform die Statusänderungen selbstständig. Wenn Sie das Bedrock AgentCore SDK verwenden, wird die Ping-Antwort für Sie abgewickelt. ## Antworten zur OAuth-Authentifizierung OAuth-configured Agenten folgen den [Authentifizierungsstandards RFC 6749 (OAuth 2.0)](https://datatracker.ietf.org/doc/html/rfc6749). Fehlt die Authentifizierung, gibt der Dienst eine Antwort 401 Unauthorized mit einem WWW-Authenticate Header (gemäß [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)) 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}" ``` **Anmerkung** SigV4-configured Agenten geben HTTP 403 mit einem `ACCESS_DENIED` Fehler zurück und schließen keine `WWW-Authenticate` Header ein.