

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](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html) y [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html), 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](runtime-how-it-works.md#runtime-platform-versions).

**Topics**
+ [Requisitos](#runtime-lifecycle-hooks-requirements)
+ [Cómo funciona una llamada de enlace](#runtime-lifecycle-hooks-how-it-works)
+ [Configura los ganchos del ciclo](#runtime-lifecycle-hooks-configure)
+ [Ganchos compatibles](#runtime-lifecycle-hooks-supported)
+ [Ver registros de ganchos](#runtime-lifecycle-hooks-logs)

## Requisitos
<a name="runtime-lifecycle-hooks-requirements"></a>
+ 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
<a name="runtime-lifecycle-hooks-how-it-works"></a>

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](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).

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

### Acciones de enganche
<a name="runtime-lifecycle-hooks-actions"></a>

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

#### Acciones HTTP
<a name="runtime-lifecycle-hooks-http-actions"></a>

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._~/-]*$`. <br />+  Está en forma canónica. No termina en `/` (excepto por el camino `/` en sí mismo), y no contiene `//`, o `.` o `..` segmentos. <br />+  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](#runtime-lifecycle-hooks-routes).  | 
|  `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](runtime-service-contract.md#runtime-reserved-ports). 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) <br />+   `GET /ws`  <br />+   `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](runtime-configure-invocation.md).

**nota**  
Si el tiempo de ejecución de su agente usa [puntos finales de sesión](runtime-session-endpoints.md), 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
<a name="runtime-lifecycle-hooks-configure"></a>

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](#runtime-lifecycle-hooks-warmup). Sustituya la región, el URI de la imagen del contenedor y el ARN del rol de ejecución por sus valores.

**Example**  

```python
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}")
```

```bash
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
<a name="runtime-lifecycle-hooks-supported"></a>


| 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](#runtime-lifecycle-hooks-warmup). | 

### Construye un gancho de calentamiento
<a name="runtime-lifecycle-hooks-warmup"></a>

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
<a name="runtime-lifecycle-hooks-warmup-handler"></a>

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.

```python
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:

```bash
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](runtime-v2-optimize.md#runtime-v2-optimize-warmup).

## Ver registros de ganchos
<a name="runtime-lifecycle-hooks-logs"></a>

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](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).