Contratto di protocollo HTTP

Comprendi i requisiti per l'implementazione del protocollo HTTP nella tua applicazione agente. Utilizza il protocollo HTTP per creare endpoint API REST diretti per request/response pattern ed WebSocket endpoint tradizionali per connessioni di streaming bidirezionali in tempo reale.

Nota

Entrambi gli endpoint HTTP (/invocations) e WebSocket (/ws) possono essere implementati sullo stesso contenitore utilizzando la porta 8080, consentendo l'implementazione di un singolo agente per supportare sia le interazioni API tradizionali che lo streaming bidirezionale in tempo reale.

Per esempio di codice, consulta Guida introduttiva alla AgentCore CLI.

Requisiti del contenitore

L'agente deve essere distribuito come applicazione containerizzata che soddisfi queste specifiche:

• Ospite: 0.0.0.0

• Porta: 8080 - Porta standard per la comunicazione tra HTTP-based agenti

• Piattaforma: contenitore ARM64 - Necessario per la compatibilità con l'ambiente AgentCore Runtime

Requisiti del percorso

/invocations - POST

Questo è l'endpoint principale di interazione tra agenti con input e output JSON. JSON/SSE

Scopo

Riceve le richieste in entrata da utenti o applicazioni e le elabora secondo la logica aziendale dell'agente

Casi d'uso

L'/invocationsendpoint serve a diversi scopi chiave:

• Interazioni e conversazioni dirette con gli utenti

• Integrazioni API con sistemi esterni

• Elaborazione in batch di più richieste

• Real-time risposte in streaming per operazioni di lunga durata

Esempio di formato di richiesta

Content-Type: application/json

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

Formati di risposta

Il tuo agente può rispondere utilizzando uno dei seguenti formati a seconda del caso d'uso:

Risposta JSON (non in streaming)

Scopo

Fornisce risposte complete per le richieste che possono essere elaborate rapidamente

Casi d'uso

Le risposte JSON sono ideali per:

• Scenari semplici in cui è necessario rispondere a domande

• Calcoli deterministici

• Ricerche rapide dei dati

• Conferme dello stato

Esempio di formato di risposta JSON

Content-Type: application/json

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

Risposta SSE (streaming)

Server-sent gli eventi (SSE) ti consentono di fornire risposte in streaming in tempo reale. Per ulteriori informazioni, consulta le specifiche degli Server-sent eventi.

Scopo

Consente l'erogazione di risposte incrementali per operazioni di lunga durata e una migliore esperienza utente

Casi d'uso

Le risposte SSE sono ideali per:

• Real-time esperienze conversazionali

• Generazione progressiva di contenuti

• Long-running calcoli con risultati intermedi

• Feed e aggiornamenti di dati in tempo reale

Esempio di formato di risposta SSE

Content-Type: text/event-stream

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

/ws - WebSocket (Facoltativo)

Questo è l'endpoint di WebSocket connessione principale per la comunicazione bidirezionale in tempo reale.

Scopo

Accetta richieste di WebSocket aggiornamento e mantiene connessioni persistenti per le interazioni con gli agenti di streaming

Casi d'uso

L'/wsendpoint serve a diversi scopi chiave:

• Real-time interfacce conversazionali

• Sessioni interattive per gli agenti con feedback immediato

• Elaborazione di dati in streaming con comunicazione bidirezionale

Stabilimento della connessione

WebSocket le connessioni iniziano con una richiesta di aggiornamento HTTP:

Esempio di richiesta di aggiornamento HTTP

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

Esempio di risposta all' WebSocket aggiornamento

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

Requisiti di gestione dei messaggi

L' WebSocket endpoint deve gestire:

• Accettazione della connessione: chiamata await websocket.accept() per stabilire la connessione

• Ricezione dei messaggi: Supporta i tipi di messaggi di testo o binari in base ai requisiti dell'applicazione

• Elaborazione dei messaggi: gestisci i messaggi in arrivo in base alla logica aziendale del tuo agente

• Invio di risposte: invia le risposte appropriate utilizzando send_text() o send_bytes()

• Ciclo di vita della connessione: gestisci la creazione, la manutenzione e la cessazione della connessione

Formati dei messaggi

Messaggi di testo

Formato JSON (consigliato)

Scopo

Scambio strutturato di dati per le interazioni con gli agenti

Messaggio di esempio

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

Esempio di risposta

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

Formato di testo semplice

Scopo

Comunicazione semplice basata su testo

Esempio

Hello, can you help me with this question?

Messaggi binari

Scopo

Support per dati non testuali come immagini, audio o altri formati binari

Casi d'uso

I messaggi binari supportano diversi scenari:

• Multi-modal interazioni tra agenti

• Caricamenti e download di file

• Trasmissione di dati compressi

• Dati di protocollo binario

Requisiti di gestione

La gestione dei messaggi binari richiede:

• Uso receive_bytes() e send_bytes() metodi

• Implementare un'elaborazione dei dati binari appropriata

• Prendi in considerazione i limiti delle dimensioni dei messaggi

Ciclo di vita della connessione

Stabilimento della connessione

1. HTTP Handshake: il client invia una richiesta di WebSocket aggiornamento

2. Risposta all'aggiornamento: l'agente accetta e restituisce 101 Switching Protocols

3. WebSocket Attivo: inizia la comunicazione bidirezionale

4. Associazione di sessione: associa la connessione all'identificatore di sessione

Scambio di messaggi

1. Continuous Loop: implementa il ciclo di ascolto dei messaggi

2. Elaborazione dei messaggi: gestisci i messaggi in arrivo in modo asincrono

3. Generazione di risposte: invia risposte appropriate

4. Gestione degli errori: gestione delle eccezioni e dei problemi di connessione

/ping - GET

Scopo

Verifica che l'agente sia operativo e pronto a gestire le richieste

Casi d'uso

L'/pingendpoint serve a diversi scopi chiave:

• Monitoraggio del servizio per rilevare e risolvere i problemi

• Ripristino automatizzato tramite l' AWS infrastruttura gestita

Formato di risposta

Restituisce un codice di stato che indica lo stato di salute del tuo agente:

• Content-Type : application/json

• Codice di stato HTTP: 200 per codici di errore corretti e appropriati per stati non integri

Se il tuo agente deve elaborare attività in background, puoi indicarlo con lo /ping stato. Se lo stato del ping èHealthyBusy, la sessione di runtime è considerata attiva.

Esempio di formato di risposta Ping

{
  "status": "<status_value>"
}

status (obbligatorio)

Healthy- Il sistema è pronto ad accettare nuovi lavori

HealthyBusy- Il sistema è operativo ma attualmente è occupato con attività asincrone. Finché lo stato èHealthyBusy, la sessione di runtime è considerata attiva e viene mantenuta attiva.

time_of_last_update (opzionale)

Timestamp Unix (in secondi) dell'ultima modifica. status Impostalo solo su una modifica di stato effettiva.

avvertimento

Non impostate time_of_last_update l'ora corrente a ogni ping. Un timestamp che avanza a ogni ping segnala un cambiamento continuo dello stato, che impedisce che il timeout della sessione inattiva si verifichi. Le sessioni quindi persistono fino a MaxLifetime esaurimento della quota di sessione. Se ometti il campo, la piattaforma tiene traccia delle modifiche allo stato da sola. Se utilizzi Bedrock AgentCore SDK, la risposta al ping viene gestita automaticamente.

Risposte di autenticazione OAuth

OAuth-configured gli agenti seguono gli standard di autenticazione RFC 6749 (OAuth 2.0). Quando manca l'autenticazione, il servizio restituisce una risposta 401 Unauthorized con un' WWW-Authenticate intestazione (secondo RFC 7235), che consente ai client di scoprire gli endpoint del server di autorizzazione tramite l'API. GetRuntimeProtectedResourceMetadata

401 - Autorizzazione negata

Restituito quando manca l'intestazione di autorizzazione.

Include l' WWW-Authenticate intestazione:

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

Nota

SigV4-configured gli agenti restituiscono HTTP 403 con un ACCESS_DENIED errore e non includono WWW-Authenticate le intestazioni.