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.
Tópicos
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
hooksConfigurationcomcapacityProviderConfiguration, a solicitação falha com umValidationException.
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 |
|---|---|---|---|
|
|
String |
Sim |
O caminho que AgentCore O Runtime envia a solicitação para o. O caminho deve atender às seguintes regras:
|
|
|
Inteiro |
Não |
O porto que AgentCore O Runtime envia a solicitação para o. O intervalo suportado é |
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.
| Protocolo | Rotas que um gancho não pode usar |
|---|---|
|
Todos os protocolos |
|
|
MCP |
|
|
A2A |
|
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.
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
403eAccessDeniedantes 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
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 |
|---|---|---|---|
|
|
|
Enquanto prepara seu agente, durante |
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 |
|---|---|---|
|
|
Primeiro, depois que seu agente passa seu |
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. |
|
|
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
/pingresponsivo. Seu servidor deve continuar respondendo/pingenquanto 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
2xxsomente 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.