View a markdown version of this page

Ejecute comandos de shell en AgentCore Sesiones de ejecución - lecho rocoso amazónico AgentCore

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Ejecute comandos de shell en AgentCore Sesiones de ejecución

El InvokeAgentRuntimeCommand la operación permite ejecutar comandos de shell directamente dentro de una ejecución AgentCore Ejecute la sesión y vuelva a transmitir la salida HTTP/2. Los comandos se ejecutan en el mismo contenedor, sistema de archivos y entorno que su agente, la misma sesión que utiliza InvokeAgentRuntime . Esto permite flujos de trabajo en los que la aplicación usa el agente para tareas de razonamiento y comandos para operaciones deterministas, como la ejecución de pruebas, las operaciones de git o la configuración del entorno.

Para llamar InvokeAgentRuntimeCommand , necesitas bedrock-agentcore:InvokeAgentRuntimeCommand permisos.

Funcionamiento

InvokeAgentRuntimeCommand ejecuta un comando de shell dentro del contenedor de un activo AgentCore Sesión de ejecución y devuelve la salida por streaming.

Mismo agente, misma sesión

InvokeAgentRuntimeCommand funciona en el mismo tiempo de ejecución y sesión del agente que InvokeAgentRuntime . No se crean recursos separados. El agente con el que lo implementaste CreateAgentRuntime acepta tanto las invocaciones del agente como la ejecución de comandos en cualquier sesión activa.

nota

El AgentCore Runtime MicroVM no incluye herramientas para desarrolladores como git , npm , o tiempos de ejecución de idiomas de forma predeterminada. Todas las herramientas de las que dependan tus comandos deben incluirse en la imagen del contenedor (a través de tu Dockerfile) o instalarse dinámicamente durante el 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 cuando terminan.

Requisitos previos

  • Permiso de IAM bedrock-agentcore:InvokeAgentRuntimeCommand

  • Un válido AgentCore ARN del punto final de ejecución

nota

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

Ejecute un comando

ejemplo
AgentCore CLI
  1. Ejecute agentcore runtime exec con el ID de tiempo de ejecución. El ID de tiempo de ejecución es el último segmento del ARN de tiempo de ejecución. El identificador de sesión debe tener entre 33 y 100 caracteres:

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

    El comando imprime JSON con sessionId, command, exitCode, status, y output campos. Agregar --timeout <seconds> (1 a 3600) para limitar el tiempo de ejecución del comando, y --qualifier <endpoint> para apuntar a un punto final que no sea DEFAULT.

Python
  1. El siguiente ejemplo muestra cómo usar boto3 para ejecutar un comando en un AgentCore Sesión en 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
  1. En el siguiente ejemplo se muestra cómo utilizar el AWS SDK para Java para ejecutar un comando en un AgentCore Sesión en 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
  1. En el siguiente ejemplo se muestra cómo utilizar el AWS SDK para JavaScript v3 para ejecutar un comando en un AgentCore Sesión en 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 del agente de codificación

Un patrón común es usar InvokeAgentRuntime para razonar y InvokeAgentRuntimeCommand para operaciones deterministas en la misma sesión.

Ejemplo End-to-end flujo de trabajo del agente de 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

Ejecutar conjuntos de pruebas

Después de que el agente escriba el código, ejecute el conjunto de pruebas del proyecto como un comando. La respuesta de streaming permite detectar los errores de forma temprana y enviar los resultados de error específicos al agente para que los repita.

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

La bifurcación, la confirmación y el empuje son operaciones deterministas. Ejecútelos como comandos una vez que el agente haya completado 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

Arranque el entorno antes de invocar el agente: clone los repositorios, instale los paquetes y configure 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"
Compila y compila

Compila los pasos y la generación de activos: cualquier cosa con un comando conocido que deba ejecutarse 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 y antes de confirmarlo.

/bin/bash -c "cd /workspace && npx eslint src/ --format json"
Inspección medioambiental

Compruebe el estado de ejecución, los paquetes instalados y las herramientas disponibles, útiles para depurar los errores de los agentes.

/bin/bash -c "python --version && node --version && git --version"
Operaciones de datos

Obtenga conjuntos de datos, cargue resultados y ejecute transformaciones de datos (operaciones de red y de cómputos que se ejecutan más rápido) mediante comandos directos.

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

Opciones clave de diseño

One-shot, ejecución no interactiva

Cada comando genera un nuevo proceso de bash, se ejecuta hasta su finalización (o se agota el tiempo de espera) y regresa. No hay ninguna sesión de shell persistente entre los comandos. Esto coincide con la forma en que los marcos de los agentes utilizan la ejecución de comandos: crear un comando, ejecutarlo, leer el resultado y decidir qué hacer a continuación.

Se acabó la transmisión de la respuesta HTTP/2

La salida llega tal como se produce, no se almacena en búfer hasta su finalización. A npm test que tarda dos minutos transmite los resultados en tiempo real. Su aplicación puede detectar un error en los primeros segundos y cancelarlo antes de tiempo en lugar de esperar a que se ejecute por completo.

Aislamiento de contenedores

Los comandos se ejecutan en el 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 el agente escribió /workspace/fix.py es inmediatamente visible 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 al agente y ejecutar comandos simultáneamente en la misma sesión. La plataforma gestiona la simultaneidad.

Sin estado entre comandos

Cada comando se inicia desde cero: no se conserva el historial del shell ni los cambios en las variables de entorno con respecto a los comandos anteriores. Si necesitas un estado, codifícalo 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 Runtime, consulte Mejores prácticas de seguridad para AgentCore Tiempo de ejecución.

importante

Bajo el AWS modelo de responsabilidad compartida, usted es responsable de la seguridad de los comandos que ejecuta en su AgentCore Sesiones de ejecución. AWS proporciona la infraestructura segura y el aislamiento a nivel de microVM. Usted es responsable de los comandos que ejecuta, los datos que procesa y los controles de acceso que configura.

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

Auditoría con CloudWatch Registros

AgentCore Runtime envía el ID de la solicitud y el comando de entrada al Amazon de tu agente CloudWatch Registra el grupo de registros. Puede usar estos registros para supervisar 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 del comando (stdout y stderr) se devuelve a la aplicación y el servicio no lo registra.

Auditoría con CloudTrail

AWS CloudTrail récords InvokeAgentRuntimeCommand Llamadas a la API en tu 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. Utilice CloudTrail para auditar quién ejecutó los comandos y cuándo y, a continuación, correlacionarlos con CloudWatch Registra los registros con el identificador de solicitud para ver qué comando se ejecutó.

Para las cargas de trabajo delicadas, considera la posibilidad de implementar controles adicionales, como:

  • Usar políticas de IAM para restringir qué directores pueden llamar InvokeAgentRuntimeCommand

  • Configurar los puntos finales de la VPC para mantener el tráfico dentro de la red

  • Configuración CloudWatch Registra los filtros métricos y las alarmas para detectar patrones de comandos inesperados

  • Revisando CloudTrail registra periódicamente los intentos de acceso no autorizados

Gestión de errores

Al usar el InvokeAgentRuntimeCommand durante la 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 del agente, el identificador de sesión y el comando tengan el formato correcto. El comando debe tener entre 1 byte y 64 KB, el tiempo de espera debe estar entre 1 y 3600 segundos y el identificador de sesión debe tener al menos 33 caracteres.

ResourceNotFoundException

Se produce cuando no se puede encontrar el tiempo de ejecución o la sesión del agente especificados. Compruebe que el ARN del agente es correcto y que la sesión está activa.

AccessDeniedException

Se produce cuando no tienes los permisos necesarios. Asegúrese de que su política de IAM incluya los bedrock-agentcore:InvokeAgentRuntimeCommand permiso.

ThrottlingException

Se produce cuando se supera el límite de velocidad de solicitudes de 25 TPS. Implemente la lógica de retroceso y reintento exponencial en su aplicación.

RetryableConflictException

Se produce (HTTP 409) cuando un InvokeAgentRuntimeCommand la operación tiene como objetivo una sesión que el servicio está aprovisionando o desactivando. El mensaje es Session operation in progress, please retry. Esta afección es transitoria y se puede volver a intentar. Vuelva a intentarlo con un breve retroceso exponencial en lugar de tratarlo como terminal. El AWS Los SDK reintentan automáticamente esta excepción cuando están habilitados los reintentos predeterminados. Si inhabilitaste los reintentos o llamaste a la API directamente sin una AWS SDK, vuelve a intentarlo tú mismo.

Un comando que se completa con un código de salida distinto de cero no es un error de API. Compruebe el exitCode en el contentStop evento para determinar si el comando en sí tuvo éxito. UN status de TIMED_OUT indica que el comando ha superado el tiempo de espera especificado.

Prácticas recomendadas

Siga estas prácticas recomendadas cuando utilice el InvokeAgentRuntimeCommand operación:

  • Uso InvokeAgentRuntimeCommand para operaciones deterministas (pruebas, git, compilaciones) y InvokeAgentRuntime para tareas de razonamiento. No dirija las operaciones deterministas a través del LLM.

  • Incluye cualquier herramienta de desarrollador de la que dependan tus comandos (como git , npm , o idiomas (tiempos de ejecución) en la imagen de su contenedor a través de su Dockerfile.

  • Compruebe siempre el exitCode en el contentStop evento para determinar si el comando se ejecutó correctamente.

  • Establezca los tiempos de espera adecuados. Un conjunto de pruebas puede necesitar 5 minutos, mientras que un git push puede que solo necesite 30 segundos.

  • Procese la salida de streaming de forma incremental para detectar los errores de forma temprana. Puede cancelar un comando que lleva mucho tiempo ejecutándose en lugar de esperar a que finalice.

  • Codifique el estado en el propio comando mediante && encadenamiento (por ejemplo, cd /workspace && export NODE_ENV=test && npm test ), ya que cada comando inicia un nuevo proceso de bash.

  • Usa los UUID para los ID de sesión para cumplir con el requisito mínimo de 33 caracteres (por ejemplo, 12345678-1234-1234-1234-123456789012 ).