View a markdown version of this page

Configurar los ganchos del ciclo de vida para AgentCore Tiempo de ejecución - lecho rocoso amazónico AgentCore

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.

Configurar los ganchos del ciclo de vida para AgentCore Tiempo de ejecución

Un enlace de ciclo de vida es un punto final de su contenedor que AgentCore El tiempo de ejecución llama a un punto específico del ciclo de vida del agente. Usa enlaces para ejecutar tu propio código en esos momentos, por ejemplo, para preparar al agente antes de que comiencen las sesiones. Los ganchos se configuran con hooksConfiguration campo de CreateAgentRuntime y UpdateAgentRuntime, agrupados por la fase del ciclo de vida a la que pertenecen.

Los enlaces de ciclo de vida están disponibles para los tiempos de ejecución de los agentes que utilizan la versión V2 de la plataforma en micromáquinas virtuales. Para obtener más información, consulte Versiones de plataforma.

Requisitos

  • El tiempo de ejecución del agente debe utilizar la versión V2 de la plataforma. En la V1, la solicitud falla con un ValidationException.

  • El tiempo de ejecución del agente debe utilizar el tipo de procesamiento MicroVMS. Los ganchos de ciclo de vida no se admiten en las instancias: si los combinas hooksConfiguration con capacityProviderConfiguration, la solicitud falla con un ValidationException.

Cómo funciona una llamada de enlace

Cuando el tiempo de ejecución de su agente llega a un punto de enganche en su ciclo de vida, AgentCore Runtime ejecuta la acción del gancho una vez. Realiza una única solicitud a tu contenedor y espera a que tu implementación notifique que se ha realizado correctamente dentro del límite de tiempo establecido por el gancho. AgentCore Runtime no vuelve a intentar una llamada de enlace.

Si la llamada falla o no se realiza correctamente dentro del límite de tiempo, se produce un error en la operación que activó el enlace. Por ejemplo, cuando se produce un error en un enlace de compilación, el tiempo de ejecución pasa a CREATE_FAILED o UPDATE_FAILED con un failureReason que describe el fracaso. Para obtener más información, consulte Solucione problemas relacionados con el ciclo de vida.

La forma en que su implementación informe sobre el éxito depende de la acción del gancho.

Acciones de enganche

Cada gancho tiene una acción, que define cómo AgentCore Runtime llama a tu contenedor.

Acciones HTTP

Una acción HTTP envía una solicitud HTTP al path y port que elijas, en un servidor de tu contenedor. Su implementación informa sobre el éxito al devolver cualquier 2xx código de estado una vez finalizado su trabajo. Cualquier otro código de estado, o una conexión fallida, hace fallar la llamada. Cada solicitud puede incluir encabezados que identifiquen la llamada. Cada enlace muestra los encabezados y valores que envía.

Los ganchos admiten el httpPost acción, que envía un POST solicitud. Lo configuras en los ganchos action.httpPost campo, que tiene los siguientes campos.

Campo Tipo Obligatorio Descripción

path

Cadena

Sí

El camino que AgentCore Runtime envía la solicitud a. La ruta debe cumplir estas reglas:

  • Contiene de 1 a 32 caracteres y coincide con el patrón ^/[A-Za-z0-9._~/-]*$.

  • Está en forma canónica. No termina en / (excepto por el camino / en sí mismo), y no contiene //, o . o .. segmentos.

  • No entra en conflicto con una ruta que AgentCore Runtime ya usa el mismo puerto. Para obtener más información, consulte Rutas de plataforma.

port

Entero

No

El puerto que AgentCore Runtime envía la solicitud a. El rango admitido es 8000—12000, inclusivo. Elija un puerto que no sea el puertos de plataforma reservados. Si no especificas un puerto, el predeterminado es el puerto de servicio de tu agente: protocolConfiguration.port si lo configuras; de lo contrario, el puerto predeterminado del protocolo (8080 para HTTP y AG-UI, 8000 para MCP, y 9000 para A2A).

La ruta de un enlace es su método HTTP, su ruta y su puerto. No puede coincidir con una ruta que AgentCore Runtime ya se utiliza en el puerto de servicio de su agente. En la siguiente tabla se enumeran estas rutas de plataforma.

Rutas de plataforma que un gancho no puede usar
Protocolo Rutas que un gancho no puede usar

Todos los protocolos

  • POST a la ruta de invocación: protocolConfiguration.path si lo configuras; de lo contrario, el protocolo predeterminado (/invocations para HTTP y AG-UI, /mcp para MCP, y / para A2A)

  • GET /ws

  • GET /ping

MCP

POST /mcp, incluso si cambias la ruta de invocación

A2A

GET /.well-known/agent-card.json

Los conflictos comparan el método con la ruta. Por ejemplo, POST /ping es una ruta de enlace válida, porque AgentCore usos en tiempo de ejecución GET /ping. Para ver el puerto de servicio y la ruta de invocación, consulte Configure el puerto de servicio y la ruta de invocación de su agente.

nota

Si el tiempo de ejecución de su agente usa puntos finales de sesión, AgentCore Runtime protege tus enlaces de las solicitudes de punto final de sesión:

  • Una solicitud que apunta a la ruta de un enlace se rechaza mediante HTTP 403 y AccessDenied antes de que llegue a su contenedor. La coincidencia de rutas ignora las mayúsculas y minúsculas y trata las grafías equivalentes comunes de una ruta como si fueran la misma ruta. Estas incluyen barras repetidas o al final, . y .. segmentos, caracteres codificados en porcentaje y ; parámetros.

  • Los encabezados de los ganchos están reservados. AgentCore Runtime los elimina de las solicitudes de punto final de sesión, por lo que la aplicación recibe los encabezados de enlace solo en las llamadas de enlace.

Configura los ganchos del ciclo

Especifique hooksConfiguration al crear o actualizar el tiempo de ejecución de un agente. En el siguiente ejemplo, se crea un tiempo de ejecución de la versión 2 con un enlace de preparación de compilación que llama POST /warmup en el puerto 8080. Para ver lo que hace el anzuelo, consulta Construye un gancho de calentamiento. Sustituya la región, el URI de la imagen del contenedor y el ARN del rol de ejecución por sus valores.

ejemplo
AWS SDK
import boto3 client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') try: response = client.create_agent_runtime( agentRuntimeName='my_agent_runtime', agentRuntimeArtifact={ 'containerConfiguration': { 'containerUri': '123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest' } }, networkConfiguration={'networkMode': 'PUBLIC'}, roleArn='arn:aws:iam::123456789012:role/AgentRuntimeRole', platformVersion='V2', hooksConfiguration={ 'build': { 'warmup': { 'action': { 'httpPost': { 'path': '/warmup', 'port': 8080 } } } } } ) print(f"Agent runtime created: {response['agentRuntimeArn']}") except client.exceptions.ValidationException as e: print(f"Validation error: {e}")
AWS CLI
aws bedrock-agentcore-control create-agent-runtime \ --agent-runtime-name "my_agent_runtime" \ --role-arn "arn:aws:iam::123456789012:role/AgentRuntimeRole" \ --agent-runtime-artifact '{ "containerConfiguration": { "containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest" } }' \ --network-configuration '{"networkMode": "PUBLIC"}' \ --platform-version V2 \ --hooks-configuration '{ "build": { "warmup": { "action": { "httpPost": {"path": "/warmup", "port": 8080} } } } }'

UpdateAgentRuntime reemplaza toda la configuración del enlace. Incluir hooksConfiguration en cada solicitud de actualización para la que quieras conservar tus enlaces. Para eliminar tus ganchos, llama UpdateAgentRuntime sin hooksConfiguration.

Ganchos compatibles

Fase Enlace ¿Cuándo AgentCore Runtime lo llama Úselo para

build

warmup

Mientras prepara a su agente, durante CreateAgentRuntime y UpdateAgentRuntime

Prepare la memoria y el disco para que las sesiones comiencen más rápido. Para obtener más información, consulte Construye un gancho de calentamiento.

Construye un gancho de calentamiento

AgentCore Runtime llama al gancho de calentamiento de compilación mientras prepara a tu agente, durante CreateAgentRuntime y UpdateAgentRuntime, antes de que llegue el tiempo de ejecución READY. Realiza dos llamadas, en este orden, e indica a tu implementación qué llamada es:

Tipo de calentamiento Order Solución

memory

En primer lugar, después de que su agente apruebe su /ping chequeo médico

Cargue en la memoria lo que necesita cada sesión, como importaciones, modelos y cachés. Cada nueva instancia comienza con lo que se carga aquí.

disk

Segundo

Lee los archivos que lee tu agente cuando se inicia una sesión. AgentCore Runtime usa estas lecturas para que esos archivos estén disponibles más rápido para las nuevas sesiones.

Con una acción HTTP, AgentCore Runtime envía el tipo de calentamiento en X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type encabezado, con el valor memory o disk.

Las dos llamadas comparten un límite de tiempo de 120 segundos en total. Porque el memory la llamada se ejecuta primero, el disk la llamada recibe la hora en que memory la llamada sale. Por ejemplo, si el memory la llamada tarda 50 segundos, el disk la llamada dura 70 segundos. No puedes cambiar este límite.

Un gancho de calentamiento puede añadir hasta 120 segundos al tiempo que CreateAgentRuntime y UpdateAgentRuntime tomar para llegar READY. Cada línea de registro de calentamiento puede aparecer más de una vez para una creación o actualización.

Escribe el controlador de calentamiento

Su controlador de calentamiento se ejecuta en el servidor de su agente, junto con /ping y su controlador de invocaciones:

  • Mantenga /ping responsivo. Su servidor debe seguir respondiendo /ping mientras se ejecuta el calentamiento. No bloquees el único hilo de tu servidor dentro del controlador de calentamiento. Ejecuta el trabajo en un hilo o proceso independiente, o usa un servidor que gestione las solicitudes de forma simultánea.

  • Regreso 2xx solo después de que el trabajo esté terminado. Lo que has cargado al responder es el punto con el que comienzan las sesiones.

La siguiente aplicación FastAPI sirve /ping, /invocations, y un gancho de calentamiento en POST /warmup en el puerto 8080. Ejecuta el trabajo de preparación en un hilo de trabajo, por lo que el servidor sigue respondiendo /ping. Reemplazar load_shared_state y STARTUP_FILES con el trabajo y los archivos propios de su agente.

import asyncio from fastapi import FastAPI, Request, Response app = FastAPI() # Files that each session reads when it starts. STARTUP_FILES = ["/app/models/tokenizer.json", "/app/config/agent.json"] def load_shared_state(): # Load what every session needs into memory, such as heavy imports, # model weights, and caches. ... def read_startup_files(): # Read the files that a session reads when it starts, so that new # sessions can use them faster. for path in STARTUP_FILES: with open(path, "rb") as f: while f.read(1024 * 1024): pass @app.get("/ping") def ping(): return {"status": "Healthy"} @app.post("/warmup") async def warmup(request: Request): # Header lookup in Starlette and FastAPI is case-insensitive. warmup_type = request.headers.get( "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type", "" ).lower() # Run the work in a worker thread so that /ping keeps answering. if warmup_type == "memory": await asyncio.to_thread(load_shared_state) elif warmup_type == "disk": await asyncio.to_thread(read_startup_files) # Respond only after the work is done. return Response(status_code=200) @app.post("/invocations") async def invoke(request: Request): payload = await request.json() # Per-request work runs here on every session. return {"response": payload.get("prompt", "")}

Si guardas la aplicación como app.py, iníciala en tu contenedor con el siguiente comando:

uvicorn app:app --host 0.0.0.0 --port 8080

Para saber qué incluir en cada llamada, consulte Prepare la memoria y el disco con un enlace de ciclo de vida.

Ver registros de ganchos

AgentCore Runtime escribe el progreso y el resultado de cada llamada de build hook en el grupo de registros de tu tiempo de ejecución, /aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT, en secuencias de registro cuyos nombres comienzan por build-logs-. Cada línea comienza con [LIFECYCLE-HOOK <epoch-milliseconds>], seguido de [LIFECYCLE] para progresar o [ERROR] en caso de fracasos. Para conocer las líneas y cómo actuar en consecuencia, consulte Solucione problemas relacionados con el ciclo de vida.