Come funziona Prerequisiti Connect tramite l' WebSocket API Protocollo Binary Frame Riconnettiti a una shell Casi di utilizzo comune Considerazioni relative alla sicurezza Gestione degli errori Best practice Quote e limiti Argomenti correlati

Conchiglie interattive (terminali)

L'InvokeAgentRuntimeCommandShelloperazione apre un terminale persistente e interattivo all'interno di una sessione di AgentCore cablaggio in esecuzione. WebSocket L'API identifica questa sessione di harness con un ID di sessione di runtime. A differenza dell'esecuzione di comandi in un colpo solo, una shell interattiva mantiene le variabili di ambiente, la directory di lavoro, la cronologia dei comandi e i processi in esecuzione tra gli input.

Usa una shell interattiva per il debug, lo sviluppo iterativo o i processi a esecuzione prolungata quando devi preservare lo stato della shell tra i comandi.

Per le richieste prefirmate SigV4 e SigV4, il chiamante necessita dell'autorizzazione sul cablaggio. bedrock-agentcore:InvokeAgentRuntimeCommandShell Bearer-token le richieste devono invece soddisfare l'autorizzazione in ingresso dell'harness.

Importante

Al momento del lancio, i comandi AgentCore CLI e gli helper della shell AgentCore SDK di alto livello non supportano gli obiettivi di cablaggio. Connect a una shell harness direttamente tramite l'InvokeAgentRuntimeCommandShell WebSocket API, come mostrato in questa pagina.

Come funziona

InvokeAgentRuntimeCommandShellstabilisce una WebSocket connessione a un processo shell interattivo nella microVM che esegue la sessione di harness. La connessione utilizza frame binari per trasmettere l'input e l'output del terminale in entrambe le direzioni.

Se il cablaggio utilizza l'ambiente predefinito, la shell viene eseguita nell'ambiente di cablaggio gestito. Se l'harness utilizza un contenitore personalizzato, la shell viene eseguita in quel contenitore. I terminali interattivi Harness attualmente supportano solo Bash.

La connessione supporta:

Funzionalità	Description
Stato persistente	Le variabili di ambiente, la directory di lavoro, la cronologia dei comandi e i processi in esecuzione persistono all'interno della stessa shell.
Riconnessione	Fornisci lo stesso ID di sessione di runtime e `shellId` riconnetterti a una shell separata. Il servizio riproduce fino a 256 KB di output bufferizzato.
Più shell simultanee	Apri fino a 10 sessioni di shell attive in una sessione di harness. Le conchiglie separate non contano ai fini di questo limite. Ogni shell ha un processo terminale indipendente e condivide il filesystem di sessione.

Prerequisiti

Un'imbracatura in stato READY
Autorizzazione per il metodo di autenticazione selezionato: autorizzazione bedrock-agentcore:InvokeAgentRuntimeCommandShell IAM per SigV4 o token bearer accettato dall'autorizzatore in entrata dell'harness
Un WebSocket client che supporta frame binari e che richiede intestazioni o URL prefirmati
Per un contenitore personalizzato, Bash è installato su. /bin/bash Altre shell, tra cui sh edash, non sono attualmente supportate.

Per ulteriori informazioni sul modello completo di autorizzazioni di cablaggio, vedere. Autorizzazioni IAM richieste per i chiamanti

Connect tramite l' WebSocket API

Apri una WebSocket connessione al seguente URL:


wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells

Utilizzate l'ARN del cablaggio, non l'ARN del relativo Runtime gestito. URL-encode l'imbracatura completa ARN prima di metterla sul percorso. Un'imbracatura ARN ha il seguente formato:


arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<harnessId>

Inviate i seguenti valori con la richiesta di WebSocket aggiornamento:

Valore	Richiesto	Description
Autenticazione	Sì	Firma la richiesta con Signature Version 4 (SigV4), usa un URL SigV4 prefirmato o invia il token bearer configurato dall'Harness Inbound Authorizer nell'intestazione. `Authorization` Il nome del servizio SigV4 è. `bedrock-agentcore`
`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`parametro di intestazione o di interrogazione	No	Si rivolge a una sessione di cablaggio esistente o ne crea una con l'ID fornito. Il valore deve contenere almeno 33 caratteri. Se lo ometti, il servizio crea un ID di sessione di runtime e lo restituisce nella risposta.
`Sec-WebSocket-Protocol`	No	Per le connessioni SigV4, offri opzionalmente di identificare il protocollo binario della `v1.command.agentcore.aws.dev` shell di comando. Bearer-token le connessioni utilizzano invece i sottoprotocolli di autenticazione descritti dopo questa tabella.
`shellId`parametro di interrogazione	No	Si riconnette a una shell esistente. Usalo con lo stesso ID di sessione di runtime che ha creato la shell.

Per un browser client che non è in grado di impostare un'Authorizationintestazione, base64url codifica il token bearer e offri l'accesso a entrambi e alla sentinel. base64UrlBearerAuthorization.<encoded-token> base64UrlBearerAuthorization Sec-WebSocket-Protocol Non offrite v1.command.agentcore.aws.dev l'offerta anche su una connessione bearer-token.

La 101 Switching Protocols risposta restituisce l'ID della sessione di runtime e l'ID della shell nelle intestazioni X-Amzn-Bedrock-AgentCore-Runtime-Session-Id andX-Amzn-Bedrock-AgentCore-Shell-Id. I client che non sono in grado di leggere le intestazioni di risposta all' WebSocket aggiornamento possono leggere l'ID della shell dal primo STATUS frame. Il frame non contiene l'ID della sessione di runtime, quindi questi client devono generare e conservare un ID di sessione di runtime prima di connettersi. Quando crei un URL prefirmato, includi l'ID della sessione di runtime come parametro di query prima di firmare l'URL.

Il timeout di WebSocket aggiornamento si applica solo fino al ripristino del servizio. 101 Switching Protocols L'inizializzazione della shell e del contenitore personalizzato può continuare dopo l'aggiornamento. Attendi il STATUS frame iniziale prima di considerare la shell pronta, applica un timeout separato per l'applicazione durante l'attesa e gestisci il codice di chiusura 1011 come un'inizializzazione della shell o un errore del server.

Il seguente esempio di Python utilizza un WebSocket client generico e botocore solo per firmare la richiesta di aggiornamento. Non utilizza un helper della shell AgentCore 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())

Protocollo Binary Frame

Ogni messaggio a livello di applicazione è un frame binario. WebSocket Il primo byte identifica il canale e i byte rimanenti sono il payload.

Canale	Direzione	Carico utile
`0x00`- STDIN	Dal cliente al servizio	Ingresso terminale non elaborato.
`0x01`- STDOUT	Servizio al cliente	Uscita PTY non elaborata. Il PTY combina i comandi stdout e stderr su questo canale.
`0x02`- STDERR	Servizio al cliente	Diagnostica del servizio o della piattaforma. Il comando stderr fa parte dell'output PTY. `0x01`
`0x03`- STATO	Servizio al cliente	UTF-8 JSON contenente i metadati di connessione o lo stato di uscita della shell.
`0x04`- RIDIMENSIONA	Dal cliente al servizio	UTF-8 JSON nel modulo`{"width":120,"height":40}`. Ogni dimensione deve essere compresa tra 1 e 1.000.
`0x05`- BATTITO CARDIACO	Entrambe le direzioni	Heartbeat dell'applicazione opzionale. Il servizio riproduce il payload. WebSocket Sono supportati anche i frame ping.
`0xFF`- CHIUDI	Entrambe le direzioni	Termina la sessione di shell.

Le cornici di testo non fanno parte del protocollo. Il servizio ignora le cornici di testo isolate e chiude la connessione con il codice 1003 dopo cinque cornici di testo consecutive.

Il primo STATUS frame conferma la connessione e include metadati simili ai seguenti:


{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    "shellId": "my-shell",
    "reconnected": false
  },
  "status": "Success"
}

Quando la shell esce con uno stato diverso da zero, il STATUS frame finale include una ExitCode causa. details.causes

Riconnettiti a una shell

Memorizza sia l'ID della sessione di runtime che l'ID della shell. Per riconnetterti, usa la stessa intestazione dell'ID della sessione di runtime e aggiungi l'ID della URL-encoded shell come parametro di query:


wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells?shellId=<shell-id>

Il processo della shell continua a funzionare mentre la connessione viene scollegata. Alla riconnessione, il servizio riproduce fino a 256 KB di output bufferizzato. Il STATUS frame di connessione imposta metadata.reconnected true e include metadata.bytesDropped se la shell scollegata ha prodotto più output di quanto il buffer di replay possa trattenere.

L'apertura di un'altra connessione con lo stesso ID di shell sostituisce la connessione esistente. Il client sostituito riceve il codice di chiusura. 4000

Casi di utilizzo comune

Debug interattivo: Ispeziona i pacchetti, i file, i processi e la configurazione dell'ambiente installati nello stesso ambiente dell'harness agent.
Convalida dell'ambiente personalizzata: Per un cablaggio con un contenitore personalizzato, verificate le dipendenze installate e i supporti dei file system dall'interno del contenitore.
Accesso al terminale dell'agente di codifica: Fornisci un ambiente di esecuzione persistente per gli agenti di codifica che devono creare file, eseguire test, ispezionare l'output e iterare.
Long-running processi: Avvia un processo, scollegalo e riconnettiti in un secondo momento per verificare lo stato di avanzamento o fornire input. WebSocket

Considerazioni relative alla sicurezza

Importante

Un principale in grado di aprire una shell Harness ha accesso interattivo ai comandi alla sessione di harness. Limita bedrock-agentcore:InvokeAgentRuntimeCommandShell ai principali affidabili e agli ARN di cablaggio specifici.

La shell può accedere a dati, file e segreti forniti dal cliente nell'ambiente selezionato o su file system montati. Può anche connettersi a destinazioni di rete raggiungibili dalla sessione. L'ambiente shell utilizza una lista di autorizzazioni e non inserisce credenziali di AgentCore piattaforma o carico di lavoro. La shell rimane all'interno della microVM isolata della sessione e non può accedere al carico di lavoro di un altro cliente.

AgentCore invia l'ID della richiesta e i metadati di connessione al gruppo di log Harness Runtime in Amazon CloudWatch Logs. Il servizio non registra l'input o l'output del terminale.

AWS CloudTrail registra le chiamate InvokeAgentRuntimeCommandShell API, tra cui l'identità del chiamante, il timestamp, l'indirizzo IP di origine, la risorsa Runtime risolta e lo stato della risposta. CloudTrail non registra l'input o l'output del terminale.

Per ulteriori indicazioni sulla sicurezza di Harness, vedereSicurezza e controlli degli accessi.

Gestione degli errori

L' WebSocket aggiornamento può restituire i seguenti errori:

ValidationException: I parametri della richiesta non sono validi. Verifica che l'ID della sessione di runtime contenga almeno 33 caratteri, che l'ID shell sia valido e che la funzionalità sia disponibile nella regione di destinazione. Utilizzate l'arn del URL-encoded cablaggio nel percorso della richiesta; l'uso diretto del Runtime ARN gestito viene rifiutato.
AccessDeniedException: Il chiamante non dispone dell'bedrock-agentcore:InvokeAgentRuntimeCommandShellautorizzazione sul cablaggio.
ResourceNotFoundException: Il cablaggio specificato non esiste. Verifica che l'URL contenga l' URL-encoded ARN del cablaggio.
ServiceQuotaExceededException (429): Il massimo di 10 proiettili attivi è già aperto. Termina una shell attiva o scollegala, quindi riprova.
RuntimeClientError (424): Il tempo di esecuzione non è stato raggiunto.
ThrottlingException: La richiesta ha superato il limite di velocità dell'API. Riprova con backoff esponenziale.
RetryableConflictException (409): Il servizio sta effettuando il provisioning o la chiusura della sessione di destinazione. Riprova con un breve backoff esponenziale.

Una volta effettuata la connessione, i seguenti codici di chiusura indicano il motivo per cui la connessione è terminata:

Codice	Significato	Azione del client
`1000`	Il guscio è uscito pulito.	Considera come una terminazione normale.
`1003`	Il client ha inviato cinque cornici di testo consecutive al protocollo binario.	Passa ai frame binari. Non riconnetterti automaticamente con lo stesso comportamento.
`1006`	La connessione è terminata senza un frame chiuso a causa di un errore di rete o di un'interruzione del servizio.	Riconnettiti con l'ID della shell memorizzato.
`1008`	La durata della connessione di un'ora è scaduta, la frequenza dei fotogrammi ha superato i 250 fotogrammi al secondo o il buffer di scrittura è sovraccarico.	Riconnettiti per la scadenza della durata. In caso di violazione della velocità o del buffer, disconnettiti prima di riconnetterti.
`1009`	Il payload di un frame ha superato i 64 KB.	Dividi il payload in frame di dimensioni inferiori a 64 KB, quindi riconnettiti.
`1011`	Si è verificato un errore imprevisto del server.	Riprova con backoff esponenziale.
`4000`	Un altro client connesso con lo stesso ID di shell.	Non riconnettersi automaticamente. Informa l'utente che un altro client è collegato alla shell.

Best practice

Genera e conserva un ID shell univoco per ogni terminale logico.
Conserva l'ID della sessione di runtime con l'ID della shell. Entrambi i valori sono necessari per la riconnessione.
Leggi subito l'output in modo che il buffer di scrittura della connessione non si riempia.
Suddividi l'input di grandi dimensioni in frame binari di dimensioni inferiori a 64 KB.
Riconnettiti prima o dopo il limite di un'ora di connessione se la shell deve rimanere disponibile più a lungo.
Termina le shell in modo esplicito quando non sono più necessarie. Le shell separate non vengono conteggiate ai fini del limite di 10 gusci attivi. Il servizio mantiene al massimo 20 input di shell attivi e scollegati ed elimina la shell separata più vecchia quando necessario.
Utilizzate un timeout di aggiornamento di almeno 330 secondi quando una connessione può avviare una sessione di cold harness. Applica un timeout separato in attesa del STATUS frame iniziale dopo l'aggiornamento.

Quote e limiti

Limite	Valore	Description
Carico utile massimo del frame	64 KB	I frame più grandi generano un codice chiuso. `1009`
Frequenza fotogrammi	250 fotogrammi al secondo	Il superamento del limite comporta la chiusura del codice. `1008`
Durata massima di una connessione	1 ora	Riconnettiti con lo stesso ID di sessione di runtime e lo stesso ID shell per continuare.
Shell attivi simultanei per sessione di cablaggio	10	Le nuove connessioni vengono rifiutate quando sono attive 10 shell. Le conchiglie separate non contano ai fini di questo limite.
Le entrate dei proiettili attive e staccate sono state mantenute	20	Quando viene raggiunto il limite, il servizio elimina la shell separata più vecchia prima di crearne un'altra.
Buffer di riconnessione	256 KB	Uscita massima riprodotta dopo la riconnessione.

Per i limiti completi del servizio, consulta Quotas for Amazon AgentCore Bedrock.

Argomenti correlati

Ambiente e file system- configura l'ambiente predefinito o un contenitore personalizzato
Sicurezza e controlli degli accessi- controllare l'accesso al cablaggio e al relativo ambiente di esecuzione
Osservabilità e controllo dei costi- monitora l'attività e i costi di Harness
Shell interattive per Runtime AgentCore

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Ambiente e file system

Osservabilità e controllo dei costi