Funcionamiento Requisitos previos Uso de la AgentCore CLI Uso del AgentCore SDK Casos de uso comunes Principales opciones de diseño Consideraciones de seguridad Gestión de errores Prácticas recomendadas Cuotas y límites

Carcasas interactivas (terminales)

La InvokeAgentRuntimeCommandShell operación abre una sesión de terminal interactiva y persistente dentro de una sesión AgentCore de Runtime en 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 incluyen en 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 llamarInvokeAgentRuntimeCommandShell, necesita bedrock-agentcore:InvokeAgentRuntimeCommandShell permisos.

Funcionamiento

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

Mismo agente, misma sesión

InvokeAgentRuntimeCommandShellfunciona en el mismo tiempo de ejecución del agente que InvokeAgentRuntime yInvokeAgentRuntimeCommand. No se crean recursos separados. El agente con el que ha desplegado CreateAgentRuntime acepta conexiones de shell en cualquier sesión activa.

nota

Puede pasar una session_id para que se dirija a 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 tanto comosession_id. 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 incluyen las entradas de la misma sesión.
Reconexión	Proporcione lo mismo `session_id` y vuelva `shellId` a conectarlo a la misma carcasa después de una desconexión. El servicio reproduce hasta 256 KB de la salida almacenada en búfer.
Varios proyectiles simultáneos	Hasta 10 sesiones de shell activas (terminales) por tiempo de ejecución. Las conexiones nuevas se rechazan cuando están al límite de su capacidad.

Requisitos previos

Permiso de IAM bedrock-agentcore:InvokeAgentRuntimeCommandShell
Un ARN AgentCore de punto final de ejecución válido con un tiempo de ejecución en estado READY

nota

Los agentes creados después del 5 de junio de 2026 admiten automáticamente las consolas interactivas (terminales). Si desplegó su agente antes de esta fecha, debe volver a desplegarlo para actualizar el tiempo de ejecución del agente.

Uso de la AgentCore CLI

Para obtener instrucciones de instalación y configuración, consulte Comenzar a utilizar AgentCore Runtime mediante la CLI.

La CLI proporciona una experiencia de terminal integrada conagentcore exec.


agentcore exec --it

Para conectarse a un entorno de ejecución específico:


agentcore exec --it --runtime <runtime-arn> --region us-west-2

Pulse Ctrl+] para separarlo de una carcasa sin cerrarla. La CLI imprime un comando de reconexión:


agentcore exec --it \
  --runtime <arn> \
  --region <region> \
  --session-id <uuid> \
  --shell-id <id>

Para los comandos de un solo paso, omita: --it


agentcore exec "ls -la /tmp"

Para obtener una salida legible por máquina, utilice el modo JSON:


agentcore exec --json "echo hello"
# Output: {"success":true,"exitCode":0,"stdout":"hello\n","stderr":""}

Para ver ejemplos de CLI adicionales, consulte los AgentCore ejemplos en GitHub.

Uso del AgentCore SDK

Instale el SDK de Python:


pip install bedrock-agentcore

ejemplo

SigV4 (default)

El siguiente ejemplo muestra cómo abrir una sesión de shell con AWS las credenciales predeterminadas.


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

En el siguiente ejemplo, se muestra cómo abrir una sesión de shell mediante 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

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 consiste en volver a conectarse shellId 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 se interrumpe la WebSocket conexión. Úselo ReconnectConfig para habilitar esto:


import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel

async def on_reconnect(reconnected: bool):
    print(f"Reconnected: {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 los AgentCore ejemplos en GitHub.

Casos de uso comunes

Depuración interactiva

Abra un shell para inspeccionar el entorno de ejecución del agente: compruebe los paquetes instalados, lea los archivos de registro, examine el sistema de archivos o pruebe 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 a la hora de diagnosticar los fallos de los agentes o validar la configuración de despliegue.


env | grep AWS && curl -s http://169.254.169.254/latest/meta-data/

Codificar el acceso al terminal del agente

Los agentes de codificación de IA utilizan capas interactivas (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 Runtime y ejecuta los comandos directamente, del mismo modo que un desarrollador utilizaría un terminal. Por ejemplo, Claude Code, Amazon Kiro y OpenAI Codex se conectan a una sesión de shell en la que pueden escribir código, ejecutarlo, observar los resultados y corregir errores en un bucle 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 &

Principales opciones 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 comandos posteriores.
El encuadre binario ha terminado WebSocket: I/O La terminal se transmite como marcos binarios WebSocket . Esto admite secuencias de control de terminal sin procesar, colores, movimiento del cursor y aplicaciones de pantalla completa sin sobrecargar la codificación.
Reconexión con reproducción de salida: Al volver a conectarse utilizando la mismashellId, 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 tiempo de ejecución, se rechazan las nuevas conexiones con 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 en Runtime, consulte las prácticas recomendadas de seguridad para AgentCore Runtime.

importante

Según el modelo de responsabilidad AWS compartida, usted es responsable 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 de las sesiones de shell (terminales) 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. Las sesiones de shell 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 de shell 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 los metadatos de conexión al grupo de CloudWatch registros de Amazon Logs de tu agente. Puede usar estos registros para monitorear la actividad de conexión del shell y mantener un registro de auditoría. I/O El contenido de la terminal (stdin/stdout) se transmite a su cliente y el servicio no lo registra.

Auditoría con CloudTrail

AWS CloudTrail registra las llamadas a la InvokeAgentRuntimeCommandShell 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 abrió las sesiones de shell y cuándo, y luego se correlaciona con CloudWatch los registros mediante el ID de solicitud para obtener detalles de conexión.

Para las cargas de trabajo sensibles, considere la posibilidad de implementar controles adicionales, como:

Utilizar las políticas de IAM para restringir los directores que pueden llamar InvokeAgentRuntimeCommandShell
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 conexión inesperados
Revisar CloudTrail los registros con regularidad para detectar 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 la WebSocket actualización:

ValidationException: Se produce cuando los parámetros de la solicitud no son válidos. Esto puede suceder si el identificador de sesión tiene menos de 33 caracteres, la función no está habilitada en la región de destino o el agente no está en estado LISTO.
AccessDeniedException: Se produce cuando no se tienen los permisos necesarios. Asegúrese de que su política de IAM incluya el bedrock-agentcore:InvokeAgentRuntimeCommandShell permiso.
ResourceNotFoundException: Se produce cuando no se encuentra el tiempo de ejecución del agente especificado. Compruebe que el ARN del tiempo de ejecución es correcto.
RuntimeClientError (424): Se produce en varios escenarios: (1) Se alcanza el máximo de sesiones de shell simultáneas (terminales) (10 abiertas): cierre una sesión existente y vuelva a intentarlo. (2) El formato de 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: inténtelo de nuevo tras un retraso. Analice el error campo JSON del cuerpo de la respuesta para distinguir las causas.
ThrottlingException: Se produce cuando se supera el límite de velocidad de la API. Implemente la lógica de retroceso exponencial y reintento.
ConflictException: Otra conexión es afirmar lo mismo simultáneamente. shellId Vuelva a intentarlo después de 1 segundo. Se trata de una condición de carrera limitada (no de un estado persistente) y se resuelve inmediatamente al volver a intentarlo.

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

Código	Significado	Acción del cliente
`1000`	Cierre normal: la carcasa salió limpiamente o se desconectó elegantemente	Pantalla «desconectada». Terminación normal.
`1001`	Desaparecerá: el servidor se despliega o se cierra	Auto-reconnect con almacenado`shellId`.
`1003`	Datos no admitidos: se envían después de 5 marcos de texto consecutivos (protocolo solo binario)	NO vuelva a conectarse automáticamente. Cambie a marcos binarios.
`1006`	Cierre anormal: se sintetiza localmente cuando no se recibe ningún fotograma cercano (muerte de la red, TCP RST)	Auto-reconnect con almacenado`shellId`.
`1008`	Infracción de 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 se ha desbordado el búfer de escritura	Auto-reconnect por caducidad del TTL (TTL nuevo al volver a conectarse). Para el límite de velocidad: desconéctate y vuelve a conectarte.
`1009`	El mensaje es demasiado grande: la carga útil de fotogramas ha superado los 64 KB	Reduzca el tamaño del fotograma (el fragmento a <64 KB) y, a continuación, vuelva a conectarlo. La sesión sigue activa.
`1011`	Error del servidor: fallo interno inesperado	Vuelva a intentarlo con un retraso.
`4000`	Reemplazado: otro cliente conectado al mismo `shellId`	NO vuelva a conectarse automáticamente. Muestra «sesión conectada desde otro cliente».

Prácticas recomendadas

Siga estas prácticas recomendadas al usarInvokeAgentRuntimeCommandShell:

Utilice un único shellId (como un UUID) para cada sesión lógica a fin de permitir la reconexión. Guárdelo shellId en el lado del cliente.
Úselo 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 rápidamente. Si el cliente se retrasa, el búfer de escritura del servidor se llena y la conexión se cierra con el código1008.
En el caso de 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 esa hora.
Cierre las sesiones de forma explícita cuando haya terminado. Las sesiones independientes cuentan para el límite de 10 sesiones.

Cuotas y límites

Límite	Valor	Description (Descripción)
Tamaño máximo de carga útil del fotograma	64 KB	Los fotogramas que superen este límite producen un código `1009` cerrado.
Velocidad de fotogramas	250 frames/sec	Superar este valor activa el código de cierre`1008`.
Duración máxima de la conexión	1 hora	La conexión se cierra con un código`1008`. Vuelva a conectarse utilizando el mismo botón `shellId` para continuar.
Sesiones de shell simultáneas (terminales) por tiempo de ejecución	10	Se rechazan las nuevas conexiones si ya hay 10 sesiones abiertas. Cierre una sesión existente y vuelva a intentarlo.
Búfer de reconexión	256 KB	La salida máxima se reproduce al volver a conectarse a una carcasa.

Para conocer los límites de servicio completos, consulta Cuotas de Amazon Bedrock AgentCore.

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

Ejecuta comandos de shell

Observe a los agentes