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.
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 |
|---|---|---|
|
|
Primer fragmento |
Confirma que el comando se inició |
|
|
Durante la ejecución |
Salida de |
|
|
Último trozo |
|
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
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
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 testque 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.pyes inmediatamente visible para un comando en ejecucióncat /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
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.
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:InvokeAgentRuntimeCommandpermiso. - 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
InvokeAgentRuntimeCommandla operación tiene como objetivo una sesión que el servicio está aprovisionando o desactivando. El mensaje esSession 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
InvokeAgentRuntimeCommandpara operaciones deterministas (pruebas, git, compilaciones) yInvokeAgentRuntimepara 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
exitCodeen elcontentStopevento 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 pushpuede 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).