View a markdown version of this page

Configure ganchos de ciclo de vida para AgentCore Tempo de execução - Rocha da Amazônia AgentCore

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 e UpdateAgentRuntime, 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.

Requisitos

  • 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

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.

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

Ações de gancho

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

Ações HTTP

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._~/-]*$.

  • Está em forma canônica. Não termina em / (exceto pelo caminho / em si), e não contém //, ou . ou .. segmentos.

  • 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.

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. 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)

  • GET /ws

  • 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.

nota

Se o tempo de execução do seu agente usa endpoints de sessão, 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

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. Substitua a região, o URI da imagem do contêiner e o ARN da função de execução por seus valores.

exemplo
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 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

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.

Construa um gancho de aquecimento

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

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.

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:

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.

Exibir registros de ganchos

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.