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.

Résoudre les problèmes d'exécution AgentCore

Cette rubrique de dépannage vous aide à identifier et à résoudre les problèmes courants liés à l'utilisation de AgentCore Runtime. En suivant ces solutions, vous pouvez rapidement diagnostiquer et résoudre les problèmes liés au temps d'exécution de vos agents.

Les appels de mon agent échouent avec le message « Ce runtime n'est pas MMDSv2-enabled » ValidationException

Lorsque cela se produit : lors de l'appel d'un moteur d'exécution d'un agent via InvokeAgentRuntimeExecuteCommand, InvokeAgentRuntimeWithWebSocketStreamInvokeAgentRuntimeCommandShell, ou GetAgentCard

Pourquoi cela se produit : à compter du 30 juin 2026, Amazon Bedrock AgentCore Runtime exige que tous les environnements d'exécution des agents utilisent MMDSv2 (MicroVM Metadata Service version 2). Le service rejette les appels ciblant des environnements d'exécution non metadataConfiguration définis, ou dont la valeur est requireMMDSV2 définie sur ou. false null

Solution : appelez UpdateAgentRuntime avec requireMMDSV2 réglé pour true entrer metadataConfiguration :

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

try:
    client.update_agent_runtime(
        agentRuntimeId='your-agent-runtime-id',
        metadataConfiguration={
            'requireMMDSV2': True
        }
    )
    print("MMDSv2 enabled successfully.")
except client.exceptions.ResourceNotFoundException as e:
    print(f"Runtime not found: {e}")
except Exception as e:
    print(f"Error enabling MMDSv2: {e}")

Après la mise à jour, les nouvelles invocations réussiront. Les sessions existantes ne sont pas affectées.

Les appels de mon agent échouent avec des erreurs 504 Gateway Timeout

Dans ce cas : lors de l'appel de l'agent via le SDK ou la console

Pourquoi cela se produit : plusieurs facteurs peuvent empêcher votre agent de répondre dans le délai imparti

Plusieurs facteurs peuvent en être la cause :

Ma version de Docker échoue avec « 403 Forbidden » lors de l'extraction d'images de base Python

Lorsque cela se produit : pendant docker build ou docker run lors de l'utilisation d'images public.ecr.aws de base

Pourquoi cela se produit : problèmes d'authentification ECR Public : l'authentification expirée ou manquante est un problème courant.

Solution : connectez-vous à ECR Public ou déconnectez-vous complètement :

# Option 1: Login to ECR Public
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws

# Option 2: Logout (recommended for avoiding token expiration)
docker logout public.ecr.aws

# Option 3: Use Docker Hub directly in Dockerfile
FROM python:3.10-slim
# instead of public.ecr.aws/docker/library/python:3.10-slim

J'obtiens l'erreur « Service inconnu : 'bedrock-agent-core-runtime' » lors de l'utilisation de boto3

Lorsque cela se produit : lors de l'appel des AgentCore API Amazon Bedrock à l'aide du SDK boto3

Pourquoi cela se produit : bibliothèque boto3 obsolète — problème courant car la plupart des installations ne disposent pas du dernier SDK

Solution : mise à jour vers les dernières versions de boto3 et botocore :

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

J'obtiens « AccessDeniedException » lorsque j'essaie de créer un environnement d'exécution Amazon Bedrock AgentCore

Dans ce cas : lors de la création de l'agent via la console, le SDK ou l'interface de ligne de commande

Pourquoi cela se produit : soit votre utilisateur n'a pas d'autorisations, soit le rôle d'exécution n'est pas correctement configuré pour Amazon Bedrock AgentCore

Solution : Plusieurs facteurs peuvent en être la cause :

Ma version de Docker échoue avec « exec/bin/sh: exec format error »

Lorsque cela se produit : lors de la création de conteneurs pour le déploiement d'Amazon Bedrock AgentCore

Pourquoi cela se produit : création de conteneurs ARM64 sur des systèmes x86 sans configuration multiplateforme appropriée

Solution : créez des conteneurs compatibles ARM64. Vous pouvez envisager d'utiliser buildx pour les builds multiplateformes. Vous pouvez également utiliser CodeBuild. Pour un exemple de code, consultez les AgentCore échantillons https://github.com/awslabs/amazon-bedrock-agentcore-samples/ Amazon Bedrock.

Quelles sont les exigences relatives aux conteneurs Docker utilisés avec Amazon Bedrock AgentCore Runtime ?

Consultez les exigences AgentCore d'Amazon Bedrock Runtime pour plus de détails.

En résumé, votre conteneur Docker doit répondre aux exigences suivantes :

Mon outil de longue durée est interrompu au bout de 15 minutes

Pour plus d'informations, consultez Gérer les agents asynchrones et de longue durée avec Amazon Bedrock AgentCore Runtime pour plus de détails.

Lorsque cela se produit : lors d'opérations d'agent de longue durée ou de flux de travail complexes

Pourquoi cela se produit : Amazon Bedrock met AgentCore automatiquement fin aux sessions après 15 minutes d'inactivité. La plateforme détermine l'activité à partir de la /ping réponse : un rapport de session HealthyBusy est maintenu en vie, tandis qu'un rapport de session Healthy est considéré comme éligible à l'inactivité et son temps d'inactivité est mesuré à partir de la status dernière modification (voir le time_of_last_update champ ci-dessous).

Solution : assurez-vous que votre /ping terminal revient HealthyBusy pendant que le travail d'arrière-plan est en cours :

{"status": "HealthyBusy"}

Si vous utilisez le AgentCore SDK Bedrock, la réponse ping est gérée automatiquement. Pour les implémentations personnalisées, assurez-vous que votre gestionnaire de ping est renvoyé HealthyBusy pendant le traitement.

Mes sessions inactives ne sont pas publiées et j'épuise mon quota de sessions

Lorsque cela se produit : le nombre de sessions augmente continuellement en cas de charge et les sessions ne sont pas libérées après le délai d'inactivité (par exemple, maxVms des erreursServiceQuotaExceededException/lors d'une rafale d'appels), même si chaque session est inactive.

Pourquoi cela se produit : lorsqu'une session génère un rapportHealthy, la plateforme mesure depuis combien de temps elle est restée inactive à partir du time_of_last_update champ de votre /ping réponse, qui doit refléter la date de la status dernière modification. Si votre gestionnaire de ping définit l'heure actuelle time_of_last_update pour chaque ping, le temps d'inactivité indiqué est constamment réinitialisé, ce qui empêche le déclenchement du délai d'inactivité. Les sessions sont ensuite diffusées jusqu'à MaxLifetime épuisement de votre quota de sessions.

Solution : mettez à jour time_of_last_update uniquement lorsque cela change status réellement, ou omettez-le complètement pour que la plateforme suive elle-même les changements de statut :

{"status": "Healthy"}

Si vous utilisez le AgentCore SDK Bedrock, passez à la dernière version, dans laquelle la réponse ping est gérée correctement. En guise de solution, l'appel StopRuntimeSession libère des sessions bloquées.

Comment accéder à l'environnement d'exécution SessionId dans le code de mon agent pour baliser ou regrouper des ressources ?

Lorsque cela s'applique : vous souhaitez regrouper, baliser ou suivre des ressources (par exemple, des objets S3, des journaux) en fonction de la session d'exécution de l'agent en cours.

Solutions :

Solution 1 : pour les agents utilisant le AgentCore SDK Bedrock Amazon Bedrock, utilisez-le depuis le point d'entrée context.session_id de votre agent

@app.entrypoint
def my_agent(payload, context):
    session_id = context.session_id

    # Use session_id for S3 object tagging/organization
    s3_client = boto3.client('s3')
    s3_client.put_object(
        Bucket='my-bucket',
        Key=f'agent-outputs/{session_id}/output.json',
        Body=json.dumps(result),
        Tagging=f'SessionId={session_id}'
    )
    return result

Solution 2 : pour les serveurs HTTP d'exécution personnalisés

L'ID de session d'exécution est transmis dans cet en-tête HTTP. Analysez-le à partir de la demande entrante et utilisez-le pour le balisage, la corrélation ou la propagation en aval.

X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <value>

J'ai RuntimeClientError (403) problèmes

Problème

Vous recevez un 403 « RuntimeClientError » lorsque vous tentez d'appeler le moteur d'exécution de votre agent.

Les causes

Cette erreur se produit généralement pour les raisons suivantes :

Résolution

Pour résoudre le problème, procédez comme suit :

J'ai des CloudWatch journaux vides ou manquants

Problème

Vous rencontrez des erreurs mais aucun identifiant pertinent ne s'affiche CloudWatch.

Solution

Essayez les approches suivantes pour diagnostiquer le problème :

J'ai des problèmes de format de charge utile

Problème

L'appel à l'exécution de votre agent échoue même si le conteneur démarre correctement.

Résolution

Pour résoudre les problèmes de format de charge utile, procédez comme suit :

J'ai besoin d'aide pour comprendre les codes d'erreur HTTP

Problème

Votre agent renvoie des codes d'erreur HTTP difficiles à interpréter.

Exemple de message d'erreur

Il se peut que vous voyiez une erreur telle que :

An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error (<HTTP Status Code>) from runtime. Please check your CloudWatch logs for more information

Résolution

Voici les codes d'erreur les plus courants et leur signification :

J'ai besoin de recommandations pour tester mon agent

Pour résoudre systématiquement les problèmes d'exécution de l'agent, procédez comme suit :

Testez d'abord localement

Avant le déploiement sur AgentCore Runtime :

Comparez les charges utiles

Garantissez la cohérence entre les environnements :

J'ai besoin d'aide pour résoudre les problèmes de conteneurs

Si vous suspectez des problèmes liés aux conteneurs :

Tirez et exécutez localement

Testez l'image de votre conteneur sur votre machine locale :

docker pull <your-ecr-repo-uri>
docker run -p 8080:8080 <your-ecr-repo-uri>

Testez avec curl

Envoyez des demandes de test à votre conteneur local :

curl -X POST http://localhost:8080/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": {"prompt": "Hello world!"}}'

Vérifiez les journaux des conteneurs

Examinez la sortie du conteneur pour détecter d'éventuelles erreurs :

docker logs <container-id>

J'ai besoin d'aide pour résoudre les problèmes liés aux agents du protocole MCP

Pour les agents du protocole MCP, suivez ces étapes de dépannage spécifiques :

Vérifier le chemin du terminal

Les serveurs MCP devraient écouter 0.0.0.0:8000/mcp/

Utiliser MCP Inspector

Testez avec l'outil MCP Inspector :

Problèmes d’authentification

Vérifiez la configuration de l'authentification :

J'ai besoin d'aide pour résoudre le problème du streaming bidirectionnel à l'aide de WebSocket

Pour le streaming bidirectionnel à l'aide d' WebSocket agents, suivez ces étapes de dépannage spécifiques :

Vérifier la configuration des terminaux

WebSocket les agents doivent s'exécuter sur le port 8080 et servir les WebSocket connexions sur /ws le chemin

Testez localement avec une complexité incrémentielle

Commencez par de simples tests locaux avant de déployer :

Problèmes d’authentification

Vérifiez la configuration de l'authentification pour les agents déployés :

Problèmes de connexion courants

Résolvez les problèmes de WebSocket connexion courants :

Mes modifications de code ne sont pas reflétées dans les sessions existantes

Problème

Vous avez mis à jour le moteur d'exécution de votre agent avec un nouveau code, mais les sessions existantes continuent d'utiliser l'ancienne version.

Pourquoi cela se produit

Chaque session MicroVM est créée avec les actifs de code (agentRuntimeArtifact) qui ont été déployés au moment de la création de la session. Une fois qu'une session est établie, elle continue à utiliser cette version du code jusqu'à la fin de la session, même lorsque les éléments de code sont mis à jour dans le cadre de l'exécution de l'UpdateAgentRuntimeopération.

Solution

Pour accéder à votre code mis à jour, utilisez un nouvel identifiant de session.

Les spans sont manquantes lorsque mon environnement d'exécution est invoqué depuis une fonction Lambda

Lorsque cela se produit : lors de l'appel de AgentCore Runtime à partir d'une fonction Lambda

Pourquoi cela se produit : Lambda génère son propre X-Amzn-Trace-Id en-tête. Si c'est le cas de la trace LambdaSampled=0, ce contexte non échantillonné se propage vers AgentCore Runtime et le runtime ignore la génération de span pour cette invocation.

Solution :

Le montage de mes fichiers S3 ou EFS échoue avec « Accès refusé »

Lorsque cela se produit : lors de l'appel d'un agent avec des fichiers S3 ou un stockage EFS configuré

Pourquoi cela se produit : le rôle d'exécution ne dispose pas des autorisations de système de fichiers requises. Pour plus d'informations sur la configuration du stockage persistant, consultez la section Configurations du système de fichiers pour AgentCore Runtime.

Solution :

Pour les fichiers S3, assurez-vous que votre rôle d'exécution est le suivant :

{
  "Effect": "Allow",
  "Action": [
    "s3files:ClientMount",
    "s3files:ClientWrite"
  ],
  "Resource": "arn:aws:s3files:<region>:<account>:file-system/*",
  "Condition": {
    "StringEquals": {
      "s3files:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Pour EFS, assurez-vous que votre rôle d'exécution est le suivant :

{
  "Effect": "Allow",
  "Action": [
    "elasticfilesystem:ClientMount",
    "elasticfilesystem:ClientWrite"
  ],
  "Resource": "arn:aws:elasticfilesystem:<region>:<account>:file-system/<fs-id>",
  "Condition": {
    "StringEquals": {
      "elasticfilesystem:AccessPointArn": "<your-access-point-arn>"
    }
  }
}

Omettez s3files:ClientWrite ou elasticfilesystem:ClientWrite si votre agent n'a besoin que d'un accès en lecture.

Le montage de mes fichiers S3 ou EFS échoue avec « ResourceNotFound »

Lorsque cela se produit : lors de l'appel d'un agent avec des fichiers S3 ou un stockage EFS configuré

Pourquoi cela se produit : le système de fichiers ou le point d'accès a été supprimé après la création de l'agent, ou les ID sont incorrects.

Solution :

Le montage de mes fichiers S3 ou EFS expire

Lorsque cela se produit : lors de l'appel d'un agent avec des fichiers S3 ou un stockage EFS configuré. L'invocation peut prendre plus de temps que d'habitude avant d'échouer.

Pourquoi cela se produit : La configuration réseau du VPC bloque le trafic NFS (port 2049) entre le calcul de l'agent et les cibles de montage du système de fichiers.

Solution :

J'obtiens « Autorisation refusée » lorsque j'écris sur mon système de fichiers monté

Lorsque cela se produit : l'appel de l'agent réussit et l'agent peut lire les fichiers depuis le montage, mais l'écriture échoue avec « Autorisation refusée »

Pourquoi cela se produit : soit le rôle IAM ne dispose pas d'autorisations d'écriture, soit les autorisations POSIX sur le répertoire définies lors de la création du point d'accès n'autorisent pas les écritures pour l'utilisateur de l'agent.

Solution :

Mon conteneur ne démarre pas avec une erreur HTTP 424 sur les images à couche supérieure

Dans ce cas : vos InvokeAgentRuntime appels renvoient le protocole HTTP 424 (échec de dépendance) et les journaux de votre agent s'affichentFailed to mount overlay: No such file or directory. Cela se produit lorsque votre image de conteneur comporte plus de 53 couches ET utilise une directive USER non numérique (par exemple, USER myuser au lieu deUSER 1000).

Pourquoi cela se produit : les images de conteneur comportant de nombreuses couches combinées à des directives USER non numériques peuvent provoquer des échecs d'initialisation.

Solution : utilisez l'une des solutions suivantes :

docker inspect <image> | jq '.[0].RootFS.Layers | length'

Mon fournisseur de capacité est dans l'état CREATE_FAILED

Lorsque cela se produit : après avoir appelé le type CreateCapacityProvider de calcul Instances, le fournisseur de capacité n'atteint pas ACTIVE et entre à la placeCREATE_FAILED.

Pourquoi cela se produit : un fournisseur de capacité s'appuie sur de multiples ressources (telles qu'un modèle de lancement et un groupe Auto Scaling) que le rôle d'opérateur du fournisseur de capacité doit être en mesure de créer. L'absence d'autorisations sur ce rôle entraîne un échec de création.

Solution : appelez l'GetCapacityProviderAPI pour récupérer la raison de l'échec dans le statusReason champ. statusReasonIdentifie les ressources qui n'ont pas pu être créées. Accordez au rôle d'opérateur du fournisseur de capacité les autorisations dont il a besoin pour créer ces ressources, puis créez à nouveau le fournisseur de capacité. Pour plus d'informations sur le rôle de l'opérateur, consultez la section Modèle de sécurité et autorisations pour les instances d'exécution.

Mes agents sur Instances n'ont pas accès à leurs informations d'identification

Dans ce cas : un agent qui s'exécute sur une session Instances ne peut pas obtenir les informations d'identification dont il a besoin pour appeler AWS les services.

Pourquoi cela se produit : le rôle d'exécution d'exécution est absent ou ne peut pas être assumé par AgentCore.

Solution : assurez-vous que le rôle d'exécution que vous avez configuré pour votre environnement d'exécution existe et permet bedrock-agentcore.amazonaws.com d'appelersts:AssumeRole. Pour plus d'informations, consultez la section Autorisations pour le rôle d'exécution d'Amazon Bedrock AgentCore Runtime.

Bonnes pratiques

Activez une journalisation complète

Mettez en place une journalisation complète dans votre agent :

Utiliser la gestion structurée des erreurs

Implémentez des rapports d'erreurs clairs :

Testez les modifications incrémentielles

Suivez une approche de test méthodique :

Surveillez les performances

Configurez la surveillance pour votre agent :