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.

Contrat de protocole HTTP

Comprenez les exigences relatives à la mise en œuvre du protocole HTTP dans votre application d'agent. Utilisez le protocole HTTP pour créer des points de terminaison d'API REST directs pour les request/response modèles traditionnels et des points de WebSocket terminaison pour les connexions de streaming bidirectionnelles en temps réel.

Pour un exemple de code, voir Commencer à utiliser la AgentCore CLI.

Exigences relatives aux conteneurs

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

Exigences relatives au chemin

/invocations - POST

Il s'agit du point de terminaison principal de l'interaction des agents avec entrée et JSON/SSE sortie JSON.

Objectif

Reçoit les demandes entrantes des utilisateurs ou des applications et les traite selon la logique métier de votre agent

Cas d’utilisation

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

Exemple de format de demande

Content-Type: application/json

{
  "prompt": "What's the weather today?"
}

Formats de réponse

Votre agent peut répondre en utilisant l'un des formats suivants en fonction du cas d'utilisation :

Réponse JSON (hors diffusion)

Objectif

Fournit des réponses complètes aux demandes qui peuvent être traitées rapidement

Cas d’utilisation

Les réponses JSON sont idéales pour :

Exemple de format de réponse JSON

Content-Type: application/json

{
  "response": "Your agent's response here",
  "status": "success"
}

Réponse SSE (streaming)

Server-sent events (SSE) vous permet de fournir des réponses en streaming en temps réel. Pour plus d'informations, consultez la spécification Server-sent des événements.

Objectif

Permet de fournir des réponses incrémentielles pour les opérations de longue durée et d'améliorer l'expérience utilisateur

Cas d’utilisation

Les réponses SSE sont idéales pour :

Exemple de format de réponse SSE

Content-Type: text/event-stream

data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}

/ws - WebSocket (Facultatif)

Il s'agit du point de terminaison de WebSocket connexion principal pour les communications bidirectionnelles en temps réel.

Objectif

Accepte les demandes de WebSocket mise à niveau et maintient des connexions persistantes pour les interactions avec les agents de streaming

Cas d’utilisation

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

Établissement de la connexion

WebSocket les connexions commencent par une demande de mise à niveau HTTP :

Exemple de demande de mise à niveau HTTP

GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid

Exemple de réponse de WebSocket mise à niveau

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Exigences relatives à la gestion des messages

Votre WebSocket terminal doit gérer :

Formats de message

Messages texte

Format JSON (recommandé)

Objectif

Échange de données structuré pour les interactions entre agents

Exemple de message

{
  "prompt": "Hello, can you help me with this question?",
  "session_id": "session-uuid",
  "message_type": "user_message"
}

Exemple de réponse

{
  "response": "I'd be happy to help you with your question!",
  "session_id": "session-uuid",
  "message_type": "agent_response"
}

Format de texte brut

Objectif

Communication textuelle simple

Exemple

Hello, can you help me with this question?

Messages binaires

Objectif

Prise en charge des données non textuelles telles que des images, du son ou d'autres formats binaires

Cas d’utilisation

Les messages binaires prennent en charge plusieurs scénarios :

Exigences en matière de manipulation

La gestion des messages binaires nécessite :

Cycle de vie de connexion

Établissement de la connexion

Échange de messages

/ping - OBTENIR

Objectif

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

Cas d’utilisation

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

Format de réponse

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

Si votre agent doit traiter des tâches en arrière-plan, vous pouvez l'indiquer avec le /ping statut. Si l'état du ping est définiHealthyBusy, la session d'exécution est considérée comme active.

Exemple de format de réponse Ping

{
  "status": "<status_value>"
}

Gestion des erreurs

Contrairement aux AG-UI protocoles A2A, MCP et, le protocole HTTP n'enveloppe pas les erreurs dans une enveloppe spécifique au protocole. Le service renvoie les erreurs directement sous forme de réponses HTTP natives : le code d'état HTTP reflète l'exception et l'en-tête de x-amzn-ErrorType réponse contient le nom de l'exception. Le tableau suivant répertorie les exceptions que vous pouvez recevoir.

ConflictExceptionet RetryableConflictException les deux renvoient HTTP 409. L'x-amzn-ErrorTypeen-tête et le message les distinguent. Le service renvoie RetryableConflictException (Session operation in progress, please retry) lorsqu'une deuxième opération cible une session que le service est en train de provisionner ou de supprimer. Cette condition est transitoire et peut être réessayée. Réessayez avec une courte temporisation exponentielle. Les AWS kits SDK réessayent automatiquement cette exception lorsque les nouvelles tentatives par défaut sont activées. Si vous appelez l'API directement sans AWS SDK, vous devez réessayer vous-même.

Réponses d'authentification OAuth

OAuth-configured les agents suivent les normes d'authentification RFC 6749 (OAuth 2.0). Lorsque l'authentification est manquante, le service renvoie une réponse 401 Unauthorized avec un WWW-Authenticate en-tête (conformément à la RFC 7235), permettant aux clients de découvrir les points de terminaison du serveur d'autorisation via l'API. GetRuntimeProtectedResourceMetadata

401 Accès non autorisé

Renvoyé lorsque l'en-tête d'autorisation est manquant.

WWW-Authenticate En-tête inclus :

WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"