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)

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 en un solo paso, 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 llamarInvokeAgentRuntimeCommandShell, necesita bedrock-agentcore:InvokeAgentRuntimeCommandShell permisos.

Funcionamiento

InvokeAgentRuntimeCommandShellestablece una WebSocket conexión con 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

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

La conexión admite:

Requisitos previos

Uso de la CLI AgentCore

Para obtener instrucciones de instalación y configuración, consulte Introducción a la AgentCore CLI.

La CLI proporciona una experiencia de terminal integrada conagentcore exec.

agentcore exec --it

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

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

Presiona Ctrl+] para separarte 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 uso, omita: --it

agentcore exec "ls -la /tmp"

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

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

Para ver más ejemplos de CLI, consulta los AgentCore ejemplos en. GitHub

Uso del AgentCore SDK

Instale el SDK de Python:

pip install bedrock-agentcore

Reconexión

Un patrón común es 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. ReconnectConfigUtilízalo 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, consulta los AgentCore ejemplos de GitHub.

Casos de uso comunes

Elecciones clave de diseño

Consideraciones de seguridad

El límite de seguridad para 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 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 registros CloudWatch

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

Auditoría con CloudTrail

AWS CloudTrail graba 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. CloudTrail Utilízalo para auditar quién abrió las sesiones de shell y cuándo y, a continuación, correlaciona con CloudWatch los registros utilizando el identificador de solicitud para obtener información sobre la conexión.

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

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:

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

Prácticas recomendadas

Siga estas prácticas recomendadas cuando utiliceInvokeAgentRuntimeCommandShell:

Cuotas y límites

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