View a markdown version of this page

MicroVMs - Base da Amazônia AgentCore
Componentes principaisVersões da plataformaAutenticação e segurançaRecursos adicionaisVisão geral da implementação

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

MicroVMs

O Amazon Bedrock AgentCore Runtime lida com escalabilidade, gerenciamento de sessões, isolamento de segurança e gerenciamento de infraestrutura, permitindo que você se concentre na criação de experiências inteligentes de agentes em vez de na complexidade operacional. Ao aproveitar os recursos e capacidades descritos aqui, você pode criar, implantar e gerenciar agentes de IA sofisticados que agregam valor aos seus usuários e, ao mesmo tempo, ajudam a manter a segurança e a confiabilidade de nível corporativo.

Componentes principais

AgentCore Tempo de execução

Um AgentCore tempo de execução é o componente fundamental que hospeda seu agente de IA ou código de ferramenta. Ele representa um aplicativo em contêiner que processa as entradas do usuário, mantém o contexto e executa ações usando recursos de IA. Ao criar um agente, você define seu comportamento, suas capacidades e as ferramentas que ele pode acessar. Por exemplo, um agente de suporte ao cliente pode responder perguntas sobre produtos, processar devoluções e encaminhar questões complexas para representantes humanos.

Você pode criar e implantar agentes no AgentCore Runtime usando a AgentCore CLI, o SDK do AgentCore Python ou diretamente por meio dos SDKs. AWS Com o SDK do AgentCore Python, você pode definir seu agente usando estruturas populares LangGraph, como CrewAI ou Strands Agents. O SDK lida com as complexidades da infraestrutura, permitindo que você se concentre na lógica e nos recursos do agente.

Cada AgentCore tempo de execução:

  • Tem uma identidade única

  • É versionado para oferecer suporte à implantação e atualizações controladas

Versões

Cada AgentCore Runtime mantém versões imutáveis que capturam um instantâneo completo da configuração em um momento específico:

  • Quando você cria um AgentCore Runtime, a Versão 1 (V1) é criada automaticamente

  • Cada atualização na configuração (imagem do contêiner, configurações de protocolo, configurações de rede) cria uma nova versão

  • Cada versão contém todas as configurações necessárias para a execução

Esse sistema de controle de versão fornece histórico de implantação confiável e recursos de reversão.

Endpoints

Os endpoints fornecem pontos de acesso endereçáveis a versões específicas do seu Runtime. AgentCore Cada endpoint:

  • Tem um ARN exclusivo para invocação

  • Faz referência a uma versão específica do seu Agent Runtime

  • Fornece acesso estável ao seu agente, mesmo quando você atualiza as implementações

Detalhes principais do endpoint:

  • O endpoint “DEFAULT” é criado automaticamente quando você liga CreateAgentRuntime e aponta para a versão mais recente

  • Quando você atualiza seu AgentCore Runtime, uma nova versão é criada, mas o DEFAULT endpoint é atualizado automaticamente para referenciá-la

  • Você pode criar endpoints personalizados com a CreateAgentRuntimeEndpoint operação para diferentes ambientes (desenvolvimento, teste, produção)

  • Quando um usuário faz uma solicitação para um endpoint, a solicitação é resolvida para a versão específica do agente referenciada por esse endpoint

Os endpoints têm estados de ciclo de vida distintos:

  • CREATING- Estado inicial durante a criação do endpoint

  • CREATE_FAILED- Indica falha na criação devido a permissões ou outros problemas

  • READY- O endpoint está operacional e está aceitando solicitações

  • UPDATING- O endpoint está sendo modificado para referenciar uma nova versão

  • UPDATE_FAILED- Indica falha na operação de atualização

Você pode atualizar endpoints sem tempo de inatividade, permitindo transições e reversões de versão perfeitas.

Sessões

As sessões representam contextos de interação individuais entre os usuários e seu AgentCore Runtime. Cada sessão:

  • É identificado por um exclusivo runtimeSessionId fornecido pelo seu aplicativo ou pelo próprio Runtime na primeira invocação, se o runtimeSessionId for deixado vazio

  • É executado em uma microVM dedicada com recursos de CPU, memória e sistema de arquivos completamente isolados

  • Preserva o contexto em várias interações na mesma conversa

  • Pode persistir por até 8 horas de tempo de execução total

Os estados da sessão incluem:

  • Ativo - Processando atualmente uma solicitação ou executando tarefas em segundo plano

  • Ocioso - Não processa nenhuma solicitação, mas mantém o contexto enquanto espera pela próxima interação

  • Encerrado - A sessão foi encerrada devido à inatividade (15 minutos), ao atingir a vida útil máxima (8 horas) ou por ser considerada insalubre

Características importantes da sessão:

  • Após o término da sessão, toda a microVM é encerrada e a memória é higienizada

  • Uma solicitação subsequente com a mesma runtimeSessionId após o encerramento criará um novo ambiente de execução

  • O isolamento da sessão evita a contaminação de dados entre sessões e garante a segurança

  • O estado da sessão é efêmero e não deve ser usado para durabilidade de longo prazo (use AgentCore Memória para durabilidade do contexto)

Esse isolamento completo entre as sessões é crucial para a segurança corporativa, especialmente ao lidar com processos de IA não determinísticos.

Versões da plataforma

Uma versão da plataforma controla como o AgentCore Runtime inicia seu agente. Você o define com o platformVersion campo (V1ouV2) em cada tempo de execução do agente. V1 é o padrão. A versão da plataforma se aplica ao próprio tempo de execução do agente; ela é separada das versões de tempo de execução que capturam seu histórico de configuração.

O Amazon Bedrock AgentCore Runtime V2 inicia seu agente a partir de um snapshot, que mantém os cold starts rápidos e consistentes, independentemente da simultaneidade ou do tamanho da imagem. AgentCore O Runtime prepara seu ambiente uma vez, tira um instantâneo dele e, em seguida, restaura esse instantâneo para cada nova instância, em vez de inicializar seu ambiente a cada inicialização.

Arranques a frio consistentes

A V2 mantém a latência de inicialização a frio consistente, independentemente da simultaneidade ou do tamanho da imagem, porque cada instância restaura um instantâneo preparado em vez de inicializar seu ambiente. Isso é mais importante para imagens de contêineres grandes, que, de outra forma, demoram a carregar em cada partida a frio.

Custo mais baixo para agentes sempre ativos ou intermitentes

A V2 cobra com base no que seu agente usa ativamente. AgentCore O tempo de execução recupera a memória à medida que seu agente a libera e reduz a sobrecarga da plataforma.

nota

A restauração a partir de um instantâneo altera a forma como você estrutura o código do agente. Para saber como otimizar seu agente e aproveitar ao máximo a versão V2 da plataforma, consulte Otimizar seu agente para o AgentCore Runtime V2.

Regiões aceitas

O V2 está disponível nas seguintes AWS regiões:

  • Leste dos EUA (Norte da Virgínia), us-east-1

  • Leste dos EUA (Ohio), us-east-2

  • Oeste dos EUA (Oregon), us-west-2

  • Europa (Irlanda), eu-west-1

  • Ásia-Pacífico (Tóquio), ap-northeast-1

Ativar V2

Você define a versão da plataforma para cada tempo de execução do agente. Configure-o ao criar um tempo de execução ou atualize um tempo de execução existente para movê-lo entre as versões da plataforma. Se você omitir platformVersion ao criar um tempo de execução, o tempo de execução usará V1. Se você omiti-lo ao atualizar um tempo de execução, o tempo de execução manterá sua versão atual da plataforma.

exemplo
AWS Management Console

  1. Abra o AgentCore console Amazon Bedrock e escolha Runtime.

  2. Na página Tempo de execução, escolha Criar tempo de execução.

  3. Insira um nome para o agente ou a ferramenta.

  4. Em Tipo de computação, escolha MicroVMS.

  5. Em Agent/tool fonte, escolha seu tipo de fonte e forneça o artefato, como um URI de imagem de contêiner ou seu código.

  6. Para a versão da plataforma, escolha V2.

  7. (Opcional) Configure a autenticação de entrada, as configurações avançadas e as permissões , como a função de execução do IAM e a chave de criptografia KMS.

  8. Escolha Criar tempo de execução. AgentCore cria a versão 1 do tempo de execução do agente e um DEFAULT endpoint que aponta para ele.

AWS CLI

  1. --platform-version V2Defina o create-agent-runtime comando.

    aws bedrock-agentcore-control create-agent-runtime \
  --agent-runtime-name "my-agent" \
  --role-arn "arn:aws:iam::111122223333:role/AgentExecutionRole" \
  --agent-runtime-artifact '{
    "containerConfiguration": {
      "containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
    }
  }' \
  --network-configuration '{"networkMode": "PUBLIC"}' \
  --platform-version V2

  2. Para confirmar a versão da plataforma, ligueget-agent-runtime.

    aws bedrock-agentcore-control get-agent-runtime \
  --agent-runtime-id my-agent-ABCDE12345 \
  --query platformVersion
AWS SDK

  1. O exemplo a seguir usa boto3 para criar um tempo de execução do agente na V2.

    import boto3

client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

client.create_agent_runtime(
    agentRuntimeName="my-agent",
    roleArn="arn:aws:iam::111122223333:role/AgentExecutionRole",
    agentRuntimeArtifact={
        "containerConfiguration": {
            "containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
        }
    },
    networkConfiguration={"networkMode": "PUBLIC"},
    platformVersion="V2",
)

  2. A create_agent_runtime resposta não retornaplatformVersion. Ligue get_agent_runtime para confirmar.

O que esperar

Uma operação de criação ou atualização da V2 prepara e captura instantâneos do seu ambiente, para que ele se comporte de forma diferente da V1.

Crie e atualize em minutos

Na V1, o tempo de execução chega READY em segundos. Na V2, a preparação do snapshot adiciona um custo único e a criação e atualização da execução por vários minutos antes que o tempo de execução chegue. READY

Seu contêiner deve estar saudável em 120 segundos

AgentCore O Runtime tira um instantâneo da primeira /ping resposta saudável. Relate a integridade /ping somente após a conclusão da inicialização, para que o snapshot capture um agente totalmente inicializado. Se o tempo de execução não reportar integridade dentro de 120 segundos após a inicialização, a criação falhará com um erro de verificação de integridade.

Pesquisa para saber o status de um terminal

As update operações create e retornam enquanto o tempo de execução ainda está CREATING ouUPDATING. Se você chamar update ou delete antes que o tempo de execução atinja um estado terminal, a operação retornaráConflictException. Pesquise get_agent_runtime até que o status seja READY ou termine em FAILED e aguarde alguns minutos para que um tempo de execução V2 chegue. READY

import time

def wait_until_ready(client, agent_runtime_id):
    while True:
        status = client.get_agent_runtime(agentRuntimeId=agent_runtime_id)["status"]
        if status == "READY" or status.endswith("FAILED"):
            return status
        time.sleep(5)
nota

Atualmente, a V2 limita o tamanho total das variáveis de ambiente do seu agente a 1,5 KB para implantações diretas de código e 2,5 KB para agentes de contêiner, em comparação com 4 KB na V1. Se sua configuração exceder esse limite, a solicitação falhará com ValidationException a. AgentCore O tempo de execução aumentará esse limite para corresponder à V1.

Ciclo de vida do snapshot

Na V2, o AgentCore Runtime gerencia um instantâneo para cada versão de tempo de execução para a qual um endpoint aponta. Você não cria nem exclui instantâneos diretamente. Eles acompanham suas mudanças de tempo de execução e endpoint.

Criado

AgentCore O Runtime prepara um instantâneo quando um endpoint aponta para uma versão. Quando você cria um tempo de AgentCore execução, o Runtime hospeda sua versão no endpoint padrão e prepara seu instantâneo. Um tempo de execução pode ter mais de um endpoint que aponta para versões diferentes, portanto, um tempo de execução pode ter mais de um instantâneo por vez.

Atualização

Quando você atualiza um tempo de AgentCore execução, o Runtime hospeda a nova versão no endpoint padrão e prepara um novo instantâneo. A versão hospedada anteriormente não é mais referenciada, então o AgentCore Runtime marca seu snapshot para exclusão e o remove após o término das sessões existentes.

Excluído

AgentCore O tempo de execução exclui um instantâneo quando nenhum endpoint aponta para ele. Isso ocorre quando você atualiza um tempo de execução, remove a referência de um endpoint a uma versão ou exclui o tempo de execução ou um endpoint de tempo de execução. A exclusão pode levar até 8 horas, que é a vida útil máxima da sessão, porque as sessões que já estão em execução no snapshot continuam até o fim.

Infraestrutura como código

AWS CloudFormation e o AWS CDK atualmente não suporta a configuraçãoplatformVersion.

Autenticação e segurança

A autenticação de entrada controla quem pode acessar seus agentes por meio do Gerenciamento de AWS Identidade e Acesso ou do OAuth 2.0, validando os tokens portadores dos provedores de identidade antes de permitir que as solicitações continuem. A autenticação de saída permite que seus agentes acessem com segurança serviços de terceiros usando chaves de API ou OAuth, com credenciais de gerenciamento de AgentCore identidade nos modos autônomo ou delegado pelo usuário. Para obter mais informações, consulte Autenticar e autorizar com autenticação de entrada e autenticação de saída.

Autenticação de entrada

O Inbound Auth, desenvolvido pelo AgentCore Identity, controla quem pode acessar e invocar seus agentes ou ferramentas no Runtime. AgentCore

Métodos de autenticação

  • AWS IAM (SigV4): usa AWS credenciais para verificação de identidade

  • OAuth 2.0: integra-se com provedores de identidade externos

Opções de configuração do OAuth

  • URL de descoberta: o endpoint de descoberta OpenID Connect do seu provedor de identidade

  • Públicos permitidos: lista de valores de público válidos que seus tokens devem conter

  • Clientes permitidos: lista de identificadores de clientes que podem acessar esse agente

Fluxo de autenticação

  1. Os usuários finais se autenticam com seu provedor de identidade (Amazon Cognito, Okta, Microsoft Entra ID)

  2. Seu aplicativo cliente recebe um token portador após uma autenticação bem-sucedida

  3. O cliente passa esse token no cabeçalho de autorização ao invocar o agente.

  4. AgentCore O tempo de execução valida o token com o servidor de autorização

  5. Se for válida, a solicitação será processada; se for inválida, será rejeitada

Isso garante que somente usuários autenticados com a devida autorização possam acessar seus agentes.

Autenticação de saída

O Outbound Auth, desenvolvido pelo Amazon Bedrock AgentCore Identity, permite que seus agentes hospedados no AgentCore Runtime acessem com segurança serviços de terceiros:

Métodos de autenticação

  • OAuth: para serviços que suportam fluxos OAuth

  • Chaves de API: para serviços que usam autenticação baseada em chave

Modos de autenticação

  • User-delegated: Agir em nome do usuário final com suas credenciais

  • Autônomo: agir de forma independente com credenciais de nível de serviço

Serviços com suporte

  • Sistemas corporativos como Slack, Zoom e GitHub

  • AWS serviços

  • APIs e fontes de dados personalizadas

AgentCore O Identity gerencia essas credenciais com segurança, evitando a exposição de credenciais no código ou nos registros do seu agente.

Recursos adicionais

Processamento assíncrono

AgentCore O Runtime oferece suporte a cargas de trabalho de longa duração por meio de:

  • Manipulação de tarefas em segundo plano para operações que excedem request/response os ciclos

  • Rastreamento automático de status por meio do /ping endpoint

  • Suporte para operações de até 8 horas de duração

Para obter mais informações, consulte Gerenciar agentes assíncronos e de longa execução com o Amazon Bedrock Runtime. AgentCore

Respostas de streaming

Os agentes podem transmitir resultados parciais à medida que eles se tornam disponíveis, em vez de esperar pelo processamento completo. Isso permite que você forneça uma experiência de usuário mais responsiva, especialmente para operações que geram grandes quantidades de conteúdo ou levam um tempo significativo para serem concluídas. Para obter mais informações, consulte Respostas do agente de streaming.

WebSocket API

O AgentCore Runtime fornece WebSocket suporte para conexões de streaming bidirecionais em tempo real para comunicação interativa com agentes. Isso permite experiências de agentes mais responsivas e interativas. Para obter mais informações, consulte Comece a usar o streaming bidirecional. WebSocket

Suporte ao protocolo

AgentCore O Runtime suporta vários protocolos de comunicação:

Visão geral da implementação

Veja como começar a usar o AgentCore Runtime. Para ver o exemplo completo, consulte Introdução à AgentCore CLI.

Prepare seu agente ou código de ferramenta

  • Defina a lógica do seu agente usando qualquer estrutura de IA ou código personalizado

  • Adicione os endpoints HTTP necessários usando o AgentCore SDK ou a implementação personalizada

  • Dependências de pacotes em um arquivo requirements.txt

Implante seu agente ou ferramenta

  • Crie e envie uma imagem de contêiner para o Amazon ECR diretamente ou por meio do SDK AgentCore

  • Crie um AgentCore Runtime usando a imagem do contêiner

  • A versão inicial (V1) e o endpoint DEFAULT são criados automaticamente

Invoque seu agente ou ferramenta

Gerencie e observe sessões e faça atualizações

  • Use o mesmo ID de sessão para interações de acompanhamento para manter o contexto

  • Analise registros, rastreamentos e métricas de observabilidade

  • Implante atualizações modificando seu AgentCore Runtime (cria novas versões)

  • Controle a implantação atualizando os endpoints para apontar para novas versões