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.
Temas
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
hooksConfigurationconcapacityProviderConfiguration, la solicitud falla con unValidationException.
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 |
|---|---|---|---|
|
|
Cadena |
Sí |
El camino que AgentCore Runtime envía la solicitud a. La ruta debe cumplir estas reglas:
|
|
|
Entero |
No |
El puerto que AgentCore Runtime envía la solicitud a. El rango admitido es |
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.
| Protocolo | Rutas que un gancho no puede usar |
|---|---|
|
Todos los protocolos |
|
|
MCP |
|
|
A2A |
|
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.
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
403yAccessDeniedantes 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
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 |
|---|---|---|---|
|
|
|
Mientras prepara a su agente, durante |
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 |
|---|---|---|
|
|
En primer lugar, después de que su agente apruebe su |
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í. |
|
|
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
/pingresponsivo. Su servidor debe seguir respondiendo/pingmientras 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
2xxsolo 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.