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à.
# 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 ](runtime-agui.md)
**Topics**
+ [Requisiti di implementazione del protocollo](#agui-protocol-implementation-requirements)
+ [Requisiti del contenitore](#agui-container-requirements)
+ [Requisiti del percorso](#agui-path-requirements)
+ [Requisiti di autenticazione](#agui-authentication-requirements)
+ [Gestione degli errori](#agui-error-handling)
+ [Risposte di autenticazione OAuth](#agui-oauth-authentication-responses)
## 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. ](https://docs.ag-ui.com/sdk/js/core/types)
#### 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 seguenti`Healthy`. `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'`status`ultima 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
X-Amzn-Bedrock-AgentCore-Runtime-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_ERROR`evento 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_ERROR`Rientra 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 |
`ConflictException`ed `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-Authenticate`intestazione (secondo [ RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)) 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`