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

Comece a usar instâncias usando o AWS CLI ou SDK

Este tutorial explica como hospedar um agente no tipo de computação Instances com a Interface de Linha de AWS Comando (AWS CLI) e os SDKs. Primeiro, você cria um provedor de capacidade que define a infraestrutura do Amazon Elastic Compute Cloud (Amazon EC2), depois cria um tempo de execução do agente que a usa e, finalmente, invoca o agente.

Para ver os pré-requisitos, consulte Começar a usar instâncias.

Etapa 1: criar um provedor de capacidade

Use a CreateCapacityProvider operação para definir sua infraestrutura EC2. A solicitação AgentCore usa uma permissionsConfiguration (a função do IAM usada para operar o provedor de capacidade) e uma computeConfiguration que descreve as instâncias do EC2 por meio de um modelo de lançamento. O exemplo a seguir cria um provedor de capacidade Linux com um único tipo de instância permitido e um volume EBS persistente.

Para executar cargas de trabalho de GPU, inclua um tipo de instância de GPU compatível. allowedInstanceTypes AgentCore provisiona os drivers de GPU na instância, para que as imagens de contêiner padrão funcionem sem agrupar drivers. As famílias apoiadas são g4dn g5 g6g6e,gr6,g6f, gr6fg7e,, inf2 e. Se você incluir um tipo de instância aceleradora de uma família sem suporte, a solicitação falhará com a. ValidationException Para obter mais informações, consulte Usar tipos de instância de GPU.

Pesquise GetCapacityProvider até que o status seja READY antes de associar o provedor de capacidade a um tempo de execução. Se o status se tornarCREATE_FAILED, inspecione statusCode e determine statusReason a causa.

Etapa 2: criar um tempo de execução do agente no provedor de capacidade

Crie um tempo de execução do agente com um capacityProviderConfiguration que faça referência ao seu provedor de capacidade. Para montar um volume definido no provedor de capacidade no sistema de arquivos do agente, adicione uma capacityProviderVolume entrada filesystemConfigurations que faça referência ao volume pelo nome. Os caminhos de montagem devem estar abaixo /mnt de um único subdiretório (por exemplo,/mnt/scratch).

O tempo de execução do agente tem seu própriolifecycleConfiguration.maxLifetime, cujo padrão é 28800 segundos (8 horas). Esse valor deve ser menor ou igual ao maxLifetime definido pelo provedor de capacidadeec2Configuration.lifecycleConfiguration. O provedor de capacidade na Etapa 1 define esse valor como 3.600 segundos (1 hora), portanto, o tempo de execução padrão de 8 horas o CreateAgentRuntime excederia e falharia com a. ValidationException Portanto, o exemplo a seguir define um tempo maxLifetime de execução de 1.800 segundos, que está dentro do limite do provedor de capacidade.

Não passe networkConfiguration quando você especificarcapacityProviderConfiguration. O tempo de execução de uma Instância herda sua rede do provedor de capacidadeec2Configuration.vpcConfiguration, portanto, a especificação de ambos falha com a. ValidationException

Etapa 3: invocar o agente

Invoque o tempo de execução da mesma forma que você faria com um micro VM-backed tempo de execução. Reutilize o mesmo runtimeSessionId em todas as invocações para manter a sessão na mesma instância. Isso permite que seu agente acesse dados de invocações anteriores. Para co-localizar agentes colaboradores, use o mesmo runtimeSessionId em vários tempos de execução que compartilham um provedor de capacidade.

runtimeSessionIdDeve ter pelo menos 33 caracteres.

A primeira invocação para uma nova sessão provisiona uma instância do EC2 em sua conta e inicia o agente, portanto, normalmente leva mais tempo do que as invocações posteriores. As invocações subsequentes para a mesma sessão reutilizam a instância em execução e retornam muito mais rápido.

AgentCore provisiona essas instâncias como instâncias gerenciadas do Amazon EC2, que estão ocultas DescribeInstances e visualizadas pelo console do EC2 por padrão. Uma aws ec2 describe-instances chamada simples não os lista. Para vê-los, inclua recursos gerenciados:

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"

Para obter mais informações sobre como gerenciar a visibilidade da instância, consulte a configuração de visibilidade de recursos gerenciados.

Co-locate vários agentes em uma instância

Quando dois tempos de execução de agentes fazem referência ao mesmo provedor de capacidade e você os invoca com o mesmo runtimeSessionId, os dois agentes são executados na mesma instância do EC2. Lá, eles podem compartilhar o volume configurado na configuração do sistema de arquivos. Os agentes colaboram lendo e gravando arquivos nesse volume compartilhado — cada agente é invocado de forma independente e, de outra forma, não compartilha o estado. Por exemplo, um executor de teste pode gravar resultados no volume e um analisador de código invocado na mesma sessão pode então lê-los. Para saber o limite entre agentes em uma instância compartilhada, consulte Modelo de segurança e permissões para instâncias de tempo de execução.

import boto3
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"

# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
    qualifier="DEFAULT",
)

# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
    qualifier="DEFAULT",
)

Cada agente é executado com suas próprias credenciais do IAM derivadas da função de execução de seu tempo de execução, para que você possa conceder aos agentes colaboradores permissões diferentes, embora eles compartilhem a mesma instância. No entanto, como os agentes na mesma instância não estão isolados uns dos outros, qualquer agente pode potencialmente ler as credenciais de outro agente. Co-locate somente agentes que são mutuamente confiáveis. Para obter mais informações, consulte Modelo de segurança e permissões para instâncias de tempo de execução.

Limpeza: interrompa e exclua sessões

Uma sessão pode hospedar vários tempos de execução de agentes na mesma instância, portanto, AgentCore fornece duas operações distintas:

Para interromper o tempo de execução de um agente específico em uma sessão, chame a StopRuntimeSession operação com o ARN do tempo de execução e o ID da sessão.

Para excluir uma sessão e desprovisionar todos os seus recursos — incluindo quaisquer volumes persistentes do EBS — ligue DeleteCapacityProviderSession com o ID do provedor de capacidade e o ID da sessão. A operação é idempotente e assíncrona: ela retorna imediatamente enquanto AgentCore encerra a instância e exclui os volumes em segundo plano.

Os IDs de sessão são valores que você fornece na invocação, e não há nenhuma operação que liste as sessões em um provedor de capacidade. Mantenha um registro dos runtimeSessionId valores que você usa para poder excluir cada sessão posteriormente. Se você não as tiver mais, poderá encontrar as instâncias que ainda estão em execução e excluir o provedor de capacidade para desprovisionar todas as suas sessões:

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
  --query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'

Excluir um provedor de capacidade

Quando você não precisar mais de um provedor de capacidade, exclua-o com a DeleteCapacityProvider operação. A exclusão de um provedor de capacidade interrompe e exclui todas as sessões associadas e seu armazenamento persistente, portanto, também serve como uma forma de limpar sessões cujos IDs você não tem mais. Você não precisa excluir as sessões primeiro. No entanto, você precisa remover os tempos de execução que fazem referência ao provedor de capacidade: exclua primeiro as versões, os endpoints ou os tempos de execução associados, ou a solicitação de exclusão falhará com um. ValidationException A operação é assíncrona; identifique o provedor de capacidade por seu ID.