Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

AG-UI contrat de protocole

Le contrat de AG-UI protocole définit les exigences relatives à la mise en œuvre de la communication entre l'interface agent-utilisateur dans Amazon Bedrock Runtime. AgentCore Ce contrat spécifie les exigences techniques, les points de terminaison et les modèles de communication que votre AG-UI agent doit mettre en œuvre.

Pour un exemple de code, voir Déployer AG-UI des serveurs dans AgentCore Runtime.

Exigences de mise en œuvre du protocole

Votre AG-UI agent doit mettre en œuvre les exigences de protocole spécifiques suivantes :

Exigences relatives aux conteneurs

Votre AG-UI agent doit être déployé en tant qu'application conteneurisée répondant aux spécifications suivantes :

Exigences relatives au chemin

/invocations - POST

Objectif

Reçoit les demandes des utilisateurs et diffuse les réponses sous forme d' Server-Sent événements (SSE)

Cas d’utilisation

Le point de terminaison des invocations a plusieurs objectifs principaux :

Format des demandes

Amazon Bedrock AgentCore transmet les charges utiles demandées directement à votre conteneur sans validation. Pour l'être AG-UI-compliant, vos demandes doivent suivre le RunAgentInput format. L'implémentation de votre conteneur détermine quels champs sont obligatoires et comment les erreurs de validation sont gérées.

AG-UI-compliant les agents s'attendent à une charge utile RunAgentInput JSON. Exemple :

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

Pour les détails complets RunAgentInput du schéma et du format des messages, voir AG-UI Types.

Format de la réponse

AG-UI les agents répondent par des flux d' SSE-formatted événements :

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

Objectif

Fournit une communication bidirectionnelle en temps réel entre les clients et les agents

Cas d’utilisation

Le WebSocket point de terminaison répond à plusieurs objectifs principaux :

/ping - OBTENIR

Objectif

Vérifie que votre AG-UI agent est opérationnel et prêt à traiter les demandes

Format de la réponse

Renvoie un code d'état indiquant l'état de santé de votre agent :

{
  "status": "Healthy"
}

statusest obligatoire et est l'un des Healthy ouHealthyBusy. Tant que le statut est HealthyBusy défini, la session d'exécution est maintenue active.

Un time_of_last_update champ facultatif (horodatage Unix en secondes) peut être inclus pour indiquer la date de la status dernière modification.

Exigences en matière d'authentification

AG-UI les agents prennent en charge plusieurs mécanismes d'authentification :

Jetons au porteur OAuth 2.0

Pour l'authentification AG-UI du client, incluez le jeton Bearer dans les en-têtes de demande :

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

Authentification SIGv4

L'authentification AWS Sigv4 standard est également prise en charge pour l'accès par programmation.

Gestion des erreurs

AG-UI sérialise chaque erreur en tant qu'RUN_ERRORévénement SSE (Content-Type: text/event-stream), que l'erreur se produise avant ou pendant le streaming. Les catégories ne diffèrent que par le code d'état HTTP qui accompagne l'événement :

Le tableau suivant associe chaque exception d'exécution à son code d'erreur AG-UI SSE, à son code d'état HTTP et à son message. Certaines exceptions partagent un code d'erreur SSE mais renvoient des messages différents. Elles sont donc répertoriées sur des lignes distinctes.

ConflictExceptionet RetryableConflictException les deux utilisent le code d'erreur SESSION_BUSY SSE (HTTP 409) mais se distinguent par leur message. Le service return RetryableConflictException (Session operation in progress, please retry) lorsqu'une deuxième opération atteint une session alors que le service provisionne ou supprime cette session. Il est temporaire et peut être réessayé. Réessayez avec un bref délai exponentiel, car AG-UI les clients ne le réessayent pas automatiquement.

Exemple d'erreur d'exécution (défaillance de l'agent) :

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"}

Exemple d'erreur d'occupation de session (conflit réessayable) :

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"}

Réponses d'authentification OAuth

OAuth-configured les agents renvoient des erreurs d'authentification avec des codes d'état HTTP standard. La réponse inclut un WWW-Authenticate en-tête (conformément à la norme RFC 7235) pour la découverte d'OAuth via l'API. GetRuntimeProtectedResourceMetadata

Exemple d'erreur d'authentification 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 les agents renvoient HTTP 403 avec une ACCESS_DENIED erreur et n'incluent pas d'WWW-Authenticateen-têtes.