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 dei comandi in un colpo solo, 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 le autorizzazioni. bedrock-agentcore:InvokeAgentRuntimeCommandShell

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 distribuito CreateAgentRuntime accetta connessioni shell in qualsiasi sessione attiva.

La connessione supporta:

Prerequisiti

Utilizzo della AgentCore CLI

Per istruzioni di installazione e configurazione, consulta Introduzione a AgentCore Runtime using the 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+]Premete per staccarvi 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 AgentCore gli esempi su. GitHub

Utilizzo dell'SDK AgentCore

Installa l'SDK Python:

pip install bedrock-agentcore

Riconnessione

Uno schema comune è quello di 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 per ReconnectConfig abilitare questa operazione:

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 filesystem propri. Le sessioni di shell non possono accedere ai carichi di lavoro degli altri clienti o sfuggire ai limiti delle macchine virtuali. Tuttavia, all'interno della macchina virtuale, i comandi della shell hanno pieno accesso al filesystem del contenitore e a tutte le credenziali o i segreti configurati.

Controllo con log CloudWatch

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

Controllo 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 correlato ai CloudWatch registri utilizzando l'ID della richiesta per i dettagli di connessione.

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

Gestione degli errori

Quando si stabilisce una connessione alla sessione di 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 completi del servizio, consulta Quotas for Amazon AgentCore Bedrock.