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

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

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

Lorsque cela se produit : lors de l'appel d'un environnement d'exécution d'agent via InvokeAgentRuntimeExecuteCommand,InvokeAgentRuntimeWithWebSocketStream,InvokeAgentRuntimeCommandShell, 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 les environnements d'exécution sans metadataConfiguration set ou avec requireMMDSV2 set to ou. false null

Solution : appelez UpdateAgentRuntimeavec requireMMDSV2 défini true sur 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 seront acceptées. Les sessions existantes ne sont pas affectées.

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

Quand cela se produit : lors de l'invocation 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

Quand 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 publique ECR : 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

Je reçois l'erreur « Service inconnu : 'bedrock-agent-core-runtime' » lors de l'utilisation de boto3

Quand 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+

Je reçois « AccessDeniedException » lorsque j'essaie de créer un Amazon Bedrock Runtime AgentCore

Lorsque cela se produit : lors de la création de l'agent via la console, le SDK ou la CLI

Pourquoi cela se produit : soit votre utilisateur n'a pas les autorisations nécessaires, 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 compilation de Docker échoue avec « erreur de format exec/bin/sh: exec »

Quand 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 versions multiplateformes. Vous pouvez également utiliser CodeBuild. Pour un exemple de code, consultez les AgentCore échantillons Amazon Bedrock.

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

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 Amazon AgentCore Bedrock 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 actif, tandis qu'un rapport de session Healthy est considéré comme éligible à l'inactivité et sa durée d'inactivité est mesurée à 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 en 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 revient HealthyBusy pendant le traitement.

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

Lorsque cela se produit : le nombre de sessions augmente continuellement sous l'effet de la charge et les sessions ne sont pas libérées après le délai d'inactivité (par exemple,ServiceQuotaExceededException/maxVmserrors lors d'une rafale d'invocations), même si chaque session est inactive.

Pourquoi cela se produit : lorsqu'une session est signaléeHealthy, la plateforme mesure le temps pendant lequel elle est restée inactive à partir du time_of_last_update champ de votre /ping réponse, ce qui doit indiquer la date de la status dernière modification. Si votre gestionnaire de ping définit l'heure actuelle time_of_last_update à chaque ping, le temps d'inactivité indiqué ne cesse de se réinitialiser, ce qui empêche le délai d'inactivité de se déclencher. Les sessions sont ensuite diffusées jusqu'à MaxLifetime épuisement de votre quota de sessions.

Solution : effectuez la mise à jour time_of_last_update uniquement lorsque cela change status réellement, ou omettez-la 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 correctement gérée. En guise de solution, les appels StopRuntimeSession libèrent les sessions bloquées.

Comment accéder au runtime SessionId dans le code de mon agent pour baliser ou regrouper des ressources ?

Lorsque cela s'applique : vous souhaitez regrouper, étiqueter ou tracer 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 essayez d'appeler le runtime 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 vous ne voyez aucune connexion pertinente CloudWatch.

Solution

Essayez les méthodes suivantes pour diagnostiquer le problème :

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

Problème

L'invocation de 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

Vous pouvez voir un message d'erreur tel 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 corriger 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

Garantir la cohérence entre les environnements :

J'ai besoin d'aide pour résoudre les problèmes liés aux 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>

Test 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 les 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 doivent é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 en utilisant WebSocket

Pour le streaming bidirectionnel à l'aide d' WebSocket agents, suivez ces étapes de résolution des problèmes 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 le déploiement :

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 WebSocket de connexion courants :

Les modifications de mon 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 du 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 d'utiliser cette version du code jusqu'à la fin de la session, même lorsque les actifs du 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 plages sont manquantes lorsque mon environnement d'exécution est invoqué à partir d'une fonction Lambda

Quand 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 en-tête. X-Amzn-Trace-Id Si c'est le cas de la trace LambdaSampled=0, ce contexte non échantillonné se propage vers AgentCore Runtime et le moteur d'exécution ignore la génération de span pour cet appel.

Solution :

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

Lorsque cela se produit : lors de l'appel d'un agent avec un stockage S3 Files ou 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 un stockage S3 Files ou 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 identifiants sont incorrects.

Solution :

Le délai de 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 du réseau 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 le message « Permission 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 le message « 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éfini 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 de haute couche

Lorsque cela se produit : vos InvokeAgentRuntime appels renvoient le HTTP 424 (dépendance défaillante) 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 associé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'

Bonnes pratiques

Activez la journalisation complète

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

Utiliser une gestion structurée des erreurs

Implémentez un signalement d'erreurs clair :

Tester les modifications incrémentielles

Suivez une approche de test méthodique :

Surveiller les performances

Configurez la surveillance pour votre agent :