Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Solucionar problemas de tiempo de ejecución AgentCore

Este tema de solución de problemas le ayuda a identificar y resolver los problemas más 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 los agentes.

Las invocaciones de mi agente fallan con el mensaje «Este tiempo de ejecución no es» MMDSv2-enabled ValidationException

Cuando esto ocurre: cuando se invoca el tiempo de ejecución de un agente medianteInvokeAgentRuntime,ExecuteCommand,InvokeAgentRuntimeWithWebSocketStream, InvokeAgentRuntimeCommandShell o GetAgentCard

Por qué ocurre esto: a partir del 30 de junio de 2026, Amazon Bedrock AgentCore Runtime requiere que todos los tiempos de ejecución de los agentes utilicen MMDSv2 (versión 2 del servicio de metadatos de MicroVM). El servicio rechaza las invocaciones dirigidas a los tiempos de ejecución sin metadataConfiguration establecer o con el valor de o. requireMMDSV2 false null

Solución: llame UpdateAgentRuntime con la opción requireMMDSV2 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 errores de tiempo de espera de 504 Gateway

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

Por qué ocurre esto: hay varios factores que pueden impedir que el agente responda dentro del tiempo de espera

Hay varios factores que pueden provocar esto:

Mi compilación de Docker falla con el mensaje «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é ocurre esto: Problemas de autenticación pública de 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

Aparece el error «Servicio desconocido: 'bedrock-agent-core-runtime'» cuando uso boto3

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

Por qué ocurre esto: biblioteca boto3 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 versiones más recientes de boto3 y botocore:

pip install --upgrade boto3 botocore

# Minimum versions: boto3 1.39.8+, botocore 1.33.8+

Cuando intento crear un Amazon Bedrock Runtime, aparece AccessDeniedException «» AgentCore

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

Por qué ocurre esto: su usuario carece de permisos o el rol de ejecución no está configurado correctamente para Amazon Bedrock AgentCore

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

Mi compilación de Docker falla con el «error de formato exec/bin/sh: exec»

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

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

Solución: cree contenedores compatibles con ARM64. Puedes considerar usar buildx para compilaciones multiplataforma. Alternativamente, puedes usar. CodeBuild Para ver un código de ejemplo, consulte los AgentCore ejemplos de Amazon Bedrock.

¿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 estos requisitos:

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

Para obtener más información, consulte Gestionar agentes asincrónicos y de larga duración con Amazon Bedrock AgentCore Runtime para obtener más información.

Cuando esto ocurre: durante operaciones de agentes de larga duración o flujos de trabajo complejos

Por qué ocurre esto: Amazon Bedrock finaliza AgentCore automáticamente las sesiones después de 15 minutos de inactividad. La plataforma determina la actividad a partir de la /ping respuesta: un informe de sesión HealthyBusy se mantiene activo, mientras que un informe de sesión Healthy se considera inactivo 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 de ping se gestiona automáticamente. Para las implementaciones personalizadas, asegúrese de que su controlador de ping regrese durante el procesamiento. HealthyBusy

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

Cuando esto ocurre: el número de sesiones aumenta continuamente bajo carga y las sesiones no se liberan una vez transcurrido el tiempo de espera de inactividad (por ejemplo, se produce un maxVms error deServiceQuotaExceededException/durante una ráfaga de invocaciones), aunque cada sesión esté inactiva.

Por qué ocurre esto: Cuando una sesión informaHealthy, la plataforma mide el tiempo que ha estado inactiva a partir del time_of_last_update campo de tu /ping respuesta, que debe reflejar cuándo se modificó por última vez. status Si tu controlador de ping establece time_of_last_update la hora actual en cada ping, el tiempo de inactividad registrado se sigue restableciendo, lo que evita que se active el tiempo de espera de inactividad. De este modo, las sesiones permanecen activas hasta que MaxLifetime se agote la cuota de sesión.

Solución: time_of_last_update actualízalas solo cuando status realmente cambien, u omítelas por completo para que la plataforma haga un seguimiento de los cambios de estado por sí sola:

{"status": "Healthy"}

Si utilizas el AgentCore SDK de Bedrock, actualízalo a la versión más reciente, en la que la respuesta del ping se gestione correctamente. Como medida provisional, las llamadas StopRuntimeSession liberan las sesiones bloqueadas.

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

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

Soluciones:

Solución 1: Para los agentes que utilizan el AgentCore SDK de Amazon Bedrock de 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 en tiempo de ejecución personalizados

El identificador de la sesión en tiempo de ejecución se pasa a este encabezado HTTP. Analízalo a partir de la solicitud entrante y utilízalo 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 RuntimeClientError «"» 403.

Causas

Este error se produce normalmente debido a:

Resolución

Sigue estos pasos para resolver el problema:

Me faltan registros o están vacíos CloudWatch

Problema

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

Solución

Prueba estos métodos para diagnosticar el problema:

Tengo problemas con el formato de la carga

Problema

La invocación del agente en tiempo de ejecución 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 ejecución del agente:

Realice primero una prueba local

Antes de realizar la implementación en AgentCore Runtime:

Compara las cargas útiles

Garantice la coherencia entre los entornos:

Necesito ayuda para solucionar problemas con los contenedores

Si sospecha que hay problemas relacionados con los contenedores:

Extraiga y ejecute localmente

Pruebe la imagen de su 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!"}}'

Revisa los registros de los contenedores

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

Para 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 MCP Inspector

Realice una prueba con la herramienta MCP Inspector:

Problemas de autenticación

Compruebe la configuración de autenticación:

Necesito ayuda para solucionar el problema de la transmisión bidireccional utilizando WebSocket

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

Verifique la configuración del punto final

WebSocket los agentes deben ejecutarse en el puerto 8080 y ofrecer WebSocket 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

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

Los cambios que he hecho en el código no se reflejan en las sesiones existentes

Problema

Actualizó el tiempo de ejecución de su agente con un código nuevo, pero las sesiones existentes siguen usando la versión anterior.

Por qué ocurre esto

Cada sesión de microVM se crea con los activos de código (agentRuntimeArtifact) que se implementaron en el momento de la creación de la sesión. Una vez establecida la sesión, continúa usando esa versión del código hasta que finalice la sesión, incluso cuando los activos del código se actualicen como parte de la ejecución de la UpdateAgentRuntime operació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 de Lambda

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

Por qué sucede esto: Lambda genera su propio encabezado. X-Amzn-Trace-Id Si el seguimiento de Lambda lo tieneSampled=0, este contexto sin muestrear se propaga a AgentCore Runtime y el Runtime 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: al rol de ejecución le faltan los permisos necesarios del sistema de archivos. 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 los archivos S3, 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>"
    }
  }
}

Para EFS, asegúrese de que su rol de ejecución tenga:

{
  "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 mis archivos S3 o EFS

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

Por qué ocurre esto: la configuración de red de la VPC bloquea el tráfico de 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 del montaje, pero la escritura falla y dice «Permiso denegado»

Por qué ocurre esto: el rol de IAM no tiene permisos de escritura o 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 debido al error HTTP 424 en las imágenes de capa superior

Cuando esto ocurre: las InvokeAgentRuntime llamadas devuelven el protocolo HTTP 424 (dependencia fallida) y se muestran Failed to mount overlay: No such file or directory los registros de los agentes. Esto ocurre cuando la imagen de tu 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 contenedor 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'

Mi proveedor de capacidad está en el estado CREATE_FAILED

Cuando esto ocurre: después de CreateCapacityProvider solicitar el tipo de procesamiento de la instancia, el proveedor de capacidad no contacta ACTIVE y, en su lugar, ingresa. CREATE_FAILED

Por qué ocurre esto: un proveedor de capacidad depende de varios recursos (como una plantilla de lanzamiento y un grupo de Auto Scaling) que el rol de operador del proveedor de capacidad debe poder crear. La falta de permisos en esa función provoca un error de creación.

Solución: llame a la GetCapacityProvider API para recuperar el motivo del error en el statusReason campo. statusReasonIdentifica los recursos que no se pudieron crear. Otorgue al rol de operador del proveedor de capacidad los permisos que necesita para crear esos recursos y, a continuación, vuelva a crear el proveedor de capacidad. Para obtener más información sobre la función de operador, consulte el modelo de seguridad y los permisos para las instancias en tiempo de ejecución.

Mis agentes en Instances no tienen acceso a sus credenciales

Cuando esto ocurre: un agente que ejecuta una sesión de Instancias no puede obtener las credenciales que necesita para llamar a AWS los servicios.

Por qué ocurre esto: falta la función de ejecución en tiempo de ejecución o no la puede asumir AgentCore.

Solución: asegúrese de que la función de ejecución que configuró para su tiempo de ejecución exista y permita bedrock-agentcore.amazonaws.com realizar llamadassts:AssumeRole. Para obtener más información, consulte los permisos del rol de ejecución de Amazon Bedrock AgentCore Runtime.

Prácticas recomendadas

Habilite el registro completo

Implemente un registro exhaustivo en su agente:

Utilice el manejo estructurado de errores

Implemente informes de errores claros:

Pruebe los cambios incrementales

Siga un enfoque de pruebas metódico:

Supervise el rendimiento

Configure la supervisión para su agente: