AG-UI contratto di protocollo

Il contratto di AG-UI protocollo definisce i requisiti per l'implementazione della comunicazione tra interfaccia agente e utente in Amazon Bedrock Runtime. AgentCore Questo contratto specifica i requisiti tecnici, gli endpoint e i modelli di comunicazione che l'agente deve implementare. AG-UI

Ad esempio di codice, vedi Distribuire i AG-UI server in Runtime. AgentCore

Requisiti di implementazione del protocollo

Il tuo AG-UI agente deve implementare questi requisiti di protocollo specifici:

• Transport: Server-Sent Events (SSE) o WebSocket - SSE fornisce lo streaming unidirezionale da server a client, mentre WebSocket consente la comunicazione bidirezionale in tempo reale

• Gestione delle sessioni: la piattaforma aggiunge automaticamente un'intestazione per l'isolamento della sessione X-Amzn-Bedrock-AgentCore-Runtime-Session-Id

Requisiti del contenitore

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

• Host: 0.0.0.0

• Porta: 8080 - Porta standard per la comunicazione con gli AG-UI agenti (uguale al protocollo HTTP)

• Piattaforma: contenitore ARM64 - Necessario per la compatibilità con l'ambiente di AWS runtime Amazon Bedrock AgentCore

Requisiti del percorso

/invocazioni - POST

Scopo

Riceve le richieste degli utenti e trasmette le risposte come Server-Sent Eventi (SSE)

Casi d’uso

L'endpoint delle chiamate serve a diversi scopi chiave:

• Risposte alle chat in streaming

• Status dell'agente e fasi di riflessione

• Chiamate e risultati degli strumenti

Formato della richiesta

I AgentCore pass Amazon Bedrock richiedono payload direttamente nel tuo container senza convalida. Per esserlo AG-UI-compliant, le tue richieste devono seguire il formato. RunAgentInput L'implementazione del contenitore determina quali campi sono obbligatori e come vengono gestiti gli errori di convalida.

AG-UI-compliant gli agenti si aspettano un payload RunAgentInput JSON. Esempio:

{
  "threadId": "thread-123",
  "runId": "run-456",
  "messages": [{"id": "msg-1", "role": "user", "content": "Hello, agent!"}],
  "tools": [],
  "context": [],
  "state": {},
  "forwardedProps": {}
}

Per i dettagli completi RunAgentInput dello schema e del formato dei messaggi, vedi AG-UI Tipi.

Formato della risposta

AG-UI gli agenti rispondono con flussi di SSE-formatted eventi:

Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-789","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-789","delta":"Processing your request"}

data: {"type":"TOOL_CALL_START","toolCallId":"tool-001","toolCallName":"search","parentMessageId":"msg-789"}

data: {"type":"TOOL_CALL_RESULT","messageId":"msg-789","toolCallId":"tool-001","content":"Search completed"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-789"}

data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"}

/ws - WebSocket

Scopo

Fornisce una comunicazione bidirezionale in tempo reale tra clienti e agenti

Casi d’uso

L' WebSocket endpoint serve a diversi scopi chiave:

• Real-time interfacce conversazionali

• sessioni interattive con agenti con interruzioni da parte dell'utente

• Multi-turn conversazioni con connessioni permanenti

/ping - GET

Scopo

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

Formato della risposta

Restituisce un codice di stato che indica lo stato di salute dell'agente:

• Content-Type : application/json

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

{
  "status": "Healthy"
}

statusè obbligatorio ed è uno dei seguentiHealthy. HealthyBusy Mentre lo stato èHealthyBusy, la sessione di runtime viene mantenuta attiva.

È possibile includere un time_of_last_update campo opzionale (un timestamp Unix in secondi) per segnalare l'statusultima modifica.

avvertimento

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

Requisiti di autenticazione

AG-UI gli agenti supportano diversi meccanismi di autenticazione:

Token al portatore OAuth 2.0

Per l'autenticazione AG-UI del client, includi il token Bearer nelle intestazioni delle richieste:

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

Autenticazione SIGv4

L'autenticazione AWS SigV4 standard è supportata anche per l'accesso programmatico.

Gestione degli errori

AG-UI serializza ogni errore come RUN_ERROR evento SSE (Content-Type: text/event-stream), indipendentemente dal fatto che l'errore si verifichi prima o durante lo streaming. Le categorie si differenziano solo per il codice di stato HTTP che accompagna l'evento:

• Connection-level errori: si verificano prima che la richiesta raggiunga il contenitore (autenticazione, autorizzazione, convalida, limitazione, conflitti di sessione). L'RUN_ERRORevento viene restituito con il vero codice di stato HTTP dell'errore (ad esempio 401, 403 o 409).

• Errori di runtime: si verificano durante l'esecuzione dell'agente dopo l'avvio dello streaming. AGENT_ERRORRientra solo in questa categoria. Il suo RUN_ERROR evento restituisce HTTP 200 perché lo streaming è già iniziato.

La tabella seguente associa ogni eccezione di runtime al relativo codice di errore AG-UI SSE, al codice di stato HTTP e al messaggio. Alcune eccezioni condividono un codice di errore SSE ma restituiscono messaggi diversi, quindi sono elencate come righe separate.

Codice di errore SSE	Eccezione di runtime	Codice di errore HTTP	Messaggio di errore
UNAUTHORIZED	UnauthorizedException	401	Autenticazione richiesta o credenziali non valide
ACCESS_DENIED	AccessDeniedException	403	Autorizzazioni insufficienti per l'operazione richiesta
VALIDATION_ERROR	ValidationException	400	Dati o parametri della richiesta non validi
RATE_LIMIT_EXCEEDED	ThrottlingException	429	Troppe richieste dal cliente
SESSION_BUSY	ConflictException	409	Conflitto di risorse: la risorsa esiste già
SESSION_BUSY	RetryableConflictException	409	Operazione della sessione in corso, riprova
SERVICE_QUOTA_EXCEEDED	ServiceQuotaExceededException	429	Quota di servizio superata
AGENT_ERROR	RuntimeClientError	200	Codice agente non riuscito durante l'esecuzione: controlla i tuoi log CloudWatch
INTERNAL_ERROR	Qualsiasi altra eccezione	500	Si è verificato un errore interno durante l'elaborazione della richiesta

ConflictExceptioned RetryableConflictException entrambi utilizzano il codice di errore SESSION_BUSY SSE (HTTP 409) ma si distinguono per il messaggio. Il servizio restituisce RetryableConflictException (Session operation in progress, please retry) quando una seconda operazione raggiunge una sessione mentre il servizio esegue il provisioning o la disattivazione di tale sessione. È temporaneo e riprovabile: riprova con un breve backoff esponenziale, perché i client non lo riprovano automaticamente. AG-UI

Esempio di errore di runtime (errore dell'agente):

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"AGENT_ERROR","message":"Agent execution failed"}

Esempio di errore relativo alla sessione occupata (conflitto riattivabile):

HTTP/1.1 409 Conflict
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"SESSION_BUSY","message":"Session operation in progress, please retry"}

Risposte di autenticazione OAuth

OAuth-configured gli agenti restituiscono errori di autenticazione con codici di stato HTTP standard. La risposta include un'WWW-Authenticateintestazione (secondo RFC 7235) per il rilevamento OAuth tramite l'API. GetRuntimeProtectedResourceMetadata

Esempio di errore di autenticazione OAuth:

HTTP/1.1 401 Unauthorized
Content-Type: text/event-stream
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"UNAUTHORIZED","message":"Authentication required"}

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