

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Configurer les hooks de cycle de vie pour AgentCore Durée d'exécution

Un hook de cycle de vie est un point final de votre conteneur qui AgentCore Les appels d'exécution surviennent à un moment précis du cycle de vie de l'environnement d'exécution de votre agent. Utilisez des hooks pour exécuter votre propre code à ces moments, par exemple pour préparer votre agent avant le début des sessions. Vous configurez les hooks avec `hooksConfiguration` domaine de [CreateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html) et [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html), regroupés selon la phase du cycle de vie à laquelle ils appartiennent.

Les hooks Lifecycle sont disponibles pour les environnements d'exécution des agents qui utilisent la version V2 de la plate-forme sur des micromachines virtuelles. Pour plus d'informations, voir [Versions de la plateforme](runtime-how-it-works.md#runtime-platform-versions).

**Topics**
+ [Exigences](#runtime-lifecycle-hooks-requirements)
+ [Comment fonctionne un hook call](#runtime-lifecycle-hooks-how-it-works)
+ [Configurer les hooks du cycle de vie](#runtime-lifecycle-hooks-configure)
+ [Crochets pris en charge](#runtime-lifecycle-hooks-supported)
+ [Afficher les journaux des crochets](#runtime-lifecycle-hooks-logs)

## Exigences
<a name="runtime-lifecycle-hooks-requirements"></a>
+ L'environnement d'exécution de l'agent doit utiliser la version V2 de la plateforme. Sur la V1, la demande échoue avec un `ValidationException`.
+ L'environnement d'exécution de l'agent doit utiliser le type de calcul MicroVMS. Les hooks Lifecycle ne sont pas pris en charge sur les instances : si vous combinez `hooksConfiguration` avec `capacityProviderConfiguration`, la demande échoue avec un `ValidationException`.

## Comment fonctionne un hook call
<a name="runtime-lifecycle-hooks-how-it-works"></a>

Lorsque l'exécution de votre agent atteint un point critique dans son cycle de vie, AgentCore Runtime exécute l'action du hook une fois. Il envoie une seule demande à votre conteneur et attend que votre implémentation signale le succès dans les délais impartis par le hook. AgentCore L'environnement d'exécution ne réessaie pas un appel hook.

Si l'appel échoue ou n'aboutit pas dans le délai imparti, l'opération qui a déclenché le hook échoue. Par exemple, lorsqu'un hook de génération échoue, le moteur d'exécution passe à `CREATE_FAILED` ou `UPDATE_FAILED` avec un `failureReason` qui décrit l'échec. Pour plus d'informations, voir [Résoudre les problèmes liés au cycle de vie](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).

La réussite de votre implémentation dépend de l'action du hook.

### Actions liées aux crochets
<a name="runtime-lifecycle-hooks-actions"></a>

Chaque crochet possède une action, qui définit comment AgentCore Runtime appelle votre conteneur.

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

Une action HTTP envoie une requête HTTP au `path` et `port` que vous choisissez, sur un serveur de votre conteneur. Vos rapports de mise en œuvre sont réussis en renvoyant tout `2xx` code d'état une fois son travail terminé. Tout autre code d'état ou un échec de connexion entraîne l'échec de l'appel. Chaque demande peut inclure des en-têtes identifiant l'appel. Chaque hook répertorie les en-têtes et les valeurs qu'il envoie.

Les crochets soutiennent le `httpPost` action, qui envoie un `POST` demande. Vous le configurez dans le hook `action.httpPost` champ, qui contient les champs suivants.


| Champ | Type | Obligatoire | Description | 
| --- | --- | --- | --- | 
|  `path`  | Chaîne | Oui | Le chemin qui AgentCore Runtime envoie la demande à. Le chemin doit respecter les règles suivantes :+  Il contient 1 à 32 caractères et correspond au modèle `^/[A-Za-z0-9._~/-]*$`. <br />+  C'est sous forme canonique. Cela ne s'arrête pas à `/` (sauf pour le chemin) `/` lui-même), et il ne contient pas `//`, ou `.` ou `..` segments. <br />+  Cela n'entre pas en conflit avec un itinéraire qui AgentCore Runtime l'utilise déjà sur le même port. Pour plus d'informations, voir [Routes de la plateforme](#runtime-lifecycle-hooks-routes).  | 
|  `port`  | Entier | Non | Le port qui AgentCore Runtime envoie la demande à. La plage prise en charge est `8000`—`12000`, inclus. Choisissez un port autre que [ports de plate-forme réservés](runtime-service-contract.md#runtime-reserved-ports). Si vous ne spécifiez aucun port, le port par défaut est le port de service de votre agent : `protocolConfiguration.port` si vous le définissez, sinon le port par défaut du protocole (`8080` pour HTTP et AG-UI, `8000` pour MCP, et `9000` pour A2A). | 

La route d'un hook est sa méthode, son chemin et son port HTTP. Il ne peut pas correspondre à un itinéraire qui AgentCore Runtime utilise déjà le port de service de votre agent. Le tableau suivant répertorie les itinéraires de ces plateformes.


**Routes de plateforme qu'un hook ne peut pas utiliser**  

|  Protocole | Routes qu'un hameçon ne peut pas emprunter | 
| --- | --- | 
| Tous les protocoles |  +   `POST` vers le chemin d'invocation : `protocolConfiguration.path` si vous le définissez, sinon c'est la valeur par défaut du protocole (`/invocations` pour HTTP et AG-UI, `/mcp` pour MCP, et `/` pour A2A) <br />+   `GET /ws`  <br />+   `GET /ping`    | 
| MCP |  `POST /mcp`, même si vous modifiez le chemin d'invocation | 
| A2A |  `GET /.well-known/agent-card.json`  | 

Les conflits comparent la méthode et le chemin. Par exemple, `POST /ping` est un itinéraire d'accrochage valide, car AgentCore Utilisations du runtime `GET /ping`. Pour votre port de service et votre chemin d'invocation, voir [Configurez le port de service et le chemin d'invocation de votre agent](runtime-configure-invocation.md).

**Note**  
Si l'environnement d'exécution de votre agent utilise [points de fin de session](runtime-session-endpoints.md), AgentCore Runtime protège vos hooks contre les demandes de point de terminaison de session :  
Une requête qui cible la route d'un hook est rejetée par HTTP `403` et `AccessDenied` avant qu'il n'atteigne votre conteneur. La correspondance de chemin ignore les majuscules et minuscules et traite les orthographes équivalentes courantes d'un chemin comme étant le même chemin. Il s'agit notamment de barres obliques répétées ou de fin, `.` et `..` segments, caractères codés en pourcentage et `;` paramètres.
Les en-têtes Hook sont réservés. AgentCore Runtime les supprime des demandes de point de terminaison de session, de sorte que votre application ne reçoit les en-têtes hook que lors des appels hook.

## Configurer les hooks du cycle de vie
<a name="runtime-lifecycle-hooks-configure"></a>

Spécifiez `hooksConfiguration` lorsque vous créez ou mettez à jour un environnement d'exécution d'agent. L'exemple suivant crée un environnement d'exécution V2 avec un hook d'échauffement de construction qui appelle `POST /warmup` sur le port `8080`. Pour savoir à quoi sert le crochet, voir [Construire un crochet d'échauffement](#runtime-lifecycle-hooks-warmup). Remplacez la région, l'URI de l'image de conteneur et l'ARN du rôle d'exécution par vos valeurs.

**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` remplace l'ensemble de la configuration des crochets. Inclure `hooksConfiguration` dans chaque demande de mise à jour pour laquelle vous souhaitez conserver vos hooks. Pour supprimer vos crochets, appelez `UpdateAgentRuntime` sans `hooksConfiguration`.

## Crochets pris en charge
<a name="runtime-lifecycle-hooks-supported"></a>


| Phase | Crochet | Quand AgentCore Runtime l'appelle | Utilisez-le pour | 
| --- | --- | --- | --- | 
|  `build`  |  `warmup`  | Pendant qu'il prépare votre agent, pendant `CreateAgentRuntime` et `UpdateAgentRuntime`  | Préparez la mémoire et le disque pour que les sessions démarrent plus rapidement. Pour plus d'informations, voir [Construisez un crochet d'échauffement](#runtime-lifecycle-hooks-warmup). | 

### Construisez un crochet d'échauffement
<a name="runtime-lifecycle-hooks-warmup"></a>

AgentCore Runtime appelle le hook d'échauffement de la construction pendant qu'il prépare votre agent, pendant `CreateAgentRuntime` et `UpdateAgentRuntime`, avant que le temps d'exécution n'atteigne `READY`. Il effectue deux appels, dans cet ordre, et indique à votre implémentation de quel appel il s'agit :


| Type d'échauffement | Ordre | Que faire | 
| --- | --- | --- | 
|  `memory`  | Tout d'abord, une fois que votre agent a réussi son `/ping` bilan de santé | Chargez en mémoire ce dont chaque session a besoin, comme les importations, les modèles et les caches. Chaque nouvelle instance commence par ce que vous chargez ici. | 
|  `disk`  | Seconde | Lisez les fichiers que votre agent lit lorsqu'une session démarre. AgentCore Runtime utilise ces lectures pour rendre ces fichiers disponibles plus rapidement pour les nouvelles sessions. | 

Avec une action HTTP, AgentCore Runtime envoie le type d'échauffement dans `X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type` en-tête, avec la valeur `memory` ou `disk`.

La durée des deux appels est limitée à 120 secondes au total. Parce que `memory` l'appel est lancé en premier, le `disk` l'appel obtient l'heure à laquelle `memory` feuilles d'appel. Par exemple, si le `memory` l'appel dure 50 secondes, le `disk` L'appel dure 70 secondes. Vous ne pouvez pas modifier cette limite.

Un crochet d'échauffement peut ajouter jusqu'à 120 secondes au temps `CreateAgentRuntime` et `UpdateAgentRuntime` prendre pour atteindre `READY`. Chaque ligne de journal de préchauffage peut apparaître plusieurs fois pour une création ou une mise à jour.

#### Écrivez le gestionnaire d'échauffement
<a name="runtime-lifecycle-hooks-warmup-handler"></a>

Votre gestionnaire d'échauffement s'exécute sur le serveur de votre agent, en même temps que `/ping` et votre gestionnaire d'invocation :
+  **Gardez `/ping` réactif.** Votre serveur doit continuer à répondre `/ping` pendant l'échauffement. Ne bloquez pas le seul thread de votre serveur dans le gestionnaire de préchauffage. Exécutez le travail dans un thread ou un processus distinct, ou utilisez un serveur qui gère les demandes simultanément.
+  **Retourner `2xx` seulement une fois le travail terminé.** Ce que vous avez chargé lorsque vous répondez correspond au début des sessions.

L'application FastAPI suivante sert `/ping`, `/invocations`, et un crochet d'échauffement à `POST /warmup` sur le port `8080`. Il exécute le travail d'échauffement dans un thread de travail, afin que le serveur continue de répondre `/ping`. Remplacer `load_shared_state` et `STARTUP_FILES` avec le travail et les dossiers de votre agent.

```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 vous enregistrez l'application sous `app.py`, démarrez-le dans votre conteneur à l'aide de la commande suivante :

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

Pour savoir ce qu'il faut inclure dans chaque appel, voir [Préparez la mémoire et le disque à l'aide d'un hook de cycle de vie](runtime-v2-optimize.md#runtime-v2-optimize-warmup).

## Afficher les journaux des crochets
<a name="runtime-lifecycle-hooks-logs"></a>

AgentCore Runtime écrit la progression et le résultat de chaque appel de build hook dans le groupe de journaux de votre environnement d'exécution, `/aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT`, dans les flux de journaux dont le nom commence par `build-logs-`. Chaque ligne commence par `[LIFECYCLE-HOOK <epoch-milliseconds>]`, suivi par `[LIFECYCLE]` pour progresser ou `[ERROR]` pour les échecs. Pour connaître les lignes et savoir comment les modifier, voir [Résoudre les problèmes liés au cycle de vie](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).