View a markdown version of this page

Execute comandos shell em AgentCore Sessões de execução - Rocha da Amazônia AgentCore

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

Execute comandos shell em AgentCore Sessões de execução

O InvokeAgentRuntimeCommand operação permite que você execute comandos shell diretamente dentro de uma execução AgentCore Execute a sessão e transmita a saída de volta HTTP/2. Os comandos são executados no mesmo contêiner, sistema de arquivos e ambiente do seu agente — a mesma sessão usada pelo InvokeAgentRuntime . Isso permite fluxos de trabalho em que seu aplicativo usa o agente para raciocinar tarefas e comandos para operações determinísticas, como execução de testes, operações git ou configuração do ambiente.

Para ligar InvokeAgentRuntimeCommand , você precisa bedrock-agentcore:InvokeAgentRuntimeCommand permissões.

Como funciona

InvokeAgentRuntimeCommand executa um comando shell dentro do contêiner de um ativo AgentCore Executa a sessão e transmite a saída de volta.

Mesmo agente, mesma sessão

InvokeAgentRuntimeCommand opera no mesmo tempo de execução e sessão do agente que InvokeAgentRuntime . Você não cria recursos separados. O agente com o qual você atuou CreateAgentRuntime aceita invocações de agentes e execução de comandos em qualquer sessão ativa.

nota

O AgentCore O Runtime MicroVM não inclui ferramentas para desenvolvedores como git , npm , ou tempos de execução do idioma por padrão. Todas as ferramentas das quais seus comandos dependem devem ser incluídas na imagem do contêiner (por meio do Dockerfile) ou instaladas dinamicamente em tempo de execução.

A resposta é um fluxo de três tipos de eventos:

Event Quando Contém

contentStart

Primeiro pedaço

Confirma que o comando foi iniciado

contentDelta

Durante a execução

Saída stdout and/or stderr

contentStop

Último pedaço

exitCode e status ( COMPLETED ou TIMED_OUT )

Fluxos de saída em tempo real. Você vê os resultados à medida que eles são executados, não depois de terminados.

Pré-requisitos

  • Permissão bedrock-agentcore:InvokeAgentRuntimeCommand do IAM

  • Um válido AgentCore ARN do endpoint de tempo de execução

nota

Os agentes criados após 17 de março de 2026 oferecem suporte automático à execução de comandos. Se você implantou seu agente antes dessa data, deverá reimplantá-lo para atualizar o tempo de execução do agente.

Executar um comando

exemplo
AgentCore CLI
  1. Corra agentcore runtime exec com o Runtime ID. O Runtime ID é o último segmento do Runtime ARN. O ID da sessão deve ter de 33 a 100 caracteres:

    agentcore runtime exec \ --id <runtime-id> \ --session-id <session-id> \ --command "ls -la /workspace"

    O comando imprime JSON com o sessionId, command, exitCode, status, e output campos. Adicionar --timeout <seconds> (1 a 3600) para limitar por quanto tempo o comando é executado e --qualifier <endpoint> para atingir um endpoint diferente de DEFAULT.

Python
  1. O exemplo a seguir mostra como usar o boto3 para executar um comando em um AgentCore Sessão de tempo de execução.

    import boto3 import sys client = boto3.client('bedrock-agentcore', region_name='us-west-2') response = client.invoke_agent_runtime_command( agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent', runtimeSessionId='session-id-at-least-33-characters-long', qualifier='DEFAULT', contentType='application/json', accept='application/vnd.amazon.eventstream', body={ 'command': '/bin/bash -c "npm test"', 'timeout': 60 } ) # Process the streaming response for event in response.get('stream', []): if 'chunk' in event: chunk = event['chunk'] if 'contentStart' in chunk: print("Command execution started") if 'contentDelta' in chunk: delta = chunk['contentDelta'] if delta.get('stdout'): print(delta['stdout'], end='') if delta.get('stderr'): print(delta['stderr'], end='', file=sys.stderr) if 'contentStop' in chunk: stop = chunk['contentStop'] print(f"\nExit code: {stop.get('exitCode')}, Status: {stop.get('status')}")
Java
  1. O exemplo a seguir mostra como usar o AWS SDK para Java para executar um comando em um AgentCore Sessão de tempo de execução.

    import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.bedrockagentcore.BedrockAgentCoreAsyncClient; import software.amazon.awssdk.services.bedrockagentcore.model.*; import java.util.UUID; import java.util.concurrent.CompletableFuture; public class ExecuteCommandExample { public static void main(String[] args) throws Exception { String agentArn = "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent"; String sessionId = UUID.randomUUID().toString(); BedrockAgentCoreAsyncClient client = BedrockAgentCoreAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(DefaultCredentialsProvider.create()) .build(); InvokeAgentRuntimeCommandRequest request = InvokeAgentRuntimeCommandRequest.builder() .agentRuntimeArn(agentArn) .runtimeSessionId(sessionId) .qualifier("DEFAULT") .contentType("application/json") .accept("application/vnd.amazon.eventstream") .body(InvokeAgentRuntimeCommandRequestBody.builder() .command("/bin/bash -c \"npm test\"") .timeout(60) .build()) .build(); InvokeAgentRuntimeCommandResponseHandler handler = InvokeAgentRuntimeCommandResponseHandler.builder() .subscriber(InvokeAgentRuntimeCommandResponseHandler.Visitor.builder() .onChunk(chunk -> { if (chunk.contentStart() != null) { System.out.println("Command execution started"); } if (chunk.contentDelta() != null) { ContentDeltaEvent delta = chunk.contentDelta(); if (delta.stdout() != null) System.out.print(delta.stdout()); if (delta.stderr() != null) System.err.print(delta.stderr()); } if (chunk.contentStop() != null) { ContentStopEvent stop = chunk.contentStop(); System.out.println("\nExit code: " + stop.exitCode() + ", Status: " + stop.statusAsString()); } }) .build()) .build(); CompletableFuture<Void> future = client.invokeAgentRuntimeCommand(request, handler); future.get(); client.close(); } }
JavaScript
  1. O exemplo a seguir mostra como usar o AWS SDK para JavaScript v3 para executar um comando em um AgentCore Sessão de tempo de execução.

    import { BedrockAgentCoreClient, InvokeAgentRuntimeCommandCommand } from "@aws-sdk/client-bedrock-agentcore"; import { randomUUID } from "crypto"; const client = new BedrockAgentCoreClient({ region: "us-west-2" }); const request = { agentRuntimeArn: "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent", runtimeSessionId: randomUUID(), qualifier: "DEFAULT", contentType: "application/json", accept: "application/vnd.amazon.eventstream", body: { command: '/bin/bash -c "npm test"', timeout: 60, }, }; const command = new InvokeAgentRuntimeCommandCommand(request); const response = await client.send(command); // Process the event stream for await (const event of response.stream) { if (event.chunk) { const chunk = event.chunk; if (chunk.contentStart) { console.log("Command execution started"); } if (chunk.contentDelta) { if (chunk.contentDelta.stdout) process.stdout.write(chunk.contentDelta.stdout); if (chunk.contentDelta.stderr) process.stderr.write(chunk.contentDelta.stderr); } if (chunk.contentStop) { console.log(`\nExit code: ${chunk.contentStop.exitCode}, ` + `Status: ${chunk.contentStop.status}`); } } } client.destroy();

Exemplo de fluxo de trabalho do agente de codificação

Um padrão comum é usar InvokeAgentRuntime para raciocinar e InvokeAgentRuntimeCommand para operações determinísticas na mesma sessão.

Exemplo End-to-end fluxo de trabalho do agente de codificação

import boto3 import json client = boto3.client('bedrock-agentcore', region_name='us-west-2') AGENT_ARN = 'arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent' SESSION_ID = 'session-id-at-least-33-characters-long' def run_command(command, timeout=60): """Helper to run a command and return the exit code.""" response = client.invoke_agent_runtime_command( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, contentType='application/json', accept='application/vnd.amazon.eventstream', body={'command': command, 'timeout': timeout} ) for event in response.get('stream', []): if 'chunk' in event and 'contentStop' in event['chunk']: return event['chunk']['contentStop'].get('exitCode') return None # Step 1: Invoke the agent to analyze and write a fix response = client.invoke_agent_runtime( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, payload=json.dumps({"prompt": "Read JIRA-1234 and implement the fix in /workspace"}).encode() ) # Process agent response... # Step 2: Run tests deterministically exit_code = run_command('/bin/bash -c "cd /workspace && npm test"', timeout=300) # Step 3: If tests pass, commit and push if exit_code == 0: run_command('/bin/bash -c "cd /workspace && git checkout -b fix/JIRA-1234"') run_command('/bin/bash -c "cd /workspace && git add -A && git commit -m \'Fix JIRA-1234\'"') run_command('/bin/bash -c "cd /workspace && git push origin fix/JIRA-1234"')

O agente escreve o código. A plataforma executa os comandos. Cada um faz o que faz de melhor.

Casos de uso comuns

Executando suítes de teste

Depois que o agente escrever o código, execute a suíte de testes do projeto como um comando. A resposta de streaming permite que você detecte falhas precocemente e forneça uma saída de erro específica ao agente para iteração.

/bin/bash -c "cd /workspace && npm test 2>&1"
Operações do Git

Ramificar, comprometer e pressionar são operações determinísticas. Execute-os como comandos após o agente concluir seu trabalho, mantendo a lógica de controle de versão fora do LLM.

/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'"
Instalação de dependência

Inicialize o ambiente antes de invocar o agente -clone repos, instalar pacotes e configurar ferramentas de compilação. Essa preparação é executada de forma mais rápida e confiável como comandos diretos.

/bin/bash -c "pip install -r requirements.txt"
Construa e compile

Compile etapas e geração de ativos - qualquer coisa com um comando conhecido que deve ser executado exatamente conforme especificado.

/bin/bash -c "cd /workspace && cargo build --release"
Linting e validação

Execute verificações de qualidade do código como uma porta de validação depois que o agente escrever o código, antes de confirmar.

/bin/bash -c "cd /workspace && npx eslint src/ --format json"
Inspeção ambiental

Verifique o estado do tempo de execução, os pacotes instalados e as ferramentas disponíveis - úteis para depurar falhas do agente.

/bin/bash -c "python --version && node --version && git --version"
Operações de dados

Busque conjuntos de dados, faça upload de resultados, execute transformações de dados - operações de rede e computação que são executadas mais rapidamente como comandos diretos.

/bin/bash -c "aws s3 cp s3://my-bucket/data.csv /workspace/"

Principais opções de design

One-shot, execução não interativa

Cada comando gera um novo processo bash, é executado até a conclusão (ou o tempo limite) e retorna. Não há sessão de shell persistente entre os comandos. Isso corresponde à forma como as estruturas de agentes usam a execução de comandos - crie um comando, execute-o, leia a saída e decida o que fazer a seguir.

Resposta de streaming terminada HTTP/2

A saída chega conforme é produzida, não armazenada em buffer até a conclusão. UM npm test que leva dois minutos, transmite resultados em tempo real. Seu aplicativo pode detectar uma falha nos primeiros segundos e cancelar mais cedo, em vez de esperar pela execução completa.

Isolamento de contêiner

Os comandos são executados dentro do mesmo contêiner do código do seu agente. Eles veem o mesmo sistema de arquivos, variáveis de ambiente e pacotes instalados. Um arquivo que o agente escreveu em /workspace/fix.py é imediatamente visível para um comando em execução cat /workspace/fix.py.

Non-blocking para o tempo de execução

A execução do comando não bloqueia as invocações do agente. Você pode invocar o agente e executar comandos simultaneamente na mesma sessão. A plataforma lida com a simultaneidade.

Sem estado entre comandos

Cada comando inicia um novo histórico de shell, nenhuma variável de ambiente muda em relação aos comandos anteriores. Se você precisar de um estado, codifique-o no próprio comando: cd /workspace && export NODE_ENV=test && npm test.

Considerações sobre segurança

dica

Para uma visão consolidada de todas as recomendações de segurança do Runtime, consulte Melhores práticas de segurança para AgentCore Tempo de execução.

Importante

Sob o AWS modelo de responsabilidade compartilhada, você é responsável pela segurança dos comandos que executa em seu AgentCore Sessões de execução. AWS fornece a infraestrutura segura e o isolamento no nível da microVM. Você é responsável pelos comandos que executa, pelos dados que processa e pelos controles de acesso que configura.

O limite de segurança para execução de comandos é a microVM. Cada AgentCore A sessão de tempo de execução é executada em uma microVM isolada com seu próprio kernel, memória e sistema de arquivos. Os comandos que você executa não podem acessar as cargas de trabalho de outros clientes nem escapar dos limites da VM. No entanto, em sua VM, os comandos têm acesso total ao sistema de arquivos do contêiner e a quaisquer credenciais ou segredos que você tenha configurado.

Auditoria com CloudWatch Registros

AgentCore O Runtime envia o ID da solicitação e o comando de entrada para a Amazon do seu agente CloudWatch Grupo de registros de registros. Você pode usar esses registros para monitorar a atividade do comando e manter uma trilha de auditoria de quais comandos foram executados em suas sessões. A saída de execução do comando (stdout e stderr) é transmitida de volta para seu aplicativo e não é registrada pelo serviço.

Auditoria com CloudTrail

AWS CloudTrail registros InvokeAgentRuntimeCommand Chamadas de API em sua conta. Cada registro inclui metadados, como identidade do chamador, data e hora, endereço IP de origem e status da resposta. CloudTrail não registra a carga útil da solicitação ou da resposta. Uso CloudTrail para auditar quem executou comandos e quando e, em seguida, correlacionar com CloudWatch Registra registros usando o ID da solicitação para ver qual comando foi executado.

Para cargas de trabalho confidenciais, considere implementar controles adicionais, como:

  • Usando políticas do IAM para restringir quais diretores podem ligar InvokeAgentRuntimeCommand

  • Configurando endpoints VPC para manter o tráfego em sua rede

  • Configurando CloudWatch Registra filtros métricos e alarmes para detectar padrões de comando inesperados

  • Revisando CloudTrail registra regularmente tentativas de acesso não autorizado

Tratamento de erros

Ao usar o InvokeAgentRuntimeCommand durante a operação, você pode encontrar os seguintes erros:

ValidationException

Ocorre quando os parâmetros da solicitação são inválidos. Verifique se o ARN, o ID da sessão e o comando do agente estão formatados corretamente. O comando deve estar entre 1 byte e 64 KB, o tempo limite deve estar entre 1 e 3600 segundos e o ID da sessão deve ter pelo menos 33 caracteres.

ResourceNotFoundException

Ocorre quando a sessão ou o tempo de execução do agente especificado não podem ser encontrados. Verifique se o ARN do agente está correto e se a sessão está ativa.

AccessDeniedException

Ocorre quando você não tem as permissões necessárias. Certifique-se de que sua política de IAM inclua a bedrock-agentcore:InvokeAgentRuntimeCommand permissão.

ThrottlingException

Ocorre quando você excede o limite da taxa de solicitação de 25 TPS. Implemente a lógica exponencial de recuo e repetição em seu aplicativo.

RetryableConflictException

Ocorre (HTTP 409) quando um InvokeAgentRuntimeCommand a operação tem como alvo uma sessão que o serviço está provisionando ou desativando. A mensagem é Session operation in progress, please retry. Essa condição é transitória e pode ser repetida. Tente novamente com um pequeno recuo exponencial em vez de tratá-lo como terminal. O AWS Os SDKs repetem automaticamente essa exceção quando as novas tentativas padrão estão habilitadas. Se você desativou as novas tentativas ou chamou a API diretamente sem um AWS SDK, tente você mesmo novamente.

Um comando que é concluído com um código de saída diferente de zero não é um erro de API. Verifique o exitCode na contentStop evento para determinar se o comando em si foi bem-sucedido. UM status do TIMED_OUT indica que o comando excedeu o tempo limite especificado.

Práticas recomendadas

Siga estas melhores práticas ao usar o InvokeAgentRuntimeCommand operação:

  • Uso InvokeAgentRuntimeCommand para operações determinísticas (testes, git, compilações) e InvokeAgentRuntime para tarefas de raciocínio. Não encaminhe operações determinísticas por meio do LLM.

  • Inclua todas as ferramentas de desenvolvedor das quais seus comandos dependam (como git , npm , ou linguagem (runtimes) em sua imagem de contêiner por meio do Dockerfile.

  • Sempre verifique o exitCode na contentStop evento para determinar se o comando foi bem-sucedido.

  • Defina os tempos limite apropriados. Uma suíte de testes pode precisar de 5 minutos, enquanto um git push pode precisar de apenas 30 segundos.

  • Processe a saída de streaming de forma incremental para detectar falhas precocemente. Você pode cancelar um comando de longa duração em vez de esperar que ele seja concluído.

  • Codifique o estado no próprio comando usando && encadeamento (por exemplo, cd /workspace && export NODE_ENV=test && npm test ), já que cada comando inicia um novo processo de bash.

  • Use UUIDs para IDs de sessão para atender ao requisito mínimo de 33 caracteres (por exemplo, 12345678-1234-1234-1234-123456789012 ).