As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Conchas interativas (terminais)

A InvokeAgentRuntimeCommandShell operação abre uma sessão de terminal persistente e interativa dentro de uma sessão AgentCore de tempo de execução WebSocket. Diferentemente da execução única de comandos, as sessões do shell mantêm o estado — as variáveis de ambiente, o diretório de trabalho e o histórico de comandos são transmitidos pelas entradas. Isso permite depuração, inspeção ambiental e 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 Começar a usar a AgentCore CLI.

A CLI fornece uma experiência de terminal integrada comagentcore 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 desprender 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 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 cair. 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 outros exemplos 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, em sua VM, os comandos shell têm acesso total ao sistema de arquivos do contêiner e a quaisquer credenciais ou segredos que você tenha configurado.

Auditoria com registros CloudWatch

AgentCore O Runtime envia o ID da solicitação e os metadados de 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, data e hora, endereço IP de origem e status da resposta. CloudTrail não registra a carga útil da solicitação ou da resposta. Use CloudTrail para auditar quem abriu as sessões do shell e quando e, em seguida, correlacione-o 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:

Uma vez conectado, os seguintes códigos de fechamento indicam por que uma 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.