Configuration d'Amazon Bedrock AgentCore Runtime et des outils pour VPC

Vous pouvez configurer Amazon Bedrock AgentCore Runtime et les outils intégrés (interpréteur de code et outil de navigateur) pour vous connecter aux ressources de votre Amazon Virtual Private Cloud (VPC). En configurant la connectivité VPC, vous permettez un accès sécurisé aux ressources privées telles que les bases de données, les API internes et les services au sein de votre VPC.

Connectivité VPC pour Amazon Bedrock AgentCore Runtime et ses outils

Pour activer Amazon Bedrock AgentCore Runtime et les outils intégrés permettant d'accéder en toute sécurité aux ressources de votre VPC privé, AgentCore fournit des fonctionnalités de connectivité VPC. Cette fonctionnalité permet à votre environnement d'exécution et à vos outils de :

Lorsque vous configurez la connectivité VPC pour Amazon Bedrock AgentCore Runtime et ses outils :

Conditions préalables

Avant de configurer Amazon Bedrock AgentCore Runtime et les outils d'accès aux VPC, assurez-vous de disposer des éléments suivants :

Zones de disponibilité prises en charge

AgentCore prend en charge la connectivité VPC dans des zones de disponibilité spécifiques au sein de chaque région prise en charge. Lorsque vous configurez des sous-réseaux pour votre Amazon Bedrock AgentCore Runtime et les outils intégrés, assurez-vous que vos sous-réseaux sont situés dans les zones de disponibilité prises en charge par votre région.

Le tableau suivant indique les ID de zone de disponibilité pris en charge pour chaque région :

Pour identifier l'ID de zone de disponibilité de vos sous-réseaux, vous pouvez utiliser la commande CLI suivante :

aws ec2 describe-subnets --subnet-ids subnet-12345678 --query 'Subnets[0].AvailabilityZoneId'

Autorisations IAM

AgentCore utilise le rôle lié au service AWSServiceRoleForBedrockAgentCoreNetwork pour créer et gérer des interfaces réseau dans votre VPC. Ce rôle est automatiquement créé lorsque vous configurez pour la première fois Amazon Bedrock AgentCore Runtime ou des outils AgentCore intégrés pour utiliser la connectivité VPC.

Si vous devez créer ce rôle manuellement, votre entité IAM a besoin des autorisations suivantes :

{
    "Action": "iam:CreateServiceLinkedRole",
    "Effect": "Allow",
    "Resource": "arn:aws:iam::*:role/aws-service-role/network.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreNetwork",
    "Condition": {
        "StringLike": {
            "iam:AWSServiceName": "network.bedrock-agentcore.amazonaws.com"
        }
    }
}

Cette autorisation est déjà incluse dans la politique AWS gérée BedrockAgentCoreFullAccess.

Bonnes pratiques

Pour des performances et une sécurité optimales avec VPC-connected Amazon Bedrock AgentCore Runtime et les outils intégrés :

Configuration de l'accès au VPC pour l'exécution et les outils

Vous pouvez configurer l'accès VPC pour Amazon Bedrock AgentCore Runtime et les outils intégrés à l'aide de la console de AWS gestion, de la AWS CLI ou des SDK. AWS

Configuration de l’exécution

Configuration de l'interpréteur de code

Configuration de l'outil de navigation

Considérations relatives aux groupes de sécurité

Les groupes de sécurité agissent comme des pare-feux virtuels pour votre Amazon Bedrock AgentCore Runtime ou comme un outil intégré lorsque vous êtes connecté à un VPC. Ils contrôlent le trafic entrant et sortant au niveau de l'instance. Pour configurer des groupes de sécurité pour votre environnement d'exécution :

Exemple : connexion à une base de données Amazon RDS

Lorsque votre Amazon Bedrock AgentCore Runtime se connecte à une base de données Amazon RDS, configurez les groupes de sécurité comme suit :

Groupe de sécurité Amazon Bedrock AgentCore Runtime

Groupe de sécurité de base de données Amazon RDS

Exemple : connexion aux fichiers Amazon EFS ou Amazon S3

Lorsque vous configurez des systèmes de fichiers « Bring-your-own » (points d'accès Amazon EFS ou Amazon S3 Files) sur le runtime de votre agent, AgentCore Runtime monte le système de fichiers sur NFS. Cela nécessite une connectivité TCP sur le port 2049 entre les ENI d'exécution de l'agent et les cibles de montage du système de fichiers.

AgentCore gère automatiquement le chiffrement TLS et l'authentification IAM. L'assistant de amazon-efs-utils montage est préinstallé dans le moteur d'exécution de microVM. Vous n'avez pas besoin de configurer ou d'installer de logiciel de montage dans votre image de conteneur.

Configuration du groupe de sécurité

Configurez vos groupes de sécurité pour autoriser le trafic NFS entre le runtime de l'agent et les cibles de montage de votre système de fichiers.

Groupe de sécurité d'exécution de l'agent — Règle sortante :

Groupe de sécurité cible de montage du système de fichiers — Règle de trafic entrant :

sg-mounttargetRemplacez-le par l'ID du groupe de sécurité de vos cibles de montage EFS ou S3 Files, et sg-agentruntime par l'ID du groupe de sécurité utilisé par l'environnement d'exécution de votre agent.

AWS CLI — Ajoutez une règle sortante au groupe de sécurité d'exécution de l'agent :

aws ec2 authorize-security-group-egress \
  --group-id sg-0123456789abcdef0 \
  --protocol tcp \
  --port 2049 \
  --source-group sg-0987654321fedcba0

AWS CLI — Ajoutez une règle entrante pour monter le groupe de sécurité cible :

aws ec2 authorize-security-group-ingress \
  --group-id sg-0987654321fedcba0 \
  --protocol tcp \
  --port 2049 \
  --source-group sg-0123456789abcdef0

Configuration du point de terminaison VPC

Lorsque vous exécutez Amazon Bedrock AgentCore Runtime dans un VPC, nous vous recommandons vivement de configurer les points de terminaison VPC suivants. Ces points de terminaison sont nécessaires si votre VPC n'a pas accès à Internet, et ils sont vivement recommandés même si votre VPC possède une passerelle NAT, afin d'éviter les frais de traitement des données liés à la passerelle NAT.

Points de terminaison VPC requis

Considérations relatives à l'accès Internet

Lorsque vous connectez Amazon Bedrock AgentCore Runtime ou un outil intégré à un Virtual Private Cloud (VPC), celui-ci n'a pas accès à Internet par défaut. Par défaut, ces ressources ne peuvent communiquer qu'avec les ressources d'un même VPC. Si votre environnement d'exécution ou votre outil nécessite un accès à la fois aux ressources du VPC et à Internet, vous devez configurer votre VPC en conséquence.

Architecture d'accès à Internet

Pour activer l'accès à Internet pour votre VPC-connected Amazon Bedrock AgentCore Runtime ou votre outil intégré, configurez votre VPC avec les composants suivants :

Configuration du routage

Mettez à jour les tables de routage de vos sous-réseaux comme suit :

Surveillance et résolution des problèmes

Pour surveiller et résoudre les problèmes liés à votre environnement d' AgentCore exécution et à vos outils VPC-connected Amazon Bedrock :

CloudWatch Journaux

Activez CloudWatch les journaux pour votre Amazon Bedrock AgentCore Runtime afin d'identifier tout problème de connectivité :

Problèmes courants et solutions correspondantes

Problèmes avec l'interpréteur de code

Problèmes liés à l'outil de navigation

Tester la connectivité VPC

Pour vérifier que votre AgentCore environnement d'exécution et vos outils disposent d'une connectivité VPC appropriée, vous pouvez tester les connexions à vos ressources privées et vérifier que les interfaces réseau sont créées correctement dans les sous-réseaux que vous avez spécifiés.

Pour vérifier que votre AgentCore outil dispose d'un accès à Internet, vous pouvez configurer un interpréteur de code avec votre configuration VPC et utiliser l'InvokeAPI pour tenter de se connecter à une API publique ou à un site Web à l'aide d'une curl commande et vérifier la réponse. executeCommand Si le délai de connexion expire, passez en revue la configuration de votre VPC, en particulier vos tables de routage et la configuration de la passerelle NAT.

# Using awscurl
awscurl -X POST \
  "https://bedrock-agentcore.<Region>.amazonaws.com/code-interpreters/<code_interpreter_id>/tools/invoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-amzn-code-interpreter-session-id: your-session-id" \
  --service bedrock-agentcore \
  --region <Region> \
  -d '{
    "name": "executeCommand",
    "arguments": {
      "command": "curl amazon.com"
    }
  }'

Problèmes de connectivité au système de fichiers

En cas d'échec du montage d'un système de fichiers, l'InvokeAgentRuntimeAPI renvoie le statut HTTP 424 (Failed Dependency). Utilisez les sections suivantes pour diagnostiquer la cause première.

Expiration du délai de montage du système de fichiers

Symptômes : les appels d'agents avec des configurations de système de fichiers échouent après un délai prolongé. L'erreur indique que le délai de l'opération de montage a expiré.

Causes courantes et solutions :

1. Règles du groupe de sécurité manquantes

Vérifiez la règle de trafic sortant sur le groupe de sécurité d'exécution de votre agent :

aws ec2 describe-security-groups \
  --group-ids sg-0123456789abcdef0 \
  --query 'SecurityGroups[0].IpPermissionsEgress[?ToPort==`2049`]'

Vérifiez la règle de trafic entrant sur votre groupe de sécurité cible de montage :

aws ec2 describe-security-groups \
  --group-ids sg-0987654321fedcba0 \
  --query 'SecurityGroups[0].IpPermissions[?ToPort==`2049`]'

Si l'une des requêtes renvoie des résultats vides, ajoutez la règle manquante comme indiqué dans Exemple : connexion à Amazon EFS ou à Amazon S3 Files.

2. Aucune cible de montage dans la zone de disponibilité de l'agent

Le runtime de l'agent peut être placé dans une zone de disponibilité où aucune cible de montage n'existe. Vérifiez le chevauchement :

# Get agent runtime subnet AZs
aws ec2 describe-subnets \
  --subnet-ids subnet-0123456789abcdef0 subnet-0123456789abcdef1 \
  --query 'Subnets[*].[SubnetId, AvailabilityZoneId]' --output table

# Get EFS mount target AZs
aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].[AvailabilityZoneId, LifeCycleState]' --output table

Solution : créez une cible de montage dans chaque zone de disponibilité où se trouvent les sous-réseaux d'exécution de votre agent, ou limitez les sous-réseaux d'exécution de l'agent aux zones de disponibilité où existent des cibles de montage.

3. Route manquante dans la table de routage : itinéraire local

Vérifiez que la table de routage associée aux sous-réseaux d'exécution de votre agent inclut la route VPC locale :

aws ec2 describe-route-tables \
  --filters "Name=association.subnet-id,Values=subnet-0123456789abcdef0" \
  --query 'RouteTables[0].Routes[?DestinationCidrBlock]'

Le montage du système de fichiers échoue avec « ResourceNotFound »

Symptômes : l'invocation de l'agent échoue immédiatement (sans délai d'expiration) avec une ResourceNotFound erreur de référence au nom d'hôte du système de fichiers.

Causes courantes et solutions :

1. Échec de résolution DNS — Le VPC ne peut pas résoudre le nom d'hôte cible de montage du système de fichiers.

Vérifiez les paramètres DNS de votre VPC :

aws ec2 describe-vpc-attribute \
  --vpc-id vpc-0123456789abcdef0 \
  --attribute enableDnsSupport

aws ec2 describe-vpc-attribute \
  --vpc-id vpc-0123456789abcdef0 \
  --attribute enableDnsHostnames

Les deux doivent revenirtrue. Si ce n'est pas le cas, activez-les :

aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-support
aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-hostnames

2. La cible de montage n'est pas disponible : la cible de montage est peut-être toujours en cours de création ou a peut-être été supprimée.

# For EFS
aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0

# For S3 Files
aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0

Assurez-vous que la cible de montage LifeCycleState estavailable. Si la cible de montage est manquante, recréez-la dans les sous-réseaux appropriés.

3. Système de fichiers ou point d'accès supprimé : la ressource référencée dans la configuration d'exécution de l'agent n'existe plus. Vérifiez et mettez à jour le runtime de l'agent avec des ARN valides.

Incompatibilité de la zone de disponibilité (pannes intermittentes)

Symptômes : les montages du système de fichiers réussissent par intermittence : certaines invocations fonctionnent tandis que d'autres échouent avec des délais impartis.

Pourquoi cela se produit : l'environnement d'exécution de votre agent possède des sous-réseaux dans plusieurs zones de disponibilité, mais les cibles de montage n'existent que dans certaines d'entre elles. Lorsque l'agent est placé dans une zone AZ sans cible de montage, le délai de montage expire.

Solution : créez des cibles de montage dans toutes les zones de disponibilité où se trouvent les sous-réseaux d'exécution de votre agent (recommandé) ou supprimez les sous-réseaux d'exécution des agents situés dans des zones de disponibilité sans cibles de montage.

# List all EFS mount target AZs
aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].AvailabilityZoneId' --output text

# Create a mount target in a missing AZ
aws efs create-mount-target \
  --file-system-id fs-0123456789abcdef0 \
  --subnet-id subnet-in-missing-az \
  --security-groups sg-0987654321fedcba0