# AG-UI protokollarischer Vertrag
Der AG-UI Protokollvertrag definiert die Anforderungen für die Implementierung der Kommunikation zwischen Agent und Benutzerschnittstelle in Amazon AgentCore Bedrock Runtime. Dieser Vertrag legt die technischen Anforderungen, Endpunkte und Kommunikationsmuster fest, die Ihr AG-UI Agent implementieren muss.
Beispielcode finden Sie unter [Bereitstellen von AG-UI Servern in AgentCore Runtime](runtime-agui.md).
**Topics**
+ [Anforderungen an die Implementierung von Protokollen](#agui-protocol-implementation-requirements)
+ [Anforderungen an Container](#agui-container-requirements)
+ [Pfadanforderungen](#agui-path-requirements)
+ [Anforderungen an die Authentifizierung](#agui-authentication-requirements)
+ [Fehlerbehandlung](#agui-error-handling)
+ [Antworten auf die OAuth-Authentifizierung](#agui-oauth-authentication-responses)
## Anforderungen an die Implementierung von Protokollen
Ihr AG-UI Agent muss diese spezifischen Protokollanforderungen implementieren:
+ **Transport**: Server-Sent Events (SSE) oder WebSocket — SSE ermöglicht unidirektionales Streaming vom Server zum Client und WebSocket ermöglicht gleichzeitig eine bidirektionale Echtzeitkommunikation
+ **Sitzungsverwaltung**: Die Plattform fügt automatisch einen `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` Header für die Sitzungsisolierung hinzu
## Anforderungen an Container
Ihr AG-UI Agent muss als containerisierte Anwendung bereitgestellt werden, die die folgenden Spezifikationen erfüllt:
+ **Gastgeber:** `0.0.0.0`
+ **Port**: `8080` - Standardport für die AG-UI Agentenkommunikation (entspricht dem HTTP-Protokoll)
+ **Plattform**: ARM64-Container — Für die Kompatibilität mit der AWS Amazon AgentCore Bedrock-Laufzeitumgebung erforderlich
## Pfadanforderungen
### /invocations — POST
#### Zweck
Empfängt Benutzeranfragen und streamt Antworten als Server-Sent Ereignisse (SSE)
#### Anwendungsfälle
Der Aufruf-Endpunkt dient mehreren wichtigen Zwecken:
+ Chat-Antworten streamen
+ Status des Agenten und Schritte zum Nachdenken
+ Tool-Aufrufe und Ergebnisse
#### Anforderungsformat
Amazon Bedrock AgentCore leitet Anforderungsnutzlasten ohne Überprüfung direkt an Ihren Container weiter. Um das zu AG-UI-compliant tun, sollten Ihre Anfragen dem `RunAgentInput` Format folgen. Ihre Container-Implementierung bestimmt, welche Felder erforderlich sind und wie mit Validierungsfehlern umgegangen wird.
AG-UI-compliant Agenten erwarten eine `RunAgentInput` JSON-Nutzlast. Beispiel:
```
{
"threadId": "thread-123",
"runId": "run-456",
"messages": [{"id": "msg-1", "role": "user", "content": "Hello, agent!"}],
"tools": [],
"context": [],
"state": {},
"forwardedProps": {}
}
```
Das vollständige `RunAgentInput` Schema und das Nachrichtenformat finden Sie unter [AG-UI Typen](https://docs.ag-ui.com/sdk/js/core/types).
#### Reaktionsformat
AG-UI Agenten antworten mit SSE-formatted Event-Streams:
```
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
#### Zweck
Ermöglicht bidirektionale Echtzeitkommunikation zwischen Clients und Agenten
#### Anwendungsfälle
Der WebSocket Endpunkt dient mehreren wichtigen Zwecken:
+ Real-time Benutzeroberflächen für Konversationen
+ Interaktive Agentensitzungen mit Benutzerinterrupts
+ Multi-turn Konversationen mit dauerhaften Verbindungen
### /ping — GET
#### Zweck
Überprüft, ob Ihr AG-UI Agent betriebsbereit und bereit ist, Anfragen zu bearbeiten
#### Reaktionsformat
Gibt einen Statuscode zurück, der den Zustand Ihres Agenten angibt:
+ **Content-Type** : `application/json`
+ **HTTP-Statuscode**: `200` für fehlerfreie Zustände, entsprechende Fehlercodes für fehlerhafte Zustände
```
{
"status": "Healthy"
}
```
`status`ist erforderlich und ist einer von `Healthy` oder`HealthyBusy`. Solange der Status lautet`HealthyBusy`, wird die Runtime-Sitzung aktiv gehalten.
Ein optionales `time_of_last_update` Feld (ein Unix-Zeitstempel in Sekunden) kann hinzugefügt werden, um zu melden, wann die `status` letzte Änderung vorgenommen wurde.
**Warnung**
Stellen Sie nicht `time_of_last_update` bei jedem Ping die aktuelle Uhrzeit ein. Ein Zeitstempel, der bei jedem Ping weitergeht, signalisiert eine kontinuierliche Statusänderung, wodurch verhindert wird, dass das Timeout für inaktive Sitzungen jemals ausgelöst wird. Die Sitzungen dauern dann an, bis Ihr Sitzungskontingent ausgeschöpft ist `MaxLifetime` und diese möglicherweise aufgebraucht sind. Wenn Sie das Feld weglassen, verfolgt die Plattform die Statusänderungen selbstständig. Wenn Sie das Bedrock AgentCore SDK verwenden, wird die Ping-Antwort für Sie abgewickelt.
## Anforderungen an die Authentifizierung
AG-UI Agenten unterstützen mehrere Authentifizierungsmechanismen:
### OAuth 2.0-Trägertoken
Fügen Sie für die AG-UI Client-Authentifizierung das Bearer-Token in die Header der Anfrage ein:
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### SigV4-Authentifizierung
Die standardmäßige AWS SigV4-Authentifizierung wird auch für den programmatischen Zugriff unterstützt.
## Fehlerbehandlung
Fehler werden je nach dem Zeitpunkt ihres Auftretens in zwei Kategorien eingeteilt:
+ **Connection-level Fehler**: Treten auf, bevor die Anfrage Ihren Container erreicht (Authentifizierung, Validierung, Drosselung). Diese geben Standard-HTTP-Statuscodes zurück.
+ **Laufzeitfehler**: Treten während der Ausführung des Agenten auf, nachdem der Stream gestartet wurde. Diese tauchen eher als `RUN_ERROR` Ereignisse im SSE-Stream als als HTTP-Statuscodes auf.
| AG-UI Fehlercode | HTTP-Status | Description |
| --- | --- | --- |
| `UNAUTHORIZED` | 401 | Authentifizierung erforderlich oder ungültige Anmeldeinformationen |
| `ACCESS_DENIED` | 403 | Unzureichende Berechtigungen für den angeforderten Vorgang |
| `VALIDATION_ERROR` | 400 | Ungültige Anforderungsdaten oder Parameter |
| `RATE_LIMIT_EXCEEDED` | 429 | Zu viele Anfragen vom Client |
| `AGENT_ERROR` | 200 | Der Agentencode ist bei der Ausführung fehlgeschlagen — überprüfen Sie Ihre CloudWatch Logs |
Beispiel für einen Laufzeitfehler (Agentenfehler):
```
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"}
```
## Antworten auf die OAuth-Authentifizierung
OAuth-configured Agenten geben Authentifizierungsfehler mit Standard-HTTP-Statuscodes zurück. Die Antwort enthält einen `WWW-Authenticate` Header (gemäß [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)) für die OAuth-Erkennung über die API. GetRuntimeProtectedResourceMetadata
Beispiel für einen OAuth-Authentifizierungsfehler:
```
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 Agenten geben HTTP 403 mit einem `ACCESS_DENIED` Fehler zurück und schließen `WWW-Authenticate` keine Header ein.