AG-UI contrat protocolaire

Le contrat de AG-UI protocole définit les exigences relatives à la mise en œuvre de la communication d'interface agent-utilisateur dans Amazon Bedrock Runtime. AgentCore Ce contrat précise 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 ces exigences de protocole spécifiques :

Exigences relatives aux contenants

Votre AG-UI agent doit être déployé sous la forme d'une 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 appels répond à plusieurs objectifs clés :

Format des demandes

Amazon Bedrock AgentCore transmet les charges utiles demandées directement à votre conteneur sans validation. Pour ce faire AG-UI-compliant, vos demandes doivent respecter le RunAgentInput format. L'implémentation de votre conteneur détermine les champs obligatoires et la manière dont les erreurs de validation sont traitées.

AG-UI-compliant les agents 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 obtenir des informations complètes sur le RunAgentInput schéma et le format des messages, consultez la section 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 clés :

/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 de statut indiquant l'état de santé de votre agent :

{
  "status": "Healthy"
}

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

Un time_of_last_update champ facultatif (un 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 porteurs 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 programmatique.

Gestion des erreurs

Les erreurs sont classées en deux catégories selon le moment où elles se produisent :

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

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

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 RFC 7235) pour la découverte 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: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

data: {"type":"RUN_ERROR","code":"UNAUTHORIZED","message":"Authentication required"}

SigV4-configured les agents renvoient le HTTP 403 avec une ACCESS_DENIED erreur et n'incluent pas les WWW-Authenticate en-têtes.