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á.
Otimize seu agente para o Amazon Bedrock AgentCore Runtime V2
O Amazon Bedrock AgentCore Runtime V2 inicia seu agente restaurando um snapshot. Isso muda a forma como você estrutura seu código de agente. O trabalho que seu agente faz na inicialização é capturado no snapshot e compartilhado por cada instância restaurada. Em vez disso, produza qualquer valor que deva ser diferente entre as solicitações ou que possa expirar em seu manipulador de solicitações. Este tópico descreve como estruturar seu agente em torno do trabalho de inicialização e do trabalho por solicitação para que ele permaneça correto após cada restauração. Para obter uma visão geral da versão V2 da plataforma, consulte Versões da plataforma.
Seu agente tem dois contextos de execução:
- Startup
-
Código que é executado uma vez quando o processo é iniciado, antes que o AgentCore Runtime tire o instantâneo. AgentCore O Runtime captura esse código no snapshot e cada instância herda seus resultados.
- Tratamento de solicitações
-
O código em seu
/invocationsmanipulador. Esse código é executado em todas as solicitações em todas as instâncias.
Use uma regra para decidir onde o código pertence. Calcule um valor na inicialização se ele permanecer o mesmo durante toda a vida útil do instantâneo. Calcule-o em seu manipulador se ele variar de acordo com a solicitação ou puder expirar. AgentCore O Runtime tira um instantâneo por versão do agente e o usa até que você crie ou atualize o agente, portanto, a vida útil do instantâneo é a vida útil dessa versão.
Inicialize uma vez na inicialização
Faça um trabalho caro e reutilizável no início do processo, antes da captura instantânea. Por exemplo, importe dependências, carregue pesos do modelo ou leia a configuração estática do seu pacote de implantação. Com o AgentCore SDK, faça esse trabalho no escopo do módulo, antes de ligarapp.run(). Seu agente não escuta na porta 8080 até ser app.run() executado, então nada /ping pode ser bem-sucedido e nenhum instantâneo pode ser tirado até que seu trabalho de inicialização termine. O instantâneo captura um agente totalmente inicializado por construção, e você não precisa bloqueá-lo. /ping Conclua a inicialização em até 120 segundos após a inicialização. Se seu agente não ficar íntegro a tempo, o tempo de execução falhará na verificação de integridade. Para obter mais informações sobre os /invocations endpoints /ping e, consulte Compreender o contrato AgentCore de serviço Runtime.
import json, pathlib from bedrock_agentcore.runtime import BedrockAgentCoreApp # Runs once at import, before app.run() starts the server and before the # snapshot. Every restored instance inherits these objects. MODEL = load_model_weights() SETTINGS = json.loads((pathlib.Path(__file__).parent / "agent.json").read_text()) app = BedrockAgentCoreApp() @app.entrypoint def invoke(payload): # Per-request work runs here on every instance. ... app.run() # starts listening on 8080; the snapshot is taken after this
Se seu agente executar seu próprio servidor HTTP em vez do AgentCore SDK, relate um status de integridade /ping somente após a conclusão da inicialização, para que o snapshot capture um agente totalmente inicializado.
Leia somente dados na inicialização que sejam os mesmos para todas as instâncias e que não expirem. Gerencie valores urgentes, como credenciais de curta duração, em seu manipulador.
Não calcule nada que você altere na inicialização sem reimplantar. Por exemplo, um catálogo de ferramentas obtido do AgentCore Gateway parece um valor de inicialização ideal porque é lento e caro de carregar, mas armazená-lo em cache na inicialização congela o inventário de ferramentas do agente no momento da captura instantânea.
Mantenha o estado atualizado por solicitação
O instantâneo é capturado uma vez e compartilhado por cada instância restaurada, portanto, qualquer valor que seu agente gera na inicialização é idêntico em todas as instâncias e fixo no momento do instantâneo. Manipule valores que o instantâneo não pode carregar em seu /invocations manipulador. A tabela a seguir descreve os valores a serem computados em seu manipulador em vez de na inicialização.
| Para fazer isso | Faça isso no manipulador | Motivo |
|---|---|---|
|
Gere valores, identificadores ou tokens aleatórios |
Ligue |
|
|
Leia a hora atual |
Calcule para cada solicitação |
Um carimbo de data/hora capturado na inicialização é fixado no momento do instantâneo. |
|
Meça o tempo decorrido |
Pegue o carimbo de data/hora de referência em seu manipulador |
|
|
Use credenciais ou tokens |
Atualize-os quando expirarem |
As credenciais carregadas na inicialização podem expirar antes do início da instância. |
|
Identifique a instância ou o trabalhador |
Gere um id por solicitação; não o derive do host |
Cada instância restaurada relata o mesmo nome de host ( |
Crie clientes reutilizáveis na inicialização e calcule valores por solicitação em cada chamada.
import os, time # Build reusable clients at startup, before the snapshot. Exercise them here too # (for example, with a warm-up call) so the setup the client caches — endpoint and # credential resolution, connection pool — is captured in the snapshot. client = build_client() warm_up(client) @app.entrypoint def invoke(payload): creds = get_credentials() # refreshed when expired, not read at startup request_id = os.urandom(16).hex() # unique per request now = time.time() # current time, not snapshot time # Handle the request.
Use bibliotecas criptográficas seguras para instantâneos
Quando o AgentCore Runtime restaura instâncias de um snapshot, cada instância criada a partir desse snapshot começa com uma cópia idêntica da memória capturada no momento do snapshot. Isso inclui o estado interno dos geradores de números aleatórios dentro das bibliotecas criptográficas e quaisquer chaves, tokens ou identificadores que seu agente criou durante a inicialização. A menos que esse estado seja atualizado após a restauração, as instâncias podem produzir os mesmos valores “aleatórios”.
Limitação atual
No AgentCore Runtime, compilações seguras para instantâneos de bibliotecas criptográficas atualmente não são reiniciadas após uma restauração. Isso se aplica tanto às implantações diretas de código quanto às implantações de contêineres.
Soluções alternativas
-
Gere segredos, chaves, tokens e identificadores de sessão ao lidar com uma solicitação, não quando seu agente inicia. Isso evita o uso de quaisquer valores criados antes que o AgentCore Runtime tire o instantâneo em cada instância restaurada a partir desse instantâneo.
-
Mesmo ao lidar com uma solicitação, obtenha valores aleatórios diretamente do sistema operacional, por exemplo, Python's
secretsoros.urandom, Go'scrypto/randou reading/dev/urandom. Não use valores aleatórios de uma biblioteca criptográfica como o OpenSSL, pois eles podem se repetir em várias instâncias.
Redes
- Crie clientes na startup e espere uma reconexão transparente
-
O soquete que você abre na inicialização não sobrevive a uma restauração, mas a configuração que sua biblioteca cliente armazena em cache — análise do modelo de serviço, resolução de endpoint, resolução de credenciais e pool de conexões — sobrevive. Crie e exercite seus clientes na inicialização e espere que a primeira chamada após uma restauração restabeleça a conexão de forma transparente.
- Não use o nome do host ou o PID como um identificador de instância exclusivo
-
Cada instância restaurada começa com o mesmo snapshot e relata o mesmo nome de host e ID de processo. Gere um identificador exclusivo em cada solicitação.
- Evite vincular a uma porta de origem fixa
-
Depois de uma restauração, a conexão mantida no momento do snapshot é restabelecida e uma porta de origem fixa pode colidir com essa substituição dentro da instância. As instâncias restauradas são microVMs separadas com seus próprios namespaces de rede, portanto, o conflito está dentro de uma instância, não entre elas.
Cross-account métricas e cotas
Para uma invocação entre contas, em que um principal em uma conta invoca o tempo de execução de um agente pertencente a outra conta por meio de uma política baseada em recursos, as CloudWatch métricas e o uso da cota de limite de taxa para a invocação são atribuídos à conta do proprietário do recurso. O proprietário do recurso é a conta que possui o tempo de execução do agente.
Você também pode ver as métricas que contam para sua cota no console Service