

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Configure ganchos de ciclo de vida para AgentCore Tempo de execução

Um gancho de ciclo de vida é um endpoint em seu contêiner que AgentCore O tempo de execução faz chamadas em um ponto específico do ciclo de vida do seu agente. Use ganchos para executar seu próprio código nesses pontos, por exemplo, para preparar seu agente antes do início das sessões. Você configura ganchos com o `hooksConfiguration` campo de [CreateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html) e [UpdateAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html), agrupados pela fase do ciclo de vida a que pertencem.

Os ganchos de ciclo de vida estão disponíveis para tempos de execução de agentes que usam a versão V2 da plataforma em microVMs. Para obter mais informações, consulte [Versões da plataforma](runtime-how-it-works.md#runtime-platform-versions).

**Topics**
+ [Requisitos](#runtime-lifecycle-hooks-requirements)
+ [Como funciona uma chamada de gancho](#runtime-lifecycle-hooks-how-it-works)
+ [Configurar ganchos de ciclo de vida](#runtime-lifecycle-hooks-configure)
+ [Ganchos suportados](#runtime-lifecycle-hooks-supported)
+ [Exibir registros de ganchos](#runtime-lifecycle-hooks-logs)

## Requisitos
<a name="runtime-lifecycle-hooks-requirements"></a>
+ O tempo de execução do agente deve usar a versão V2 da plataforma. Na V1, a solicitação falha com um `ValidationException`.
+ O tempo de execução do agente deve usar o tipo de computação microVMS. Os ganchos do ciclo de vida não são compatíveis com instâncias: se você combinar `hooksConfiguration` com `capacityProviderConfiguration`, a solicitação falha com um `ValidationException`.

## Como funciona uma chamada de gancho
<a name="runtime-lifecycle-hooks-how-it-works"></a>

Quando o tempo de execução do seu agente atinge um ponto crítico em seu ciclo de vida, AgentCore O tempo de execução executa a ação do gancho uma vez. Ele faz uma única solicitação ao seu contêiner e espera que sua implementação reporte o sucesso dentro do limite de tempo do gancho. AgentCore O tempo de execução não tenta novamente uma chamada de hook.

Se a chamada falhar ou não for bem-sucedida dentro do limite de tempo, a operação que acionou o gancho falhará. Por exemplo, quando um gancho de compilação falha, o tempo de execução passa para `CREATE_FAILED` ou `UPDATE_FAILED` com um `failureReason` que descreve a falha. Para obter mais informações, consulte [Solucionar problemas de ganchos do ciclo de vida](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).

A forma como sua implementação relata o sucesso depende da ação do gancho.

### Ações de gancho
<a name="runtime-lifecycle-hooks-actions"></a>

Cada gancho tem uma ação, que define como AgentCore O Runtime chama seu contêiner.

#### Ações HTTP
<a name="runtime-lifecycle-hooks-http-actions"></a>

Uma ação HTTP envia uma solicitação HTTP para o `path` e `port` que você escolher, em um servidor em seu contêiner. Sua implementação relata o sucesso retornando qualquer `2xx` código de status após a conclusão do trabalho. Qualquer outro código de status, ou uma falha na conexão, falha na chamada. Cada solicitação pode incluir cabeçalhos que identifiquem a chamada. Cada gancho lista os cabeçalhos e os valores que ele envia.

Os ganchos suportam o `httpPost` ação, que envia um `POST` solicitação. Você o configura no gancho `action.httpPost` campo, que tem os seguintes campos.


| Campo | Tipo | Obrigatório | Descrição | 
| --- | --- | --- | --- | 
|  `path`  | String | Sim | O caminho que AgentCore O Runtime envia a solicitação para o. O caminho deve atender às seguintes regras:+  Ele contém de 1 a 32 caracteres e corresponde ao padrão `^/[A-Za-z0-9._~/-]*$`. <br />+  Está em forma canônica. Não termina em `/` (exceto pelo caminho `/` em si), e não contém `//`, ou `.` ou `..` segmentos. <br />+  Não entra em conflito com uma rota que AgentCore O Runtime já é usado na mesma porta. Para obter mais informações, consulte [Rotas da plataforma](#runtime-lifecycle-hooks-routes).  | 
|  `port`  | Inteiro | Não | O porto que AgentCore O Runtime envia a solicitação para o. O intervalo suportado é `8000`—`12000`, inclusive. Escolha uma porta diferente da [portas de plataforma reservadas](runtime-service-contract.md#runtime-reserved-ports). Se você não especificar uma porta, o padrão é a porta de atendimento do seu agente: `protocolConfiguration.port` se você configurá-lo, caso contrário, a porta padrão do protocolo (`8080` para HTTP e AG-UI, `8000` para MCP e `9000` para A2A). | 

A rota de um gancho é seu método, caminho e porta HTTP. Não pode corresponder a uma rota que AgentCore O Runtime já está sendo usado na porta de atendimento do seu agente. A tabela a seguir lista essas rotas de plataforma.


**Rotas de plataforma que um gancho não pode usar**  

| Protocolo | Rotas que um gancho não pode usar | 
| --- | --- | 
| Todos os protocolos |  +   `POST` para o caminho de invocação: `protocolConfiguration.path` se você configurá-lo, caso contrário, o protocolo padrão (`/invocations` para HTTP e AG-UI, `/mcp` para MCP e `/` para A2A) <br />+   `GET /ws`  <br />+   `GET /ping`    | 
| MCP |  `POST /mcp`, mesmo se você alterar o caminho de invocação | 
| A2A |  `GET /.well-known/agent-card.json`  | 

Os conflitos comparam o método e o caminho. Por exemplo, `POST /ping` é uma rota de gancho válida, porque AgentCore Usos do runtime `GET /ping`. Para sua porta de serviço e caminho de invocação, consulte [Configure a porta de atendimento e o caminho de invocação do seu agente](runtime-configure-invocation.md).

**nota**  
Se o tempo de execução do seu agente usa [endpoints de sessão](runtime-session-endpoints.md), AgentCore O Runtime protege seus ganchos das solicitações de endpoint da sessão:  
Uma solicitação que visa a rota de um gancho é rejeitada com HTTP `403` e `AccessDenied` antes de chegar ao seu contêiner. A correspondência de caminhos ignora maiúsculas e minúsculas e trata as grafias equivalentes comuns de um caminho como o mesmo caminho. Isso inclui barras repetidas ou finais, `.` e `..` segmentos, caracteres codificados por porcentagem e `;` parâmetros.
Os cabeçalhos do gancho são reservados. AgentCore O tempo de execução os exclui das solicitações de endpoint da sessão, portanto, seu aplicativo recebe cabeçalhos de gancho somente em chamadas de gancho.

## Configurar ganchos de ciclo de vida
<a name="runtime-lifecycle-hooks-configure"></a>

Especifique `hooksConfiguration` quando você cria ou atualiza o tempo de execução de um agente. O exemplo a seguir cria um tempo de execução V2 com um gancho de aquecimento de compilação que chama `POST /warmup` no porto `8080`. Para saber o que o gancho faz, consulte [Construa um gancho de aquecimento](#runtime-lifecycle-hooks-warmup). Substitua a região, o URI da imagem do contêiner e o ARN da função de execução por seus 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` substitui toda a configuração do gancho. Incluir `hooksConfiguration` em cada solicitação de atualização para a qual você deseja manter seus ganchos. Para remover seus ganchos, ligue `UpdateAgentRuntime` sem `hooksConfiguration`.

## Ganchos suportados
<a name="runtime-lifecycle-hooks-supported"></a>


| Fase | Hook | Quando AgentCore O Runtime chama isso | Use-o para | 
| --- | --- | --- | --- | 
|  `build`  |  `warmup`  | Enquanto prepara seu agente, durante `CreateAgentRuntime` e `UpdateAgentRuntime`  | Prepare a memória e o disco para que as sessões comecem mais rapidamente. Para obter mais informações, consulte [Construa um gancho de aquecimento](#runtime-lifecycle-hooks-warmup). | 

### Construa um gancho de aquecimento
<a name="runtime-lifecycle-hooks-warmup"></a>

AgentCore O Runtime chama o gancho de aquecimento da compilação enquanto prepara seu agente, durante `CreateAgentRuntime` e `UpdateAgentRuntime`, antes que o tempo de execução chegue `READY`. Ele faz duas chamadas, nessa ordem, e informa à sua implementação qual é a chamada:


| Tipo de aquecimento | Ordem | O que fazer | 
| --- | --- | --- | 
|  `memory`  | Primeiro, depois que seu agente passa seu `/ping` verificação de saúde | Carregue na memória o que cada sessão precisa, como importações, modelos e caches. Cada nova instância começa com o que você carrega aqui. | 
|  `disk`  | Segunda | Leia os arquivos que seu agente lê quando uma sessão começa. AgentCore O Runtime usa essas leituras para disponibilizar esses arquivos mais rapidamente para novas sessões. | 

Com uma ação HTTP, AgentCore O Runtime envia o tipo de aquecimento no `X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type` cabeçalho, com o valor `memory` ou `disk`.

As duas chamadas compartilham um limite de tempo de 120 segundos no total. Porque o `memory` a chamada é executada primeiro, o `disk` a chamada recebe a hora em que o `memory` a chamada sai. Por exemplo, se o `memory` a chamada leva 50 segundos, o `disk` a chamada tem 70 segundos. Você não pode alterar esse limite.

Um gancho de aquecimento pode adicionar até 120 segundos ao tempo em que `CreateAgentRuntime` e `UpdateAgentRuntime` pegue para alcançar `READY`. Cada linha de registro de aquecimento pode aparecer mais de uma vez para uma criação ou atualização.

#### Escreva o manipulador de aquecimento
<a name="runtime-lifecycle-hooks-warmup-handler"></a>

Seu manipulador de aquecimento é executado no servidor do seu agente, junto com `/ping` e seu manipulador de invocação:
+  **Mantenha `/ping` responsivo.** Seu servidor deve continuar respondendo `/ping` enquanto o aquecimento é executado. Não bloqueie o único thread do seu servidor dentro do manipulador de aquecimento. Execute o trabalho em um thread ou processo separado ou use um servidor que processe solicitações simultaneamente.
+  **Retorne `2xx` somente depois que o trabalho estiver concluído.** O que você carrega ao responder é com o que as sessões começam.

O seguinte aplicativo FastAPI serve `/ping`, `/invocations`, e um gancho de aquecimento em `POST /warmup` no porto `8080`. Ele executa o trabalho de aquecimento em um thread de trabalho, para que o servidor continue respondendo `/ping`. Substituir `load_shared_state` e `STARTUP_FILES` com o trabalho e os arquivos do seu 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", "")}
```

Se você salvar o aplicativo como `app.py`, inicie-o em seu contêiner com o seguinte comando:

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

Para saber o que colocar em cada chamada, consulte [Prepare a memória e o disco com um gancho de ciclo de vida](runtime-v2-optimize.md#runtime-v2-optimize-warmup).

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

AgentCore O Runtime grava o progresso e o resultado de cada chamada de build hook no grupo de log do seu tempo de execução, `/aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT`, em fluxos de log cujos nomes começam com `build-logs-`. Cada linha começa com `[LIFECYCLE-HOOK <epoch-milliseconds>]`, seguido por `[LIFECYCLE]` para progresso ou `[ERROR]` para falhas. Para ver as linhas e como agir de acordo com elas, consulte [Solucionar problemas de ganchos do ciclo de vida](runtime-troubleshooting.md#troubleshoot-runtime-lifecycle-hooks).