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.

Commencez à utiliser les instances à l'aide du AWS CLI ou SDK

Ce didacticiel explique comment héberger un agent sur le type de calcul Instances avec l'interface de ligne de AWS commande (AWS CLI) et les SDK. Vous créez d'abord un fournisseur de capacité qui définit l'infrastructure Amazon Elastic Compute Cloud (Amazon EC2), puis vous créez un environnement d'exécution d'agent qui l'utilise, et enfin vous invoquez l'agent.

Pour connaître les prérequis, consultez la section Commencer à utiliser les instances.

Étape 1 : Création d'un fournisseur de capacités

Utilisez cette CreateCapacityProvider opération pour définir votre infrastructure EC2. La demande prend un permissionsConfiguration (le rôle IAM AgentCore utilisé pour faire fonctionner le fournisseur de capacité) et un computeConfiguration qui décrit les instances EC2 via un modèle de lancement. L'exemple suivant crée un fournisseur de capacité Linux avec un seul type d'instance autorisé et un volume EBS persistant.

Pour exécuter des charges de travail GPU, incluez un type d'instance GPU pris en charge dansallowedInstanceTypes. AgentCore provisionne les pilotes GPU sur l'instance, de sorte que les images de conteneurs standard fonctionnent sans regrouper les pilotes. Les familles prises en charge sont g4dn g5 g6g6e,gr6,g6f,gr6f,g7e, etinf2. Si vous incluez un type d'instance d'accélérateur appartenant à une famille non prise en charge, la demande échoue avec unValidationException. Pour plus d'informations, consultez la section Utiliser les types d'instances GPU.

Effectuez un sondage GetCapacityProvider jusqu'à ce que le statut soit atteint READY avant d'associer le fournisseur de capacité à un environnement d'exécution. Si le statut devientCREATE_FAILED, inspectez statusCode et statusReason déterminez la cause.

Étape 2 : créer un environnement d'exécution d'agent sur le fournisseur de capacité

Créez un environnement d'exécution d'agent avec un capacityProviderConfiguration qui fait référence à votre fournisseur de capacité. Pour monter un volume défini sur le fournisseur de capacité dans le système de fichiers de l'agent, ajoutez une capacityProviderVolume entrée filesystemConfigurations qui fait référence au volume par son nom. Les chemins de montage doivent se /mnt trouver sous un seul sous-répertoire (par exemple,/mnt/scratch).

Le runtime de l'agent possède son propre environnementlifecycleConfiguration.maxLifetime, qui est par défaut de 28 800 secondes (8 heures). Cette valeur doit être inférieure ou égale à maxLifetime celle définie par le fournisseur de capacitéec2Configuration.lifecycleConfiguration. À l'étape 1, le fournisseur de capacité définit cette valeur sur 3 600 secondes (1 heure), de sorte que la valeur par défaut de 8 heures serait supérieure à cette valeur et CreateAgentRuntime échouerait avec ValidationException a. L'exemple suivant définit donc une durée d'exécution maxLifetime de 1 800 secondes, ce qui est dans les limites du fournisseur de capacité.

Ne réussissez pas networkConfiguration lorsque vous le spécifiezcapacityProviderConfiguration. Un environnement d'exécution d'instances hérite de son réseau de celui du fournisseur de capacitéec2Configuration.vpcConfiguration, donc la spécification des deux échoue avec a. ValidationException

Étape 3 : Invoquer l'agent

Invoquez le runtime de la même manière que vous le feriez pour un micro VM-backed runtime. Réutilisez la même chose pour runtimeSessionId toutes les invocations afin de conserver la session sur la même instance. Cela permet à votre agent d'accéder aux données des appels précédents. Pour partager les locaux des agents collaborateurs, utilisez-les runtimeSessionId sur plusieurs environnements d'exécution partageant le même fournisseur de capacité.

runtimeSessionIdIl doit comporter au moins 33 caractères.

Le premier appel pour une nouvelle session provisionne une instance EC2 dans votre compte et lance l'agent. Cela prend donc généralement plus de temps que les appels ultérieurs. Les appels ultérieurs à la même session réutilisent l'instance en cours d'exécution et sont renvoyés beaucoup plus rapidement.

AgentCore provisionne ces instances en tant qu'instances gérées par Amazon EC2, qui sont masquées DescribeInstances et affichées par défaut sur votre console EC2. Un simple aws ec2 describe-instances appel ne les répertorie pas. Pour les consulter, incluez les ressources gérées :

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"

Pour plus d'informations sur la gestion de la visibilité des instances, consultez le paramètre de visibilité des ressources gérées.

Co-locate plusieurs agents sur une seule instance

Lorsque deux environnements d'exécution d'agents font référence au même fournisseur de capacité et que vous les invoquez avec le même nom runtimeSessionId, les deux agents s'exécutent sur la même instance EC2. Ils peuvent y partager le volume configuré dans la configuration de leur système de fichiers. Les agents collaborent en lisant et en écrivant des fichiers sur ce volume partagé. Chaque agent est invoqué indépendamment et ne partage pas d'état. Par exemple, un lanceur de tests peut écrire les résultats dans le volume, et un analyseur de code appelé au cours de la même session peut ensuite les lire. Pour connaître la limite entre les agents d'une instance partagée, consultez la section Modèle de sécurité et autorisations pour les instances d'exécution.

import boto3
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"

# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
    qualifier="DEFAULT",
)

# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
    qualifier="DEFAULT",
)

Chaque agent s'exécute avec ses propres informations d'identification IAM dérivées du rôle d'exécution de son environnement d'exécution. Vous pouvez donc accorder des autorisations différentes aux agents collaborateurs même s'ils partagent la même instance. Cependant, étant donné que les agents d'une même instance ne sont pas isolés les uns des autres, n'importe quel agent peut potentiellement lire les informations d'identification d'un autre agent. Co-locate uniquement des agents qui se font mutuellement confiance. Pour plus d'informations, consultez la section Modèle de sécurité et autorisations pour les instances d'exécution.

Nettoyage : arrêt et suppression de sessions

Une session peut héberger plusieurs environnements d'exécution d'agents sur la même instance. Elle AgentCore propose donc deux opérations distinctes :

Pour arrêter l'exécution d'un agent spécifique sur une session, appelez l'StopRuntimeSessionopération à l'aide de l'ARN d'exécution et de l'ID de session.

Pour supprimer une session et déprovisionner toutes ses ressources, y compris les volumes EBS persistants, appelez DeleteCapacityProviderSession avec l'ID du fournisseur de capacité et l'ID de session. L'opération est idempotente et asynchrone : elle revient immédiatement tout en AgentCore mettant fin à l'instance et en supprimant les volumes en arrière-plan.

Les ID de session sont des valeurs que vous fournissez lors de l'appel, et aucune opération ne répertorie les sessions sur un fournisseur de capacité. Conservez une trace des runtimeSessionId valeurs que vous utilisez afin de pouvoir supprimer chaque session par la suite. Si vous ne les possédez plus, vous pouvez rechercher les instances toujours en cours d'exécution, puis supprimer le fournisseur de capacité pour déprovisionner toutes ses sessions :

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
  --query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'

Supprimer un fournisseur de capacité

Lorsque vous n'avez plus besoin d'un fournisseur de capacité, supprimez-le avec l'DeleteCapacityProvideropération. La suppression d'un fournisseur de capacité arrête et supprime toutes ses sessions associées ainsi que leur stockage persistant. Cela permet également de nettoyer les sessions dont vous ne possédez plus les identifiants. Il n'est pas nécessaire de supprimer les sessions au préalable. Vous devez toutefois supprimer les environnements d'exécution qui font référence au fournisseur de capacité : supprimez d'abord les versions, les points de terminaison ou les environnements d'exécution associés, sinon la demande de suppression échoue avec un. ValidationException L'opération est asynchrone ; identifiez le fournisseur de capacité par son ID.