Contrat de protocole HTTP

Découvrez 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 avec la AgentCore CLI.

Exigences relatives aux contenants

Votre 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

Il s'agit du point de terminaison principal de l'interaction avec l'agent 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 clés :

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 selon le cas d'utilisation :

Réponse JSON (sans diffusion en continu)

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 les événements (SSE) vous permettent 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 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 clés :

Etablissement 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 point de terminaison 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 simple basée sur du texte

Exemple

Hello, can you help me with this question?

Messages binaires

Objectif

Support pour les données non textuelles telles que les images, le son ou d'autres formats binaires

Cas d’utilisation

Les messages binaires prennent en charge plusieurs scénarios :

Exigences relatives à la manipulation

La gestion des messages binaires nécessite :

Cycle de vie des connexions

É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 clés :

Format de réponse

Renvoie un code de statut 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éfini sur HealthyBusy cette valeur, la session d'exécution est considérée comme active.

Exemple de format de réponse Ping

{
  "status": "<status_value>"
}

Réponses d'authentification OAuth

OAuth-configured les agents respectent les normes d'authentification RFC 6749 (OAuth 2.0). Lorsque l'authentification est absente, 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}"