Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Conchiglie interattive (terminali)

L'InvokeAgentRuntimeCommandShelloperazione apre una sessione terminale persistente e interattiva all'interno di una sessione di AgentCore Runtime in esecuzione. WebSocket A differenza dell'esecuzione immediata dei comandi, le sessioni di shell mantengono lo stato: le variabili di ambiente, la directory di lavoro e la cronologia dei comandi vengono trasferite tra gli input. Ciò consente il debug, l'ispezione dell'ambiente e la creazione di esperienze terminali nell'applicazione.

Per chiamareInvokeAgentRuntimeCommandShell, sono necessarie bedrock-agentcore:InvokeAgentRuntimeCommandShell le autorizzazioni.

Come funziona

InvokeAgentRuntimeCommandShellstabilisce una WebSocket connessione a un processo shell interattivo in esecuzione all'interno della sessione dell'agente. La connessione utilizza frame binari per trasmettere l'input e l'output del terminale in entrambe le direzioni.

Stesso agente, stessa sessione

InvokeAgentRuntimeCommandShellopera sullo stesso runtime dell'agente di InvokeAgentRuntime eInvokeAgentRuntimeCommand. Non si creano risorse separate. L'agente con cui hai eseguito la distribuzione CreateAgentRuntime accetta connessioni shell in qualsiasi sessione attiva.

La connessione supporta:

Prerequisiti

Utilizzo della CLI AgentCore

Per le istruzioni di installazione e configurazione, consulta Get started with the AgentCore CLI.

La CLI offre un'esperienza terminale integrata con. agentcore exec

agentcore exec --it

Per connettersi a un runtime specifico:

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

Ctrl+]Premi per staccarti da un guscio senza chiuderlo. La CLI stampa un comando di riconnessione:

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

Per i comandi one-shot, ometti: --it

agentcore exec "ls -la /tmp"

Per un output leggibile dalla macchina, usa la modalità JSON:

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

Per ulteriori esempi di CLI, consulta gli esempi su. AgentCore GitHub

Utilizzo dell'SDK AgentCore

Installa l'SDK Python:

pip install bedrock-agentcore

Riconnessione

Un modello comune viene utilizzato per riconnettersi shellId a una shell dopo una disconnessione, preservando tutto lo stato della sessione.

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

L'SDK può anche riconnettersi automaticamente quando la connessione si interrompe. WebSocket Usa ReconnectConfig per abilitare questo:

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())

Per ulteriori esempi di SDK, consulta gli AgentCore esempi su GitHub.

Casi di utilizzo comune

Scelte di progettazione chiave

Considerazioni relative alla sicurezza

Il limite di sicurezza per le sessioni di shell (terminali) è la MicroVM. Ogni sessione AgentCore di Runtime viene eseguita in una MicroVM isolata con kernel, memoria e file system propri. Le sessioni Shell non possono accedere ai carichi di lavoro di altri clienti o sfuggire ai confini della VM. Tuttavia, all'interno della tua VM, i comandi della shell hanno pieno accesso al filesystem del contenitore e a tutte le credenziali o i segreti che hai configurato.

Controllo con i log CloudWatch

AgentCore Runtime invia l'ID della richiesta e i metadati di connessione al gruppo di CloudWatch log Amazon Logs del tuo agente. Puoi utilizzare questi log per monitorare l'attività di connessione alla shell e mantenere un audit trail. Il I/O contenuto del terminale (stdin/stdout) viene trasmesso in streaming al client e non viene registrato dal servizio.

Revisione con CloudTrail

AWS CloudTrail registra le chiamate InvokeAgentRuntimeCommandShell API nel tuo account. Ogni record include metadati come l'identità del chiamante, il timestamp, l'indirizzo IP di origine e lo stato della risposta. CloudTrail non registra il payload della richiesta o della risposta. Viene utilizzato CloudTrail per verificare chi ha aperto le sessioni di shell e quando, quindi esegue la correlazione con CloudWatch i log utilizzando l'ID della richiesta per i dettagli della connessione.

Per carichi di lavoro sensibili, prendi in considerazione l'implementazione di controlli aggiuntivi come:

Gestione degli errori

Quando si stabilisce una connessione con una sessione shell, è possibile che si verifichino i seguenti errori durante l' WebSocket aggiornamento:

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

Best practice

Segui queste best practice quando usiInvokeAgentRuntimeCommandShell:

Quote e limiti

Per i limiti di servizio completi, consulta Quote per Amazon Bedrock. AgentCore