Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Contratto di protocollo HTTP

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

Per esempio di codice, vedi Guida introduttiva all'interfaccia della riga di comando. AgentCore

Requisiti del contenitore

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

Requisiti del percorso

/invocazioni - POST

Questo è il principale endpoint di interazione dell'agente con input e output JSON. JSON/SSE

Scopo

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

Casi d'uso

L'/invocationsendpoint serve a diversi scopi chiave:

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 alle richieste che possono essere elaborate rapidamente

Casi d'uso

Le risposte JSON sono ideali per:

Esempio di formato di risposta JSON

Content-Type: application/json

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

Risposta SSE (streaming)

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

Scopo

Consente una risposta incrementale per operazioni di lunga durata e una migliore esperienza utente

Casi d'uso

Le risposte SSE sono ideali per:

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 permanenti per le interazioni con gli agenti di streaming

Casi d'uso

L'/wsendpoint serve a diversi scopi chiave:

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

Il tuo WebSocket endpoint deve gestire:

Formati dei messaggi

Messaggi di testo

Formato JSON (consigliato)

Scopo

Scambio di dati strutturato 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 normale

Scopo

Comunicazione semplice basata su testo

Esempio

Hello, can you help me with this question?

Messaggi binari

Scopo

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

Casi d'uso

I messaggi binari supportano diversi scenari:

Requisiti di gestione

La gestione dei messaggi binari richiede:

Ciclo di vita della connessione

Stabilimento della connessione

Scambio di messaggi

/ping - GET

Scopo

Verifica che il tuo agente sia operativo e pronto a gestire le richieste

Casi d'uso

L'/pingendpoint serve a diversi scopi chiave:

Formato di risposta

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

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

Gestione degli errori

A differenza dei AG-UI protocolli A2A, MCP e, il protocollo HTTP non raggruppa gli errori in una busta specifica del protocollo. Il servizio restituisce gli errori direttamente come risposte HTTP native: il codice di stato HTTP riflette l'eccezione e l'intestazione della x-amzn-ErrorType risposta riporta il nome dell'eccezione. La tabella seguente elenca le eccezioni che puoi ricevere.

ConflictExceptioned RetryableConflictException entrambi restituiscono HTTP 409. L'x-amzn-ErrorTypeintestazione e il messaggio li distinguono. Il servizio restituisce RetryableConflictException (Session operation in progress, please retry) quando una seconda operazione è indirizzata a una sessione di cui il servizio sta eseguendo il provisioning o la disattivazione. Questa condizione è transitoria e riprovabile. Riprova con un breve backoff esponenziale. Gli AWS SDK riprovano automaticamente questa eccezione quando i tentativi predefiniti sono abilitati. Se chiami l'API direttamente senza un AWS SDK, devi riprovare tu stesso.

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 (per 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}"