View a markdown version of this page

Carcasas interactivas (terminales) - 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.

Carcasas interactivas (terminales)

El InvokeAgentRuntimeCommandShell la operación abre una sesión de terminal interactiva y persistente dentro de una ejecución AgentCore Se acabó la sesión de ejecución WebSocket. A diferencia de la ejecución de comandos de una sola vez, las sesiones de shell mantienen el estado: las variables de entorno, el directorio de trabajo y el historial de comandos se transfieren entre las entradas. Esto permite la depuración, la inspección del entorno y la creación de experiencias de terminal en su aplicación.

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

Funcionamiento

InvokeAgentRuntimeCommandShell establece un WebSocket conexión a un proceso de shell interactivo que se ejecuta dentro de la sesión de su agente. La conexión utiliza marcos binarios para transmitir la entrada y la salida del terminal en ambas direcciones.

Mismo agente, misma sesión

InvokeAgentRuntimeCommandShell funciona en el mismo tiempo de ejecución del agente que InvokeAgentRuntime y InvokeAgentRuntimeCommand. No se crean recursos separados. El agente con el que lo implementaste CreateAgentRuntime acepta conexiones de shell en cualquier sesión activa.

nota

Puede pasar un session_id para segmentar una sesión de tiempo de ejecución específica. Si se omite, se crea una nueva sesión para cada conexión. Para usar la reconexión, debe almacenar y reutilizar ambas session_id y shellId.

La conexión admite:

Característica Description (Descripción)

Estado persistente

Las variables de entorno, el directorio de trabajo y el historial de comandos se transfieren a las entradas de la misma sesión.

Reconexión

Proporcione lo mismo session_id y shellId para volver a conectarse a la misma carcasa después de una desconexión. El servicio reproduce hasta 256 KB de salida almacenada en búfer.

Múltiples shells simultáneos

Hasta 10 sesiones de shell activas (terminales) por tiempo de ejecución. Las conexiones nuevas se rechazan cuando están al máximo de su capacidad.

Requisitos previos

  • Permiso de IAM bedrock-agentcore:InvokeAgentRuntimeCommandShell

  • Un válido AgentCore ARN de punto final de ejecución con un tiempo de ejecución en estado READY

nota

Los agentes creados después del 5 de junio de 2026 admiten automáticamente los shells interactivos (terminales). Si implementó el agente antes de esta fecha, debe volver a implementarlo para actualizar el tiempo de ejecución del agente.

Utilizando el AgentCore CLI

Para obtener instrucciones de instalación y configuración, consulte Comience con el AgentCore CLI.

La CLI proporciona una experiencia de terminal interactiva integrada. Pase un ID de tiempo de ejecución, no un ARN de tiempo de ejecución. Para un tiempo de ejecución en un AgentCore el ID de tiempo de ejecución es el último segmento del tiempo de ejecución arn en la salida de agentcore status --json:

Para un entorno gestionado por un arnés, utilice agentcore harness shell --id <harness-id> en lugar del ID del motor de ejecución gestionado. Consulte Abra la carcasa de un arnés con el AgentCore CLIP.

agentcore runtime shell --id <runtime-id>

Sin --qualifier, la CLI le pide que elija un punto final. Para seleccionar un punto final directamente:

agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --region us-west-2

Utilice --session-id para abrir el shell en una sesión de Runtime específica:

agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --session-id <runtime-session-id>

Tras la conexión, la CLI imprime el ID de la sesión en tiempo de ejecución, el ID del shell y un comando de reconexión completo. Presiona Ctrl+] para desconectar el terminal local mientras se mantiene el shell remoto en funcionamiento:

Connected Session ID: <runtime-session-id> Shell ID: <shell-id> Ctrl+D or 'exit' to close · Ctrl+] to detach To reconnect: agentcore runtime shell --id <runtime-id> --qualifier DEFAULT --session-id <runtime-session-id> --shell-id <shell-id> --region us-west-2

Ejecute el comando impreso para volver a conectarse al mismo shell. Cuando construya el comando usted mismo, --shell-id requiere --session-id:

agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --session-id <runtime-session-id> \ --shell-id <shell-id> \ --region us-west-2

En el caso de un Runtime configurado con la autorización CUSTOM_JWT, pasa también su token de portador:

agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --bearer-token file://token.txt

El comando de reconexión nunca incluye un token de portador. Pase --bearer-token de nuevo al volver a conectarse a un CUSTOM_JWT Runtime.

Introduzca exit o presione Ctrl+D para cerrar el shell remoto de forma permanente. Presiona Ctrl+] cuando quieras desconectarte y volver a conectarte más tarde.

Para ejecutar un solo comando sin abrir un shell, utilice agentcore runtime exec:

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

Para ver más ejemplos de CLI, consulte AgentCore muestras en GitHub.

Usando el AgentCore SDK

Instala el SDK de Python:

pip install bedrock-agentcore
ejemplo
SigV4 (default)
  1. El siguiente ejemplo muestra cómo abrir una sesión de shell de forma predeterminada AWS credenciales.

    import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ShellChannel async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn) as shell: print(f"Connected. Shell ID: {shell.shell_id}") # Send a command await shell.send("echo Hello from AgentCore Shell\n") # Read output frames async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") if "Hello from AgentCore Shell" in frame.text: break asyncio.run(main())
Pre-signed URL
  1. El siguiente ejemplo muestra cómo abrir una sesión de shell con una URL prefirmada.

    import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, PresignedAuth, ShellChannel async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn, auth=PresignedAuth(expires=120)) as shell: await shell.send("whoami\n") async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") break asyncio.run(main())
OAuth
  1. En el siguiente ejemplo, se muestra cómo abrir una sesión de shell con un token portador de OAuth.

    import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, OAuthAuth, ShellChannel async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" bearer_token = "your_oauth_token_here" client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn, auth=OAuthAuth(bearer_token=bearer_token)) as shell: await shell.send("echo oauth-connected\n") async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") if "oauth-connected" in frame.text: break asyncio.run(main())

Reconexión

Un patrón común es usar shellId volver a conectarse a un shell después de una desconexión, conservando todo el estado de la sesión.

import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient async def main(): client = AgentCoreRuntimeClient(region="us-west-2") runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" session_id = "my-session-0000000000000000000000" shell_id = "my-shell" shell = await client.open_shell( runtime_arn, session_id=session_id, shell_id=shell_id, ).__aenter__() print(f"connected (reconnected={shell.reconnected})") await shell.send("export GREETING='hello'\n") await asyncio.sleep(1) async with client.open_shell( runtime_arn, session_id=session_id, shell_id=shell_id, ) as shell2: print(f"reconnected (reconnected={shell2.reconnected})") assert shell2.reconnected if __name__ == "__main__": asyncio.run(main())

Auto-reconnect

El SDK también puede volver a conectarse automáticamente cuando WebSocket la conexión se interrumpe. Utilice ReconnectConfig para habilitar esto:

import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel async def on_reconnect(): print("Reconnected") async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" shell_id = "my-persistent-shell" config = ReconnectConfig(max_retries=5, base_delay=0.5, on_reconnect=on_reconnect) client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn, shell_id=shell_id, reconnect_config=config) as shell: # If the connection drops, the SDK retries automatically await shell.send("long-running-command\n") async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") asyncio.run(main())

Para ver más ejemplos de SDK, consulte AgentCore muestras en GitHub.

Casos de uso comunes

Depuración interactiva

Abre un shell para inspeccionar el entorno de ejecución de tu agente: comprueba los paquetes instalados, lee los archivos de registro, examina el sistema de archivos o prueba los comandos antes de añadirlos al código del agente.

python --version && pip list | head -20
Inspección del entorno

Verifique las variables de entorno, la conectividad de la red, las herramientas disponibles y el estado del sistema de archivos. Resulta útil para diagnosticar errores de agentes o validar la configuración de implementación.

env | grep AWS && curl -s http://169.254.169.254/latest/meta-data/
Acceso al terminal del agente de codificación

Los agentes de codificación de IA utilizan shells interactivos (terminales) como entorno de ejecución. Cuando un agente de codificación necesita ejecutar código, instalar paquetes o ejecutar pruebas, abre una sesión de shell en el AgentCore Ejecuta y ejecuta los comandos directamente, del mismo modo que un desarrollador utilizaría una terminal. Por ejemplo, Claude Code, Amazon Kiro y OpenAI Codex se conectan cada uno a una sesión de shell en la que pueden escribir código, ejecutarlo, observar el resultado y corregir errores de forma iterativa. El estado persistente significa que el agente puede ejecutar una secuencia de comandos sin perder el contexto entre los pasos.

# A coding agent opens a shell and iterates on code async with client.open_shell(runtime_arn, shell_id="agent-workspace") as shell: await shell.send("cd /workspace && git clone https://github.com/user/repo.git\n") await shell.send("cd repo && pip install -r requirements.txt\n") await shell.send("python -m pytest tests/ -v\n") # Agent reads test output, fixes failures, re-runs — all in the same shell
Long-running procesos

Inicie procesos que sobrevivan a una sola solicitud HTTP. Utilice la reconexión para comprobar el progreso o para proporcionar información adicional a lo largo del tiempo.

nohup python train.py > /tmp/train.log 2>&1 &

Opciones clave de diseño

Sesiones interactivas persistentes

Cada conexión se asigna a un proceso de shell de larga duración. Puede enviar varios comandos sin restablecer la conexión y el estado acumulado por los comandos anteriores (variables exportadas, cd cambios) está disponible para los posteriores.

Se acabó el encuadre binario WebSocket

Terminal I/O se transmite como binario WebSocket marcos. Esto admite secuencias de control de terminales sin procesar, colores, movimientos del cursor y aplicaciones de pantalla completa sin procesar sin sobrecargar la codificación.

Reconexión con reproducción de salida

Cuando te vuelvas a conectar usando el mismo shellId, el servicio reproduce hasta 256 KB de la salida reciente. Esto le permite recuperarse de las interrupciones de la red sin perder el contexto. El proceso de shell continúa ejecutándose durante la desconexión.

Límite de sesiones

Cuando ya hay 10 sesiones de shell (terminales) abiertas en un tiempo de ejecución, las nuevas conexiones se rechazan y se produce un error. Debe cerrar una sesión existente antes de abrir una nueva.

Consideraciones de seguridad

sugerencia

Para obtener una vista consolidada de todas las recomendaciones de seguridad de 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 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 las sesiones de shell (terminales) 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. Las sesiones de Shell no pueden acceder a las cargas de trabajo de otros clientes ni escapar de los límites de las máquinas virtuales. Sin embargo, dentro de su máquina virtual, los comandos de shell tienen acceso total al sistema de archivos del contenedor y a cualquier credencial o secreto que haya configurado.

Auditoría con CloudWatch Registros

AgentCore Runtime envía el identificador de la solicitud y los metadatos de la conexión al Amazon de tu agente CloudWatch Registra el grupo de registros. Puede usar estos registros para supervisar la actividad de las conexiones de shell y mantener un registro de auditoría. Terminal I/O contenido (stdin/stdout) se transmite a su cliente y el servicio no lo registra.

Auditoría con CloudTrail

AWS CloudTrail récords InvokeAgentRuntimeCommandShell 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 abrió las sesiones de shell y cuándo y, a continuación, correlacionarlas con CloudWatch Registra los datos de conexión con el ID de solicitud.

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

  • Uso de políticas de IAM para restringir qué directores pueden llamar InvokeAgentRuntimeCommandShell

  • 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 conexión inesperados

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

Gestión de errores

Al establecer una conexión de sesión de shell, es posible que se produzcan los siguientes errores durante el WebSocket actualización:

Si la CLI informa Server rejected WebSocket connection: HTTP 400 y el tiempo de ejecución lo administra un arnés, utilice el comando Harness shell con el identificador del arnés. Otras respuestas HTTP 400 pueden tener causas diferentes; verifique el recurso y la solicitud en lugar de dar por sentado que cada rechazo identifica un Harness.

ValidationException

Se produce cuando los parámetros de la solicitud no son válidos. Esto puede ocurrir si el identificador de sesión tiene menos de 33 caracteres, si la función no está habilitada en la región de destino o si el agente no está en estado LISTO.

AccessDeniedException

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

ResourceNotFoundException

Se produce cuando no se puede encontrar el tiempo de ejecución del agente especificado. Compruebe que el ARN en tiempo de ejecución sea correcto.

RuntimeClientError (424)

Ocurre en varios escenarios: (1) Se alcanza el máximo de sesiones simultáneas de shell (terminales) (10 abiertas); cierra una sesión existente y vuelve a intentarlo. (2) El formato del identificador de shell no es válido: debe contener entre 1 y 128 caracteres alfanuméricos, guiones bajos o guiones. (3) No se puede acceder al tiempo de ejecución: vuelva a intentarlo después de retroceder. Analice el JSON del cuerpo de la respuesta. error campo para distinguir las causas.

ThrottlingException

Se produce cuando se supera el límite de velocidad de la API. Implemente la lógica de retroceso y reintento exponencial.

ConflictException

Otra conexión afirma lo mismo shellId simultáneamente. Vuelva a intentarlo después de 1 segundo. Se trata de una condición de carrera limitada (no un estado persistente) y se resuelve inmediatamente al volver a intentarlo.

RetryableConflictException (409)

Se produce cuando se abre una conexión de sesión shell mientras el servicio aprovisiona o desactiva la sesión de destino. El mensaje es Session operation in progress, please retry. Esta afección es transitoria y se puede volver a intentar. La ventana es breve y las sesiones que ya se están ejecutando no se ven afectadas. Vuelva a intentarlo con un breve retroceso exponencial. Porque InvokeAgentRuntimeCommandShell es un WebSocket API, la AWS Los SDK no lo reintentan automáticamente. Vuelva a intentarlo usted mismo.

Una vez conectada, los siguientes códigos de cierre indican el motivo por el que se interrumpió la conexión:

Código Significado Acción del cliente

1000

Cierre normal: la carcasa salió limpiamente o se desconectó correctamente

Muestra «desconectado». Terminación normal.

1001

Desaparición: implementación o cierre del servidor

Auto-reconnect con almacenamiento shellId.

1003

Datos no compatibles: se envían después de 5 marcos de texto consecutivos (protocolo solo binario)

NO te vuelvas a conectar automáticamente. Cambie a marcos binarios.

1006

Cierre anormal: se sintetiza localmente cuando no se recibe ningún fotograma cerrado (muerte de la red, TCP RST)

Auto-reconnect con almacenado shellId.

1008

Infracción de la política: el TTL de la conexión ha caducado (1 hora), se ha superado el límite de velocidad de fotogramas (250) frames/sec), o desbordamiento del búfer de escritura

Auto-reconnect para la caducidad del TTL (TTL nuevo al volver a conectarse). Para el límite de velocidad: apágalo y, a continuación, vuelve a conectarte.

1009

El mensaje es demasiado grande: la carga útil de fotogramas supera los 64 KB

Reduzca el tamaño del marco (el fragmento a menos de 64 KB) y vuelva a conectarlo. La sesión sigue activa.

1011

Error del servidor: fallo interno inesperado

Vuelva a intentarlo con la opción de retroceso.

4000

Reemplazado: otro cliente conectado al mismo shellId

NO vuelva a conectarse automáticamente. Muestra «sesión adjunta desde otro cliente».

Prácticas recomendadas

Siga estas prácticas recomendadas cuando lo utilice InvokeAgentRuntimeCommandShell:

  • Usa un único shellId (como un UUID) para cada sesión lógica para permitir la reconexión. Almacene el shellId del lado del cliente.

  • Utilice ReconnectConfig en el SDK para gestionar automáticamente las interrupciones transitorias de la red sin una lógica de reconexión manual.

  • Lea los fotogramas de salida con prontitud. Si el cliente se retrasa, el búfer de escritura del servidor se llena y la conexión se cierra con código 1008.

  • Para entradas de gran tamaño (como pegar un archivo), divida el contenido en fragmentos de menos de 64 KB por fotograma para evitar cerrar el código 1009.

  • Establezca los tiempos de espera de conexión adecuados. La duración máxima de la conexión es de 1 hora; vuelve a conectarte con la misma shellId para continuar más allá de eso.

  • Cierre las sesiones de forma explícita cuando haya terminado. Las sesiones independientes se tienen en cuenta para el límite de 10 sesiones.

Cuotas y límites

Límite Valor Description (Descripción)

Tamaño máximo de carga útil de fotogramas

64 KB

Los fotogramas que superen este límite dan como resultado un código cerrado 1009.

Velocidad de fotogramas

250 frames/sec

Superar este límite activa el código de cierre 1008.

Duración máxima de la conexión

1 hora

La conexión se cierra con código 1008. Vuelva a conectarse usando el mismo shellId para continuar.

Sesiones de shell simultáneas (terminales) por tiempo de ejecución

10

Las conexiones nuevas se rechazan si ya hay 10 sesiones abiertas. Cierre una sesión existente y vuelva a intentarlo.

Búfer de reconexión

256 KB

Salida máxima que se reproduce al volver a conectarse a un shell.

Para ver los límites de servicio completos, consulte Cuotas para Amazon Bedrock AgentCore.