Funcionamiento Requisitos previos Ejecute un comando Ejemplo de flujo de trabajo de agente de codificación Casos de uso comunes Principales opciones de diseño Consideraciones de seguridad Gestión de errores Prácticas recomendadas

Ejecuta comandos de shell en sesiones AgentCore de tiempo de ejecución

La InvokeAgentRuntimeCommandoperación permite ejecutar comandos de shell directamente dentro de una sesión AgentCore de Runtime en ejecución y volver a transmitir el resultado HTTP/2. Los comandos se ejecutan en el mismo contenedor, sistema de archivos y entorno que el agente, es decir, en la misma sesión utilizada por. InvokeAgentRuntime Esto permite flujos de trabajo en los que la aplicación utiliza el agente para razonar las tareas y los comandos para operaciones deterministas, como la ejecución de pruebas, las operaciones de git o la configuración del entorno.

Para llamarInvokeAgentRuntimeCommand, necesita bedrock-agentcore:InvokeAgentRuntimeCommand permisos.

Funcionamiento

InvokeAgentRuntimeCommandejecuta un comando de shell dentro del contenedor de una sesión de AgentCore tiempo de ejecución activa y devuelve el resultado.

El mismo agente, la misma sesión

InvokeAgentRuntimeCommandfunciona en el mismo tiempo de ejecución y sesión del agente queInvokeAgentRuntime. No se crean recursos independientes. El agente con el que ha desplegado CreateAgentRuntime acepta tanto las invocaciones del agente como la ejecución de comandos en cualquier sesión activa.

nota

De forma predeterminada, la microVM en tiempo de AgentCore ejecución no incluye herramientas para desarrolladores gitnpm, ni tiempos de ejecución de idiomas. Todas las herramientas de las que dependan tus comandos deben incluirse en la imagen del contenedor (a través del Dockerfile) o instalarse dinámicamente en tiempo de ejecución.

La respuesta es una secuencia de tres tipos de eventos:

Event	Cuando	Contiene
`contentStart`	Primer fragmento	Confirma que el comando se inició
`contentDelta`	Durante la ejecución	Salida de `stdout` and/or `stderr`
`contentStop`	Último trozo	`exitCode`y `status` (`COMPLETED`o`TIMED_OUT`)

Transmisiones de salida en tiempo real. Los resultados se ven a medida que se ejecutan, no una vez finalizados.

Requisitos previos

Permiso de IAM bedrock-agentcore:InvokeAgentRuntimeCommand
Un ARN AgentCore de punto final de ejecución válido

nota

Los agentes creados después del 17 de marzo de 2026 admiten la ejecución automática de comandos. Si desplegó su agente antes de esta fecha, debe volver a desplegarlo para actualizar el tiempo de ejecución del agente.

Ejecute un comando

ejemplo

Python

El siguiente ejemplo muestra cómo usar boto3 para ejecutar un comando en una sesión de AgentCore tiempo de ejecución.


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

El siguiente ejemplo muestra cómo usar el AWS SDK para Java para ejecutar un comando en una sesión de AgentCore tiempo de ejecución.


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

El siguiente ejemplo muestra cómo usar el AWS SDK de la JavaScript versión 3 para ejecutar un comando en una sesión de AgentCore tiempo de ejecución.


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();

Ejemplo de flujo de trabajo de agente de codificación

Un patrón común es usarlo InvokeAgentRuntime para el razonamiento y InvokeAgentRuntimeCommand para las operaciones deterministas en la misma sesión.

Ejemplo de flujo de trabajo del agente de End-to-end codificación


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"')

El agente escribe el código. La plataforma ejecuta los comandos. Cada uno hace lo que mejor sabe hacer.

Casos de uso comunes

Ejecutando suites de prueba

Una vez que el agente escriba el código, ejecute el conjunto de pruebas del proyecto como un comando. La respuesta de transmisión le permite detectar los errores de forma temprana y enviar los resultados de errores específicos al agente para que los repita.


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

Operaciones de Git

La ramificación, el compromiso y el empuje son operaciones deterministas. Ejecútelas como comandos una vez que el agente complete su trabajo, manteniendo la lógica de control de versiones fuera del LLM.


/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'"

Instalación de dependencias

Inicie el entorno antes de invocar los repositorios de clones del agente, instalar paquetes y configurar las herramientas de compilación. Esta preparación se ejecuta de forma más rápida y fiable mediante comandos directos.


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

Construye y compila

Compila los pasos y la generación de activos: cualquier cosa con un comando conocido que se ejecute exactamente como se especifica.


/bin/bash -c "cd /workspace && cargo build --release"

Linting y validación

Realice comprobaciones de calidad del código como puerta de validación después de que el agente escriba el código, antes de confirmarlo.


/bin/bash -c "cd /workspace && npx eslint src/ --format json"

Inspección ambiental

Compruebe el estado del tiempo de ejecución, los paquetes instalados y las herramientas disponibles, lo que resulta útil para depurar los errores de los agentes.


/bin/bash -c "python --version && node --version && git --version"

Operaciones de datos

Obtenga conjuntos de datos, cargue los resultados, ejecute transformaciones de datos: operaciones de red y cómputo que se ejecutan más rápido como comandos directos.


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

Principales opciones de diseño

One-shot, ejecución no interactiva: Cada comando genera un nuevo proceso bash, se ejecuta hasta que se completa (o se agota el tiempo de espera) y regresa. No hay una sesión de shell persistente entre los comandos. Esto coincide con la forma en que los marcos de agentes utilizan la ejecución de comandos: crear un comando, ejecutarlo, leer el resultado y decidir qué hacer a continuación.
Se acabó la respuesta de streaming HTTP/2: La salida llega tal como se produce, no se almacena en búfer hasta que se completa. Los resultados npm test de una emisión de dos minutos se producen en tiempo real. La aplicación puede detectar un error en los primeros segundos y cancelarla antes de tiempo en lugar de esperar a que se ejecute por completo.
Aislamiento de contenedores: Los comandos se ejecutan dentro del mismo contenedor que el código del agente. Ven el mismo sistema de archivos, variables de entorno y paquetes instalados. Un archivo en el que escribió el agente /workspace/fix.py es visible inmediatamente para un comando en ejecución. cat /workspace/fix.py
Non-blocking al tiempo de ejecución: La ejecución de comandos no bloquea las invocaciones de los agentes. Puede invocar el agente y ejecutar comandos simultáneamente en la misma sesión. La plataforma gestiona la simultaneidad.
Sin estado entre comandos: Cada comando se inicia de forma nueva, sin historial de comandos ni cambios en las variables de entorno con respecto a los comandos anteriores. Si necesita estado, codifíquelo en el propio comando:. cd /workspace && export NODE_ENV=test && npm test

Consideraciones de seguridad

sugerencia

Para obtener una vista consolidada de todas las recomendaciones de seguridad en tiempo de ejecución, consulte las mejores prácticas de seguridad para AgentCore Runtime.

importante

Según el modelo de responsabilidad AWS compartida, usted es responsable de la seguridad de los comandos que ejecuta en sus sesiones AgentCore de Runtime. AWS proporciona la infraestructura segura y el aislamiento a nivel de microVM. Usted es responsable de los comandos que ejecuta, de los datos que procesa y de los controles de acceso que configura.

El límite de seguridad para la ejecución de comandos es la microVM. Cada sesión AgentCore de Runtime se ejecuta en una microVM aislada con su propio núcleo, memoria y sistema de archivos. Los comandos que ejecute no pueden acceder a las cargas de trabajo de otros clientes ni escapar del límite de las máquinas virtuales. Sin embargo, dentro de su máquina virtual, los comandos tienen acceso total al sistema de archivos del contenedor y a cualquier credencial o secreto que haya configurado.

Auditoría con registros CloudWatch

AgentCore Runtime envía el ID de solicitud y el comando de entrada al grupo de CloudWatch registros de Amazon Logs de tu agente. Puede usar estos registros para monitorear la actividad de los comandos y mantener un registro de auditoría de los comandos que se ejecutaron en sus sesiones. El resultado de la ejecución de comandos (stdout y stderr) se devuelve a la aplicación y el servicio no lo registra.

Auditoría con CloudTrail

AWS CloudTrail registra las llamadas a la InvokeAgentRuntimeCommand API en su cuenta. Cada registro incluye metadatos como la identidad de la persona que llama, la marca de tiempo, la dirección IP de origen y el estado de la respuesta. CloudTrail no registra la carga útil de la solicitud o la respuesta. Se usa CloudTrail para auditar quién ejecutó los comandos y cuándo, y luego se correlaciona con CloudWatch los registros de Logs utilizando el ID de solicitud para ver qué comando se ejecutó.

En el caso de las cargas de trabajo delicadas, considere la posibilidad de implementar controles adicionales, como los siguientes:

Utilizar las políticas de IAM para restringir los directores que pueden llamar InvokeAgentRuntimeCommand
Configuración de puntos finales de VPC para mantener el tráfico dentro de la red
Configuración de alarmas y filtros métricos de CloudWatch Logs para detectar patrones de comandos inesperados
Revisar CloudTrail los registros con regularidad para detectar intentos de acceso no autorizados

Gestión de errores

Al utilizar la InvokeAgentRuntimeCommand operación, es posible que se produzcan los siguientes errores:

ValidationException: Se produce cuando los parámetros de la solicitud no son válidos. Compruebe que el ARN, el ID de sesión y el comando de su agente estén formateados correctamente. El comando debe tener entre 1 byte y 64 KB, el tiempo de espera debe estar entre 1 y 3600 segundos y el ID de sesión debe tener al menos 33 caracteres.
ResourceNotFoundException: Se produce cuando no se encuentra la sesión o el tiempo de ejecución del agente especificado. Compruebe que el ARN del agente es correcto y que la sesión está activa.
AccessDeniedException: Se produce cuando no se tienen los permisos necesarios. Asegúrese de que su política de IAM incluya el bedrock-agentcore:InvokeAgentRuntimeCommand permiso.
ThrottlingException: Se produce cuando se supera el límite de velocidad de solicitudes de 25 TPS. Implemente una lógica de retroceso exponencial y reintento en su aplicación.

Un comando que se complete con un código de salida distinto de cero no constituye un error de API. Active esta casilla exitCode en contentStop este caso para determinar si el comando en sí se ha realizado correctamente. Un valor status de TIMED_OUT indica que el comando ha superado el tiempo de espera especificado.

Prácticas recomendadas

Siga estas prácticas recomendadas al utilizar la InvokeAgentRuntimeCommand operación:

InvokeAgentRuntimeCommandUtilícela para operaciones deterministas (pruebas, git, compilaciones) y InvokeAgentRuntime para tareas de razonamiento. No dirija las operaciones deterministas a través del LLM.
Incluya cualquier herramienta de desarrollador de la que dependan sus comandos (como gitnpm, o los tiempos de ejecución del idioma) en la imagen del contenedor a través de su Dockerfile.
Siempre compruébalo exitCode en contentStop este caso para determinar si el comando se ejecutó correctamente.
Establezca los tiempos de espera adecuados. Un conjunto de pruebas puede necesitar 5 minutos, mientras que git push uno solo necesitará 30 segundos.
Procese la salida de la transmisión de forma incremental para detectar los fallos de forma temprana. Puede cancelar un comando de larga ejecución en lugar de esperar a que se complete.
Codifique el estado en el propio comando mediante el && encadenamiento (por ejemplocd /workspace && export NODE_ENV=test && npm test), ya que cada comando inicia un nuevo proceso bash.
Utilice los UUID como ID de sesión para cumplir con el requisito mínimo de 33 caracteres (por ejemplo,). 12345678-1234-1234-1234-123456789012

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Ejecución de shell

Conchas interactivas (terminales)