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 ](runtime-instances-how-it-works.md#runtime-instances-capacity-provider) 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. ](runtime-instances-getting-started.md)
**nota**
Os nomes dos parâmetros nesses exemplos seguem o modelo do plano de AgentCore controle. Para obter as formas oficiais de solicitação e resposta, consulte a Referência da API [ Amazon Bedrock AgentCore Control. ](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html)
## 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.
**Example**
1.
```
aws bedrock-agentcore-control create-capacity-provider \
--name "my_capacity_provider" \
--permissions-configuration '{
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
}' \
--compute-configuration '{
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"]
}
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"]
},
"lifecycleConfiguration": {
"maxLifetime": 3600
},
"volumes": [
{ "ebsConfiguration": { "name": "scratch", "sizeGiB": 50, "volumeType": "gp3" } }
]
}
}'
```
1. Exemplo de Python usando boto3 para criar um provedor de capacidade.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_capacity_provider(
name="my_capacity_provider",
permissionsConfiguration={
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
},
computeConfiguration={
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"],
},
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"],
},
"lifecycleConfiguration": {
"maxLifetime": 3600,
},
"volumes": [
{"ebsConfiguration": {"name": "scratch", "sizeGiB": 50, "volumeType": "gp3"}}
],
}
},
)
print(f"Capacity provider ARN: {response['capacityProviderArn']}")
```
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` `g6``g6e`,`gr6`,`g6f`, `gr6f``g7e`,, `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 ](runtime-instances-how-it-works.md#runtime-instances-gpu) 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 tornar`CREATE_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óprio`lifecycleConfiguration.maxLifetime`, cujo padrão é 28800 segundos (8 horas). Esse valor deve ser menor ou igual ao `maxLifetime` definido pelo provedor de capacidade`ec2Configuration.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.
**nota**
Ambos os recursos usam um `lifecycleConfiguration` membro, mas são estruturas diferentes. A versão do provedor de capacidade pega `idleInstanceTimeout` `maxLifetime` e se aplica à instância. A versão do tempo de execução do agente pega `idleRuntimeSessionTimeout` `maxLifetime` e se aplica à sessão. Para obter mais informações, consulte [ Definir as configurações do AgentCore ciclo de vida do Amazon Bedrock. ](runtime-lifecycle-settings.md)
Não passe `networkConfiguration` quando você especificar`capacityProviderConfiguration`. O tempo de execução de uma Instância herda sua rede do provedor de capacidade`ec2Configuration.vpcConfiguration`, portanto, a especificação de ambos falha com a. `ValidationException`
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "my_instances_agent" \
--role-arn "arn:aws:iam::111122223333:role/AgentRuntimeRole" \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
}' \
--capacity-provider-configuration '{
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
}' \
--lifecycle-configuration '{
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800
}' \
--filesystem-configurations '[
{
"capacityProviderVolume": { "volumeName": "scratch", "mountPath": "/mnt/scratch" }
}
]'
```
1. Exemplo de Python usando boto3 para criar um tempo de execução do agente em instâncias.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="my_instances_agent",
roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
},
capacityProviderConfiguration={
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5",
},
lifecycleConfiguration={
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800,
},
filesystemConfigurations=[
{
"capacityProviderVolume": {"volumeName": "scratch", "mountPath": "/mnt/scratch"}
}
],
)
print(f"Agent runtime ARN: {response['agentRuntimeArn']}")
```
## 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.
**Example**
1.
```
echo '{"prompt": "Analyze the sales data and summarize the key trends."}' > payload.json
aws bedrock-agentcore invoke-agent-runtime \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000" \
--qualifier "DEFAULT" \
--payload fileb://payload.json \
response.json
```
O `payload` parâmetro é um blob binário e a AWS CLI espera que os blobs sejam codificados em base64 por padrão. A passagem de JSON bruto em linha, como`--payload '{"prompt": "…"}'`, falha no lado do cliente com um `Invalid base64` erro antes que a solicitação chegue ao serviço. O `fileb://` formulário usado aqui lê o arquivo como binário, independentemente da `cli_binary_format` configuração, portanto, evita a etapa de codificação.
A resposta do agente é um blob de streaming que a AWS CLI grava no arquivo de saída que você nomeia como último argumento, neste exemplo. `response.json` A saída padrão carrega somente os `statusCode` campos `runtimeSessionId``contentType`, e, então leia o arquivo de saída para ver o que seu agente retornou.
AWS SDK
1. Exemplo de Python usando boto3 para invocar o tempo de execução de um agente em instâncias.
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000", # 33+ chars; reuse to keep the session
payload=json.dumps({"prompt": "Analyze the sales data and summarize the key trends."}).encode(),
qualifier="DEFAULT",
)
print("Agent response:", json.loads(response["response"].read()))
```
`runtimeSessionId`Deve 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html), 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html#managed-resource-visibility-settings).
## 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 ](runtime-instances-security.md) 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](runtime-instances-security.md).
## Limpeza: interrompa e exclua sessões
**Atenção**
Para evitar cobranças contínuas pelas instâncias do Amazon EC2 e pelos volumes do Amazon EBS provisionados em sua conta, exclua as sessões e os provedores de capacidade que você não precisa mais ao concluir este tutorial.
Uma sessão pode hospedar vários tempos de execução de agentes na mesma instância, portanto, AgentCore fornece duas operações distintas:
+ **Interromper o tempo de execução de um agente em uma sessão ** — `StopRuntimeSession` interrompe o tempo de execução de um único agente em uma sessão, identificado pelo ARN do tempo de execução e pelo ID da sessão. Outros tempos de execução de agentes que compartilham a mesma sessão e instância não são afetados.
+ **Excluir uma sessão ** — `DeleteCapacityProviderSession` exclui a sessão inteira e desprovisiona os recursos do EC2 criados em sua conta (instância, interface de rede e quaisquer volumes persistentes do EBS), para que você pare de incorrer em custos de infraestrutura e armazenamento.
Para interromper o tempo de execução de um agente específico em uma sessão, chame a [ StopRuntimeSession ](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) operação com o ARN do tempo de execução e o ID da sessão.
**Example**
1.
```
aws bedrock-agentcore stop-runtime-session \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000"
```
1. Exemplo de Python usando boto3 para interromper uma sessão de tempo de execução.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
client.stop_runtime_session(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000",
)
```
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]'
```
**Example**
1.
```
aws bedrock-agentcore delete-capacity-provider-session \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5" \
--session-id "project-xyz-0000000000000000000000000000"
```
1. Exemplo de Python usando boto3 para excluir uma sessão de provedor de capacidade.
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.delete_capacity_provider_session(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
sessionId="project-xyz-0000000000000000000000000000",
)
print("Session status:", response["status"])
```
## 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.
**Example**
1.
```
aws bedrock-agentcore-control delete-capacity-provider \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5"
```
1. Exemplo de Python usando boto3 para excluir um provedor de capacidade.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
client.delete_capacity_provider(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
)
```