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 un terminal persistente e interactivo dentro de una sesión de AgentCore arnés en ejecución WebSocket. La API identifica esta sesión de arnés con un identificador de sesión en tiempo de ejecución. A diferencia de la ejecución de comandos de una sola vez, un shell interactivo mantiene sus variables de entorno, su directorio de trabajo, su historial de comandos y los procesos en ejecución en todas las entradas.
Utilice un shell interactivo para la depuración, el desarrollo iterativo o los procesos de larga ejecución cuando necesite conservar el estado del shell en todos los comandos.
En el caso de las solicitudes prefirmadas de SigV4 y SigV4, la persona que llama necesita un permiso para utilizar el arnés. bedrock-agentcore:InvokeAgentRuntimeCommandShell Bearer-token En su lugar, las solicitudes deben cumplir con el autorizador de entrada del arnés.
importante
En el momento del lanzamiento, los comandos de AgentCore CLI y los ayudantes de shell del AgentCore SDK de alto nivel no admiten los objetivos de arnés. Conéctese directamente a una carcasa de arnés a través de la InvokeAgentRuntimeCommandShell WebSocket API, como se muestra en esta página.
Funcionamiento
InvokeAgentRuntimeCommandShellestablece una WebSocket conexión a un proceso de shell interactivo en la microVM que ejecuta la sesión de arnés. La conexión utiliza marcos binarios para transmitir la entrada y la salida del terminal en ambas direcciones.
Si el arnés utiliza el entorno predeterminado, la carcasa se ejecuta en el entorno de arnés gestionado. Si el arnés utiliza un contenedor personalizado, la carcasa se coloca en ese contenedor. Los terminales interactivos Harness actualmente solo son compatibles con Bash.
La conexión admite:
| Característica | Description (Descripción) |
|---|---|
|
Estado persistente |
Las variables de entorno, el directorio de trabajo, el historial de comandos y los procesos en ejecución persisten en el mismo shell. |
|
Reconexión |
Proporcione el mismo ID de sesión en tiempo de ejecución y vuelva |
|
Múltiples proyectiles simultáneos |
Abre hasta 10 sesiones de concha activas en una sesión de arnés. Los casquillos desprendidos no se tienen en cuenta para este límite. Cada shell tiene un proceso terminal independiente y comparte el sistema de archivos de la sesión. |
Requisitos previos
-
Un arnés en estado
READY -
Autorización para el método de autenticación seleccionado: permiso de
bedrock-agentcore:InvokeAgentRuntimeCommandShellIAM para SigV4 o un token portador aceptado por el autorizador de entrada del arnés -
Un WebSocket cliente que admite marcos binarios y solicita encabezados o URL prefirmadas
-
Para un contenedor personalizado, Bash se instala en.
/bin/bashActualmente, no se admiten otrosshproyectilesdash, incluidos los de tipo y.
Para obtener más información sobre el modelo completo de permisos de arnés, consultePermisos de IAM necesarios para las personas que llaman.
Conéctate a través de la WebSocket API
Abre una WebSocket conexión a la siguiente URL:
wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells
Utilice el ARN del arnés, no el ARN de su tiempo de ejecución gestionado. URL-encode el ARN completo del arnés antes de colocarlo en el camino. El ARN de un arnés tiene el siguiente formato:
arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<harnessId>
Envíe los siguientes valores con la solicitud de WebSocket actualización:
| Valor | Obligatorio | Description (Descripción) |
|---|---|---|
|
Autenticación |
Sí |
Firme la solicitud con la versión 4 de Signature (SiGv4), utilice una URL prefirmada de SiGv4 o envíe el token de soporte configurado por el autorizador entrante del arnés en el encabezado. |
|
|
No |
Se dirige a una sesión de arnés existente o crea una con el ID proporcionado. El valor debe contener al menos 33 caracteres. Si lo omite, el servicio crea un identificador de sesión en tiempo de ejecución y lo devuelve en la respuesta. |
|
|
No |
Para las conexiones SigV4, si lo desea, ofrezca |
|
|
No |
Se vuelve a conectar a un shell existente. Úselo con el mismo ID de sesión de tiempo de ejecución que creó el shell. |
En el caso de un cliente de navegador que no pueda configurar un Authorization encabezado, codifique en base64url-url el token portador y utilice tanto el código Sentinel. base64UrlBearerAuthorization.<encoded-token> base64UrlBearerAuthorization Sec-WebSocket-Protocol No lo ofrezcas también en una conexión portador-token. v1.command.agentcore.aws.dev
La 101 Switching Protocols respuesta devuelve el ID de la sesión en tiempo de ejecución y el ID del shell en los encabezados X-Amzn-Bedrock-AgentCore-Runtime-Session-Id yX-Amzn-Bedrock-AgentCore-Shell-Id. Los clientes que no puedan leer los encabezados de las respuestas de WebSocket actualización pueden leer el ID del shell desde el primer STATUS fotograma. El marco no contiene el ID de sesión en tiempo de ejecución, por lo que estos clientes deben generar y conservar un ID de sesión en tiempo de ejecución antes de conectarse. Al crear una URL prefirmada, incluye el ID de la sesión en tiempo de ejecución como parámetro de consulta antes de firmar la URL.
El tiempo de espera de la WebSocket actualización solo se aplica hasta que se restablezca el servicio. 101 Switching Protocols La inicialización del shell y del contenedor personalizado puede continuar después de la actualización. Espere al STATUS fotograma inicial antes de considerar que el shell está listo, aplique un tiempo de espera diferente a la aplicación mientras espera y gestione el código de cierre 1011 como si se inicializara el shell o se produjera un fallo en el servidor.
El siguiente ejemplo de Python usa un WebSocket cliente genérico y botocore solo para firmar la solicitud de actualización. No usa un asistente de shell AgentCore del SDK.
pip install "boto3>=1.34" "websockets>=15"
import asyncio import json import urllib.parse import uuid import botocore.session import websockets from botocore.auth import SigV4Auth from botocore.awsrequest import AWSRequest REGION = "us-west-2" HARNESS_ARN = ( "arn:aws:bedrock-agentcore:us-west-2:123456789012:" "harness/MyHarness-a1b2c3d4e5" ) SESSION_ID = str(uuid.uuid4()) # 36 characters SUBPROTOCOL = "v1.command.agentcore.aws.dev" def signed_headers(url): request = AWSRequest( method="GET", url=url, headers={ "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": SESSION_ID, }, ) credentials = botocore.session.Session().get_credentials() SigV4Auth(credentials, "bedrock-agentcore", REGION).add_auth(request) return dict(request.headers) async def main(): encoded_arn = urllib.parse.quote(HARNESS_ARN, safe="") host = f"bedrock-agentcore.{REGION}.amazonaws.com" path = f"/runtimes/{encoded_arn}/ws/shells" https_url = f"https://{host}{path}" websocket_url = f"wss://{host}{path}" async with websockets.connect( websocket_url, additional_headers=signed_headers(https_url), subprotocols=[SUBPROTOCOL], open_timeout=330, ) as websocket: shell_id = websocket.response.headers.get( "X-Amzn-Bedrock-AgentCore-Shell-Id" ) print(f"Connected to shell {shell_id}") # Channel 0x00 carries terminal input. await websocket.send(b"\x00echo 'Hello from my harness'\n") await websocket.send(b"\x00exit\n") async for frame in websocket: if isinstance(frame, str) or not frame: continue channel, payload = frame[0], frame[1:] if channel == 0x01: # PTY output (command stdout and stderr) print(payload.decode("utf-8", errors="replace"), end="") elif channel == 0x02: # Service or platform diagnostics print(payload.decode("utf-8", errors="replace"), end="") elif channel == 0x03: # STATUS status = json.loads(payload) shell_id = status.get("metadata", {}).get("shellId", shell_id) print(f"\nStatus: {status}") asyncio.run(main())
Protocolo de marco binario
Cada mensaje a nivel de aplicación es un marco binario WebSocket . El primer byte identifica el canal y los bytes restantes son la carga útil.
| Canal | Dirección | Carga útil |
|---|---|---|
|
|
De cliente a servicio |
Entrada de terminal sin procesar. |
|
|
Servicio al cliente |
Salida PTY sin procesar. El PTY combina los comandos stdout y stderr en este canal. |
|
|
Servicio al cliente |
Diagnósticos de servicios o plataformas. El comando stderr forma parte de la salida de |
|
|
Servicio al cliente |
UTF-8 JSON que contiene los metadatos de la conexión o el estado de salida del shell. |
|
|
De cliente a servicio |
UTF-8 JSON en el formulario |
|
|
En ambas direcciones |
Aplicación opcional Heartbeat. El servicio reproduce la carga útil. WebSocket También se admiten tramas de ping. |
|
|
En ambas direcciones |
Finaliza la sesión provisional. |
Los marcos de texto no forman parte del protocolo. El servicio ignora los marcos de texto aislados y cierra la conexión con código 1003 después de cinco marcos de texto consecutivos.
El primer STATUS marco confirma la conexión e incluye metadatos similares a los siguientes:
{ "kind": "Status", "apiVersion": "v1", "metadata": { "shellId": "my-shell", "reconnected": false }, "status": "Success" }
Cuando el shell sale con un estado distinto de cero, el STATUS fotograma final incluye una entrada de ExitCode causa. details.causes
Vuelva a conectarse a un shell
Guarde tanto el ID de la sesión en tiempo de ejecución como el ID del shell. Para volver a conectarse, utilice el mismo encabezado de ID de sesión en tiempo de ejecución y añada el ID de URL-encoded shell como parámetro de consulta:
wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells?shellId=<shell-id>
El proceso de shell continúa ejecutándose mientras la conexión está desconectada. Al volver a conectarse, el servicio reproduce hasta 256 KB de salida almacenada en búfer. El STATUS marco de conexión se establece metadata.reconnected true e incluye metadata.bytesDropped si la carcasa separada produjo más salida de la que el búfer de reproducción podría retener.
Al abrir otra conexión con el mismo ID de terminal, se reemplaza la conexión existente. El cliente sustituido recibe el código de cierre4000.
Casos de uso comunes
- Depuración interactiva
-
Inspeccione los paquetes, archivos, procesos y configuración del entorno instalados en el mismo entorno que el agente de arnés.
- Validación del entorno personalizada
-
En el caso de un arnés con un contenedor personalizado, compruebe las dependencias instaladas y los montajes del sistema de archivos desde el interior de ese contenedor.
- Acceso al terminal del agente de codificación
-
Proporcione un entorno de ejecución persistente para los agentes de codificación que necesitan crear archivos, ejecutar pruebas, inspeccionar los resultados e iterar.
- Long-running procesos
-
Inicie un proceso, desconéctelo y vuelva a conectarlo más tarde para comprobar el progreso o proporcionar información. WebSocket
Consideraciones de seguridad
importante
Un director que pueda abrir una carcasa de arnés tiene acceso interactivo mediante comandos a la sesión del arnés. bedrock-agentcore:InvokeAgentRuntimeCommandShellLimítelo a directores de confianza y ARN de arnés específicos.
El shell puede acceder a los datos, archivos y secretos proporcionados por el cliente en el entorno seleccionado o en sistemas de archivos montados. También se puede conectar a los destinos de red a los que puede llegar la sesión. El entorno shell usa una lista de permisos y no inyecta credenciales de AgentCore plataforma o carga de trabajo. El shell permanece dentro de la microVM aislada de la sesión y no puede acceder a la carga de trabajo de otro cliente.
AgentCore envía el ID de solicitud y los metadatos de conexión al grupo de registros Harness Runtime en Amazon CloudWatch Logs. El servicio no registra las entradas ni las salidas del terminal.
AWS CloudTrail registra las llamadas a la InvokeAgentRuntimeCommandShell API, incluida la identidad de la persona que llama, la marca de tiempo, la dirección IP de origen, el recurso de tiempo de ejecución resuelto y el estado de la respuesta. CloudTrail no registra la entrada ni la salida del terminal.
Para obtener más información sobre la guía de seguridad de Harness, consulteSeguridad y controles de acceso.
Gestión de errores
La WebSocket actualización puede devolver los siguientes errores:
- ValidationException
-
Los parámetros de la solicitud no son válidos. Compruebe que el identificador de la sesión en tiempo de ejecución contenga al menos 33 caracteres, que el identificador del shell sea válido y que la función esté disponible en la región de destino. Utilice el ARN de URL-encoded arnés en la ruta de solicitud; se rechaza el uso directo del ARN de tiempo de ejecución administrado.
- AccessDeniedException
-
La persona que llama no tiene
bedrock-agentcore:InvokeAgentRuntimeCommandShellpermiso para usar el arnés. - ResourceNotFoundException
-
El arnés especificado no existe. Compruebe que la URL contiene el ARN del URL-encoded arnés.
- ServiceQuotaExceededException (429)
-
Ya hay abierto un máximo de 10 proyectiles activos. Finaliza un proyectil activo o sepáralo e inténtalo de nuevo.
- RuntimeClientError (424)
-
No se pudo alcanzar el tiempo de ejecución.
- ThrottlingException
-
La solicitud superó el límite de velocidad de la API. Vuelva a intentarlo con retroceso exponencial.
- RetryableConflictException (409)
-
El servicio aprovisiona o desactiva la sesión de destino. Vuelva a intentarlo con un breve retraso exponencial.
Una vez conectada, los siguientes códigos de cierre indican el motivo de la finalización de la conexión:
| Código | Significado | Acción del cliente |
|---|---|---|
|
|
El proyectil salió limpiamente. |
Trátela como una terminación normal. |
|
|
El cliente envió cinco marcos de texto consecutivos al protocolo solo binario. |
Cambie a marcos binarios. No vuelvas a conectarte automáticamente con el mismo comportamiento. |
|
|
La conexión finalizó sin un marco cerrado debido a un fallo de la red o a una interrupción del servicio. |
Vuelva a conectarse con el identificador de shell almacenado. |
|
|
La duración de la conexión de una hora expiró, la velocidad de fotogramas superó los 250 fotogramas por segundo o el búfer de escritura se desbordó. |
Vuelva a conectarse cuando haya expirado el tiempo. En caso de que se produzcan infracciones de velocidad o búfer, apáguese antes de volver a conectarse. |
|
|
La carga útil de un fotograma supera los 64 KB. |
Divida la carga útil en fotogramas de menos de 64 KB y, a continuación, vuelva a conectarla. |
|
|
Se ha producido un error inesperado en el servidor. |
Vuelva a intentarlo con retroceso exponencial. |
|
|
Otro cliente conectado con el mismo identificador de shell. |
No vuelvas a conectarte automáticamente. Informe al usuario de que hay otro cliente conectado al shell. |
Prácticas recomendadas
-
Genere y conserve un identificador de shell único para cada terminal lógico.
-
Conserve el ID de la sesión en tiempo de ejecución junto con el ID del shell. Ambos valores son necesarios para la reconexión.
-
Lea la salida rápidamente para que el búfer de escritura de la conexión no se llene.
-
Divida la entrada grande en marcos binarios de menos de 64 KB.
-
Vuelva a conectarse antes o después del límite de conexión de una hora si la carcasa debe permanecer disponible durante más tiempo.
-
Finalice las cáscaras de forma explícita cuando ya no las necesite. Los proyectiles desprendidos no cuentan para el límite de 10 proyectiles activos. El servicio retiene como máximo 20 entradas de proyectiles activos e independientes y desaloja los proyectiles desprendidos más antiguos cuando es necesario.
-
Utilice un tiempo de espera de actualización de al menos 330 segundos cuando una conexión pueda iniciar una sesión de conexión en frío. Aplica un tiempo de espera diferente mientras esperas al
STATUSfotograma inicial tras la actualización.
Cuotas y límites
| Límite | Valor | Description (Descripción) |
|---|---|---|
|
Carga máxima de fotogramas |
64 KB |
Los fotogramas más grandes dan como resultado un código |
|
Velocidad de fotogramas |
250 fotogramas por segundo |
Si se supera el límite, se cierra el código |
|
Duración máxima de la conexión |
1 hora |
Vuelva a conectarse con el mismo ID de sesión en tiempo de ejecución y el mismo ID de shell para continuar. |
|
Carcasas activas simultáneas por sesión de arnés |
10 |
Las conexiones nuevas se rechazan cuando hay 10 carcasas activas. Los proyectiles desprendidos no cuentan para este límite. |
|
Se conservan las entradas de los proyectiles activas y separadas |
20 |
Cuando se alcanza el límite, el servicio desaloja la carcasa desprendida más antigua antes de crear otra. |
|
Búfer de reconexión |
256 KB |
La salida máxima se reproduce tras la reconexión. |
Para conocer los límites de servicio completos, consulta Cuotas de Amazon Bedrock AgentCore.
Temas relacionados
-
Entorno y sistema de archivos- configure el entorno predeterminado o un contenedor personalizado
-
Seguridad y controles de acceso- controlar el acceso al arnés y su entorno de ejecución
-
Controles de observabilidad y costos- monitorizar la actividad y los costes del arnés
