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.

Anforderungen an die Implementierung von Protokollen

Ihr AG-UI Agent muss diese spezifischen Protokollanforderungen implementieren:

Anforderungen an Container

Ihr AG-UI Agent muss als containerisierte Anwendung bereitgestellt werden, die die folgenden Spezifikationen erfüllt:

Pfadanforderungen

/invocations — POST

Zweck

Empfängt Benutzeranfragen und streamt Antworten als Server-Sent Ereignisse (SSE)

Anwendungsfälle

Der Aufruf-Endpunkt dient mehreren wichtigen Zwecken:

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.

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:

/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:

{
  "status": "Healthy"
}

statusist erforderlich und ist einer von Healthy oderHealthyBusy. Solange der Status lautetHealthyBusy, 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.

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 <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <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:

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) 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.