Solucionar problemas en tiempo de AgentCore ejecución

Este tema de solución de problemas le ayuda a identificar y resolver problemas comunes al trabajar con AgentCore Runtime. Si sigue estas soluciones, puede diagnosticar y solucionar rápidamente los problemas relacionados con los tiempos de ejecución de sus agentes.

Las invocaciones de mi agente fallan y dicen: «Este tiempo de ejecución no es» MMDSv2-enabled ValidationException

Cuando esto ocurre: al invocar el tiempo de ejecución de un agente medianteInvokeAgentRuntime,ExecuteCommand,InvokeAgentRuntimeWithWebSocketStream, InvokeAgentRuntimeCommandShell o GetAgentCard

Por qué sucede esto: A partir del 30 de junio de 2026, Amazon Bedrock AgentCore Runtime requiere que todos los tiempos de ejecución de los agentes usen MMDSv2 (MicroVM Metadata Service versión 2). El servicio rechaza las invocaciones dirigidas a tiempos de ejecución que no estén configurados o estén metadataConfiguration configurados en o. requireMMDSV2 false null

Solución: llame UpdateAgentRuntimecon la requireMMDSV2 configuración establecida en: true 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}")

Tras la actualización, las nuevas invocaciones se realizarán correctamente. Las sesiones existentes no se ven afectadas.

Las invocaciones de mi agente fallan y se producen 504 errores de tiempo de espera de Gateway

Cuando esto ocurre: durante la invocación del agente mediante el SDK o la consola

Por qué sucede esto: varios factores pueden impedir que su agente responda dentro del período de espera

Hay varios factores que pueden provocar esto:

Mi compilación de Docker falla con «403 Forbidden» al extraer imágenes base de Python

Cuando esto ocurre: durante docker build o docker run cuando se utilizan imágenes public.ecr.aws base

Por qué sucede esto: Problemas de autenticación pública con ECR: la autenticación caducada o faltante es un problema común.

Solución: inicie sesión en ECR Public o cierre la sesión por completo:

# 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

Al usar boto3, aparece el error «Servicio desconocido: 'bedrock-agent-core-runtime'»

Cuando esto ocurre: al invocar las AgentCore API de Amazon Bedrock mediante el SDK boto3

Por qué sucede esto: la biblioteca boto3 está desactualizada: un problema común, ya que la mayoría de las instalaciones no tienen el SDK más reciente

Solución: actualice a las últimas versiones de boto3 y botocore:

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

Obtengo «AccessDeniedException» cuando intento crear un Amazon Bedrock Runtime AgentCore

Cuando esto ocurre: durante la creación del agente mediante la consola, el SDK o la CLI

Por qué sucede esto: o su usuario carece de permisos o la función de ejecución no está configurada correctamente para Amazon Bedrock AgentCore

Solución: hay varios factores que pueden provocar esto:

Mi compilación de Docker falla y aparece el mensaje «exec/bin/sh: exec format error»

Cuando esto ocurre: Al crear contenedores para la implementación de Amazon Bedrock AgentCore

Por qué sucede esto: creación de contenedores ARM64 en sistemas x86 sin una configuración multiplataforma adecuada

Solución: construya contenedores compatibles con ARM64. Puedes considerar el uso de buildx para compilaciones multiplataforma. Como alternativa, puedes usar. CodeBuild Para ver un código de ejemplo, consulte Amazon Bedrock AgentCore Samples.

¿Cuáles son los requisitos para los contenedores Docker que se utilizan con Amazon Bedrock Runtime? AgentCore

Consulte los requisitos de Amazon Bedrock AgentCore Runtime para obtener más información.

En resumen, su contenedor Docker debe cumplir los siguientes requisitos:

Mi herramienta de larga duración se interrumpe después de 15 minutos

Para obtener más información, consulte Gestión de agentes asíncronos y de larga ejecución con Amazon Bedrock Amazon Bedrock Runtime para obtener más información. AgentCore

Cuando esto ocurre: durante operaciones de agentes prolongadas o flujos de trabajo complejos

Por qué ocurre esto: Amazon Bedrock finaliza AgentCore automáticamente las sesiones tras 15 minutos de inactividad. La plataforma determina la actividad a partir de la /ping respuesta: los informes de una sesión HealthyBusy se mantienen activos, mientras que los informes de una sesión Healthy se consideran inactivos y su tiempo de inactividad se mide desde la status última vez que se modificó (consulte el campo siguiente). time_of_last_update

Solución: asegúrese de que su /ping terminal vuelva a funcionar HealthyBusy mientras se está trabajando en segundo plano:

{"status": "HealthyBusy"}

Si utiliza el AgentCore SDK de Bedrock, la respuesta al ping se gestiona automáticamente. Para implementaciones personalizadas, asegúrese de que su controlador de ping regrese HealthyBusy durante el procesamiento.

Mis sesiones inactivas no se publican y estoy agotando mi cuota de sesiones

Cuando esto ocurre: el recuento de sesiones aumenta continuamente con la carga y las sesiones no se liberan después del tiempo de espera de inactividad (por ejemplo, se maxVms producen erroresServiceQuotaExceededException/durante una ráfaga de invocaciones), aunque cada sesión esté inactiva.

Por qué sucede esto: cuando se informa de una sesiónHealthy, la plataforma mide cuánto tiempo ha estado inactiva desde el time_of_last_update campo de /ping respuesta, lo que debe reflejar cuándo se modificó por última vez. status Si tu controlador de ping se ajusta time_of_last_update a la hora actual de cada ping, el tiempo de inactividad registrado se sigue restableciendo, lo que impide que se active el tiempo de espera de inactividad. De este modo, las sesiones permanecerán activas hasta que MaxLifetime se agote tu cuota de sesiones.

Solución: time_of_last_update actualízalo solo cuando status realmente cambie, u omítelo por completo para que la plataforma registre los cambios de estado por sí sola:

{"status": "Healthy"}

Si utilizas el AgentCore SDK de Bedrock, actualiza a la última versión, en la que la respuesta al ping se gestiona correctamente. Como medida provisional, las llamadas StopRuntimeSession liberan las sesiones bloqueadas.

¿Cómo accedo al tiempo de ejecución SessionId de mi código de agente para etiquetar o agrupar recursos?

Cuando esto ocurre: desea agrupar, etiquetar o rastrear los recursos (por ejemplo, objetos de S3 o registros) según la sesión de tiempo de ejecución del agente actual.

Soluciones:

Solución 1: Para los agentes que utilizan el AgentCore SDK de Amazon Bedrock para Bedrock, utilícelo context.session_id desde el punto de entrada de su agente

@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

Solución 2: Para servidores HTTP personalizados en tiempo de ejecución

El ID de la sesión en tiempo de ejecución se incluye en este encabezado HTTP. Analícelo a partir de la solicitud entrante y utilícelo para etiquetar, correlacionar o propagar en sentido descendente.

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

Tengo RuntimeClientError (403) problemas

Problema

Cuando intentas invocar el tiempo de ejecución de tu agente, recibes un valor de 403 RuntimeClientError pulgadas.

Causas

Este error suele producirse debido a:

Resolución

Siga estos pasos para resolver el problema:

Me faltan registros o están vacíos CloudWatch

Problema

Encuentras errores pero no ves ningún inicio de sesión relevante CloudWatch.

Solución

Prueba estos enfoques para diagnosticar el problema:

Tengo problemas con el formato de carga

Problema

La invocación del tiempo de ejecución del agente falla aunque el contenedor se inicie correctamente.

Resolución

Siga estos pasos para resolver los problemas de formato de la carga útil:

Necesito ayuda para entender los códigos de error HTTP

Problema

Su agente devuelve códigos de error HTTP que son difíciles de interpretar.

Ejemplo de mensaje de error

Es posible que veas un error como el siguiente:

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

Resolución

Estos son los códigos de error más comunes y sus significados:

Necesito recomendaciones para probar a mi agente

Para depurar sistemáticamente los problemas de tiempo de ejecución del agente:

Pruebe primero localmente

Antes de realizar la implementación en AgentCore Runtime:

Compare las cargas útiles

Garantice la coherencia entre los entornos:

Necesito ayuda para depurar problemas con los contenedores

Si sospecha que hay problemas relacionados con los contenedores:

Extraiga y ejecute localmente

Pruebe la imagen del contenedor en su máquina local:

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

Prueba con curl

Envía las solicitudes de prueba a tu contenedor local:

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

Comprueba los registros del contenedor

Examine la salida del contenedor para ver si hay errores:

docker logs <container-id>

Necesito ayuda para solucionar problemas con los agentes del protocolo MCP

En el caso de los agentes de protocolo MCP, siga estos pasos específicos de solución de problemas:

Verifique la ruta del punto final

Los servidores MCP deberían escuchar 0.0.0.0:8000/mcp/

Utilice el Inspector MCP

Pruebe con la herramienta Inspector MCP:

Problemas de autenticación

Compruebe la configuración de autenticación:

Necesito ayuda para solucionar problemas de streaming bidireccional mediante WebSocket

Para la transmisión bidireccional mediante WebSocket agentes, sigue estos pasos específicos de solución de problemas:

Compruebe la configuración del punto final

WebSocket los agentes deben ejecutarse en el puerto 8080 y servir WebSocket las conexiones en la ruta /ws

Realice pruebas locales con una complejidad incremental

Comience con pruebas locales sencillas antes de la implementación:

Problemas de autenticación

Compruebe la configuración de autenticación de los agentes desplegados:

Problemas de conexión comunes

Abordar los problemas de WebSocket conexión más comunes:

Los cambios en mi código no se reflejan en las sesiones existentes

Problema

Has actualizado el tiempo de ejecución del agente con un código nuevo, pero las sesiones existentes siguen utilizando la versión anterior.

¿Por qué sucede esto

Cada sesión de microVM se crea con los activos de código (agentRuntimeArtifact) que se desplegaron en el momento de la creación de la sesión. Una vez establecida una sesión, se sigue utilizando esa versión del código hasta que finalice la sesión, incluso cuando los activos de código se actualicen como parte de la UpdateAgentRuntimeoperación.

Solución

Para acceder al código actualizado, utilice un nuevo identificador de sesión.

Faltan intervalos cuando se invoca mi tiempo de ejecución desde una función Lambda

Cuando esto ocurre: Al invocar AgentCore Runtime desde una función Lambda

Por qué sucede esto: Lambda genera su propio encabezado. X-Amzn-Trace-Id Si el rastreo Lambda lo ha hechoSampled=0, este contexto sin muestrear se propaga a AgentCore Runtime y el tiempo de ejecución omite la generación de intervalos para esa invocación.

Solución:

El montaje de mis archivos S3 o EFS falla y aparece el mensaje «Acceso denegado»

Cuando esto ocurre: durante la invocación de un agente con archivos S3 o almacenamiento EFS configurado

Por qué ocurre esto: a la función de ejecución le faltan los permisos de sistema de archivos necesarios. Para obtener más información sobre la configuración del almacenamiento persistente, consulte Configuraciones del sistema de archivos para AgentCore Runtime.

Solución:

En el caso de S3 Files, asegúrese de que su función de ejecución tenga:

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

En el caso de EFS, asegúrese de que su función de ejecución cuente con:

{
  "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>"
    }
  }
}

Omita s3files:ClientWrite o elasticfilesystem:ClientWrite si su agente solo necesita acceso de lectura.

El montaje de mis archivos S3 o EFS falla con "ResourceNotFound»

Cuando esto ocurre: durante la invocación de un agente con archivos S3 o almacenamiento EFS configurado

Por qué ocurre esto: el sistema de archivos o el punto de acceso se eliminaron después de crear el agente, o los ID son incorrectos.

Solución:

Se agota el tiempo de espera para el montaje de My S3 Files o EFS

Cuando esto ocurre: durante la invocación de un agente con archivos S3 o almacenamiento EFS configurado. La invocación puede tardar más de lo habitual antes de fallar.

Por qué ocurre esto: la configuración de la red de la VPC bloquea el tráfico NFS (puerto 2049) entre el procesamiento del agente y los destinos de montaje del sistema de archivos.

Solución:

Cuando escribo en mi sistema de archivos montado, aparece el mensaje «Permiso denegado»

Cuando esto ocurre: la invocación del agente se realiza correctamente y el agente puede leer los archivos desde el montaje, pero la escritura falla y aparece el mensaje «Permiso denegado»

Por qué ocurre esto: o bien al rol de IAM le faltan permisos de escritura, o bien los permisos POSIX del directorio establecidos durante la creación del punto de acceso no permiten la escritura para el usuario del agente.

Solución:

Mi contenedor no se inicia con el error HTTP 424 en imágenes de capa alta

Cuando esto ocurre: tus InvokeAgentRuntime llamadas devuelven el protocolo HTTP 424 (dependencia fallida) y se muestran Failed to mount overlay: No such file or directory los registros de tu agente. Esto ocurre cuando la imagen del contenedor tiene más de 53 capas y utiliza una directiva USER no numérica (por ejemplo, USER myuser en lugar deUSER 1000).

Por qué sucede esto: las imágenes de contenedores con muchas capas combinadas con directivas USER no numéricas pueden provocar errores de inicialización.

Solución: utilice una de estas soluciones alternativas:

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

Prácticas recomendadas

Habilite un registro completo

Implemente un registro exhaustivo en su agente:

Utilice un manejo estructurado de errores

Implemente informes de errores claros:

Pruebe los cambios incrementales

Siga un enfoque de prueba metódico:

Supervise el rendimiento

Configure la supervisión para su agente: