Conchas interativas (terminais)

A InvokeAgentRuntimeCommandShell operação abre uma sessão de terminal persistente e interativa dentro de uma sessão de Runtime em AgentCore execução WebSocket. Ao contrário da execução única de comandos, as sessões de shell mantêm o estado — as variáveis de ambiente, o diretório de trabalho e o histórico de comandos são transmitidos entre as entradas. Isso permite a depuração, a inspeção do ambiente e a criação de experiências de terminal em seu aplicativo.

Para ligarInvokeAgentRuntimeCommandShell, você precisa de bedrock-agentcore:InvokeAgentRuntimeCommandShell permissões.

Como funciona

InvokeAgentRuntimeCommandShellestabelece uma WebSocket conexão com um processo de shell interativo em execução na sessão do seu agente. A conexão usa quadros binários para transmitir a entrada e a saída do terminal em ambas as direções.

Mesmo agente, mesma sessão

InvokeAgentRuntimeCommandShellopera no mesmo tempo de execução do agente que InvokeAgentRuntime InvokeAgentRuntimeCommand e. Você não cria recursos separados. O agente com o qual você implantou CreateAgentRuntime aceita conexões shell em qualquer sessão ativa.

A conexão suporta:

Pré-requisitos

Usando a AgentCore CLI

Para obter instruções de instalação e configuração, consulte Comece a usar o AgentCore Runtime usando a CLI.

A CLI fornece uma experiência de terminal integrada com. agentcore exec

agentcore exec --it

Para se conectar a um tempo de execução específico:

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

Pressione Ctrl+] para se soltar de uma concha sem fechá-la. A CLI imprime um comando de reconexão:

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

Para comandos únicos, --it omita:

agentcore exec "ls -la /tmp"

Para uma saída legível por máquina, use o modo JSON:

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

Para obter exemplos adicionais de CLI, consulte AgentCore exemplos em. GitHub

Usando o AgentCore SDK

Instale o SDK do Python:

pip install bedrock-agentcore

Reconexão

Um padrão comum é usar para se shellId reconectar a um shell após uma desconexão, preservando todo o estado da sessão.

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

O SDK também pode se reconectar automaticamente quando a WebSocket conexão é interrompida. Use ReconnectConfig para habilitar isso:

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 exemplos adicionais de SDK, veja AgentCore exemplos em. GitHub

Casos de uso comuns

Principais opções de design

Considerações sobre segurança

O limite de segurança para sessões de shell (terminais) é a microVM. Cada sessão do AgentCore Runtime é executada em uma microVM isolada com seu próprio kernel, memória e sistema de arquivos. As sessões do Shell não podem acessar as cargas de trabalho de outros clientes nem escapar dos limites da VM. No entanto, na sua VM, os comandos shell têm acesso total ao sistema de arquivos do contêiner e a todas as credenciais ou segredos que você configurou.

Auditoria com registros CloudWatch

AgentCore O Runtime envia o ID da solicitação e os metadados da conexão para o grupo de CloudWatch logs do Amazon Logs do seu agente. Você pode usar esses registros para monitorar a atividade de conexão do shell e manter uma trilha de auditoria. I/O O conteúdo do terminal (stdin/stdout) é transmitido para seu cliente e não é registrado pelo serviço.

Auditoria com CloudTrail

AWS CloudTrail registra chamadas de InvokeAgentRuntimeCommandShell API em sua conta. Cada registro inclui metadados, como identidade do chamador, carimbo de data/hora, endereço IP de origem e status da resposta. CloudTrail não registra a carga útil da solicitação ou resposta. Use CloudTrail para auditar quem abriu as sessões de shell e quando, depois correlacione com CloudWatch os registros usando o ID da solicitação para obter detalhes da conexão.

Para cargas de trabalho confidenciais, considere a implementação de controles adicionais, como:

Tratamento de erros

Ao estabelecer uma conexão de sessão de shell, você pode encontrar os seguintes erros durante a WebSocket atualização:

Depois de conectado, os seguintes códigos de fechamento indicam por que a conexão foi encerrada:

Práticas recomendadas

Siga estas melhores práticas ao usarInvokeAgentRuntimeCommandShell:

Cotas e limites

Para ver os limites completos do serviço, consulte Cotas para o Amazon Bedrock AgentCore.