View a markdown version of this page

AG-UI contratto di protocollo - Amazon Bedrock AgentCore
Requisiti di implementazione del protocolloRequisiti del contenitoreRequisiti del percorsoRequisiti di autenticazioneGestione degli erroriRisposte di autenticazione OAuth

AG-UI contratto di protocollo

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

Per un esempio di codice, consulta Deploy AG-UI servers 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 dal server al client, abilita al contempo WebSocket la comunicazione bidirezionale in tempo reale

  • Gestione delle sessioni: la piattaforma aggiunge automaticamente l'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 queste specifiche:

  • Ospite: 0.0.0.0

  • Porta: 8080 - Porta standard per la comunicazione tra 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

/invocations - POST

Scopo

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

Casi d’uso

L'endpoint delle invocazioni ha diversi scopi chiave:

  • Risposte in streaming via chat

  • Status dell'agente e fasi di riflessione

  • Chiamate e risultati degli strumenti

Formato della richiesta

Amazon Bedrock AgentCore trasferisce i payload delle richieste direttamente al tuo container senza convalida. Per essere 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, consulta 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 comunicazioni bidirezionali 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 utente

  • Multi-turn conversazioni con connessioni persistenti

/ping - OTTIENI

Scopo

Verifica che l' 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 corretti e appropriati per stati non integri

{
  "status": "Healthy"
}

statusè obbligatorio ed è uno dei Healthy oHealthyBusy. 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 quando è stata apportata l'statusultima modifica.

avvertimento

Non impostate l'ora corrente time_of_last_update 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.

Requisiti di autenticazione

AG-UI gli agenti supportano più meccanismi di autenticazione:

Token OAuth 2.0 Bearer

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

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

Gli errori sono classificati in due categorie in base al momento in cui si verificano:

  • Connection-level errori: si verificano prima che la richiesta raggiunga il contenitore (autenticazione, convalida, limitazione). Questi restituiscono codici di stato HTTP standard.

  • Errori di runtime: si verificano durante l'esecuzione dell'agente dopo l'avvio dello stream. Questi appaiono come RUN_ERROR eventi nel flusso SSE anziché come codici di stato HTTP.

AG-UI Codice di errore Stato HTTP Description

UNAUTHORIZED

401

Autenticazione richiesta o credenziali non valide

ACCESS_DENIED

403

Autorizzazioni insufficienti per l'operazione richiesta

VALIDATION_ERROR

400

Dati o parametri della richiesta non validi

RATE_LIMIT_EXCEEDED

429

Troppe richieste dal cliente

AGENT_ERROR

200

Il codice dell'agente non è riuscito durante l'esecuzione: controlla i CloudWatch registri

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

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

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

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 l'individuazione di 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: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

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