Como funciona Pré-requisitos Executar um comando Exemplo de fluxo de trabalho de agente de codificação Casos de uso comuns Principais opções de design Considerações sobre segurança Tratamento de erros Práticas recomendadas

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

A InvokeAgentRuntimeCommandoperação permite que você execute comandos de shell diretamente dentro de uma sessão AgentCore de tempo de execução e retransmita a saída 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 tarefas de raciocínio e comandos para operações determinísticas, como execução de testes, operações do git ou configuração do ambiente.

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

Como funciona

InvokeAgentRuntimeCommandexecuta um comando shell dentro do contêiner de uma sessão ativa do AgentCore Runtime e transmite a saída de volta.

Mesmo agente, mesma sessão

InvokeAgentRuntimeCommandopera no mesmo tempo de execução e sessão do agente queInvokeAgentRuntime. Você não cria recursos separados. O agente com o qual você implantou CreateAgentRuntime aceita as invocações do agente e a execução do comando em qualquer sessão ativa.

nota

O AgentCore Runtime MicroVM não inclui ferramentas de desenvolvedorgit, comonpm, ou tempos de execução de linguagem 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 correm, não depois de terminarem.

Pré-requisitos

Permissão bedrock-agentcore:InvokeAgentRuntimeCommand do IAM
Um ARN de endpoint AgentCore de tempo de execução válido

nota

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

Python

O exemplo a seguir mostra como usar o boto3 para executar um comando em uma sessão de AgentCore 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

O exemplo a seguir mostra como usar o AWS SDK for Java para executar um comando em AgentCore uma 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

O exemplo a seguir mostra como usar o AWS SDK para JavaScript v3 para executar um comando em uma sessão de AgentCore 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 de agente de codificação

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

Exemplo de fluxo End-to-end 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 o conjunto de testes do projeto como um comando. A resposta de streaming permite detectar falhas precocemente e enviar uma saída de erro específica de volta ao agente para iteração.


/bin/bash -c "cd /workspace && npm test 2>&1"

Operações Git

Ramificar, comprometer e promover 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ências

Inicialize o ambiente antes de invocar o agente -clone repos, instale pacotes e configure as 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"

Crie 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 grava 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 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 - criam um comando, o executam, lêem a saída e decidem o que fazer a seguir.
Resposta de streaming encerrada HTTP/2: A saída chega à medida que é produzida, não armazenada em buffer até a conclusão. Uma transmissão npm test que leva dois minutos para transmitir 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 agente. Eles veem o mesmo sistema de arquivos, variáveis de ambiente e pacotes instalados. Um arquivo no qual o agente escreveu /workspace/fix.py fica imediatamente visível para um comando em execuçãocat /workspace/fix.py.
Non-blocking ao 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 concorrência.
Apátrida entre comandos: Cada comando inicia do zero - sem histórico do shell, nenhuma alteração na variável de ambiente em relação aos comandos anteriores é transferida. Se você precisar de estado, codifique-o no próprio comando:cd /workspace && export NODE_ENV=test && npm test.

Considerações sobre segurança

dica

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

Importante

No modelo de responsabilidade AWS compartilhada, você é responsável pela segurança dos comandos que executa nas sessões do AgentCore Runtime. 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 é o microVM. Cada sessão do AgentCore Runtime é 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, na sua VM, os comandos têm acesso total ao sistema de arquivos do contêiner e a todas as credenciais ou segredos que você configurou.

Auditoria com registros CloudWatch

AgentCore O Runtime envia o ID da solicitação e o comando de entrada para o grupo de CloudWatch logs do Amazon Logs do seu agente. 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 da 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 registra chamadas de InvokeAgentRuntimeCommand API em sua conta. Cada registro inclui metadados, como identidade do chamador, carimbo de data/hora, endereço IP de origem e status da resposta. CloudTrail não registra a carga útil da solicitação ou resposta. Use CloudTrail para auditar quem executou os comandos e quando, em seguida, correlacione com os CloudWatch registros de 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 filtros métricos e alarmes do CloudWatch Logs para detectar padrões de comando inesperados
Analisar CloudTrail os registros regularmente em busca de tentativas de acesso não autorizado

Tratamento de erros

Ao usar a InvokeAgentRuntimeCommand 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 seu 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 o tempo de execução ou a sessã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 do 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 de recuo exponencial e tente novamente em seu aplicativo.

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

Práticas recomendadas

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

Use 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 dependem (como git tempos de execução de linguagem) na imagem do contêiner por meio do Dockerfile. npm
Sempre verifique o exitCode 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 uma 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 execuçã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), pois cada comando inicia um novo processo bash.
Use UUIDs como IDs de sessão para atender ao requisito mínimo de 33 caracteres (por exemplo,). 12345678-1234-1234-1234-123456789012

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Execução de shell

Conchas interativas (terminais)