Como funciona Pré-requisitos Connect por meio da WebSocket API Protocolo de quadro binário Reconecte-se a um shell Casos de uso comuns Considerações sobre segurança Tratamento de erros Práticas recomendadas Cotas e limites Tópicos relacionados

Conchas interativas (terminais)

A InvokeAgentRuntimeCommandShell operação abre um terminal persistente e interativo dentro de uma sessão de AgentCore arnês em WebSocket execução. A API identifica essa sessão de arnês com um ID de sessão em tempo de execução. Ao contrário da execução única de comandos, um shell interativo mantém suas variáveis de ambiente, diretório de trabalho, histórico de comandos e processos em execução nas entradas.

Use um shell interativo para depuração, desenvolvimento iterativo ou processos de longa execução quando precisar preservar o estado do shell em todos os comandos.

Para solicitações pré-assinadas SigV4 e SigV4, o chamador precisa de permissão no chicote. bedrock-agentcore:InvokeAgentRuntimeCommandShell Bearer-token Em vez disso, as solicitações devem satisfazer o autorizador de entrada do harness.

Importante

No lançamento, os comandos da AgentCore CLI e os auxiliares de shell do AgentCore SDK de alto nível não oferecem suporte a alvos de aproveitamento. Conecte-se diretamente a um shell de arnês por meio da InvokeAgentRuntimeCommandShell WebSocket API, conforme mostrado nesta página.

Como funciona

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

Se o chicote usar o ambiente padrão, o shell será executado no ambiente de chicote gerenciado. Se o chicote usar um contêiner personalizado, o shell será executado nesse contêiner. Atualmente, os terminais interativos Harness suportam apenas o Bash.

A conexão suporta:

Recurso	Description
Estado persistente	Variáveis de ambiente, diretório de trabalho, histórico de comandos e processos em execução persistem no mesmo shell.
Reconexão	Forneça o mesmo ID de sessão de tempo `shellId` de execução e reconecte-se a um shell separado. O serviço reproduz até 256 KB de saída em buffer.
Vários shells simultâneos	Abra até 10 sessões ativas de shell em uma sessão de arnês. Os projéteis isolados não contam para esse limite. Cada shell tem um processo de terminal independente e compartilha o sistema de arquivos da sessão.

Pré-requisitos

Um arnês no estado READY
Autorização para o método de autenticação selecionado: permissão bedrock-agentcore:InvokeAgentRuntimeCommandShell do IAM para SigV4 ou um token de portador aceito pelo autorizador de entrada do harness
Um WebSocket cliente que oferece suporte a quadros binários e cabeçalhos de solicitação ou URLs pré-assinados
Para um contêiner personalizado, o Bash foi instalado em/bin/bash. Outros shells, incluindo sh edash, não são suportados atualmente.

Para obter mais informações sobre o modelo completo de permissões de arnês, consultePermissões de IAM necessárias para chamadores.

Connect por meio da WebSocket API

Abra uma WebSocket conexão com o seguinte URL:


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

Use o ARN do chicote, não o ARN de seu tempo de execução gerenciado. URL-encode o ARN completo do arnês antes de colocá-lo no caminho. Um arnês ARN tem o seguinte formato:


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

Envie os seguintes valores com a solicitação de WebSocket upgrade:

Valor	Obrigatório	Description
Autenticação	Sim	Assine a solicitação com Signature Version 4 (SigV4), use uma URL pré-assinada SigV4 ou envie o token do portador configurado pelo autorizador de entrada do harness no cabeçalho. `Authorization` O nome do serviço SigV4 é. `bedrock-agentcore`
`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`cabeçalho ou parâmetro de consulta	Não	Tem como alvo uma sessão de arnês existente ou cria uma com o ID fornecido. O valor deve conter pelo menos 33 caracteres. Se você a omitir, o serviço criará uma ID de sessão de tempo de execução e a retornará na resposta.
`Sec-WebSocket-Protocol`	Não	Para conexões SigV4, opcionalmente, ofereça `v1.command.agentcore.aws.dev` a identificação do protocolo binário do shell de comando. Bearer-token Em vez disso, as conexões usam os subprotocolos de autenticação descritos após essa tabela.
`shellId`parâmetro de consulta	Não	Reconecta-se a um shell existente. Use-o com o mesmo ID de sessão de tempo de execução que criou o shell.

Para um cliente de navegador que não consegue definir um Authorization cabeçalho, codifique em base64url o token do portador e ofereça ambos e a sentinela. base64UrlBearerAuthorization.<encoded-token> base64UrlBearerAuthorization Sec-WebSocket-Protocol Também não ofereça v1.command.agentcore.aws.dev uma conexão entre o portador e o token.

A 101 Switching Protocols resposta retorna o ID da sessão de tempo de execução e o ID do shell nos X-Amzn-Bedrock-AgentCore-Shell-Id cabeçalhos X-Amzn-Bedrock-AgentCore-Runtime-Session-Id e. Clientes que não conseguem ler cabeçalhos de resposta de WebSocket atualização podem ler o ID do shell a partir do primeiro STATUS quadro. O quadro não contém o ID da sessão em tempo de execução, portanto, esses clientes devem gerar e reter um ID de sessão em tempo de execução antes de se conectarem. Ao criar um URL pré-assinado, inclua o ID da sessão de tempo de execução como um parâmetro de consulta antes de assinar o URL.

O tempo limite do WebSocket upgrade se aplica somente até o retorno 101 Switching Protocols do serviço. A inicialização do shell e do contêiner personalizado pode continuar após a atualização. Aguarde o STATUS quadro inicial antes de tratar o shell como pronto, aplique um tempo limite de aplicativo separado enquanto espera e trate o código de fechamento 1011 como uma inicialização do shell ou falha do servidor.

O exemplo de Python a seguir usa um WebSocket cliente genérico e botocore somente para assinar a solicitação de upgrade. Ele não usa um auxiliar de shell AgentCore do 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())

Protocolo de quadro binário

Cada mensagem no nível do aplicativo é um quadro binário. WebSocket O primeiro byte identifica o canal e os bytes restantes são a carga útil.

Canal	Direction	Carga útil
`0x00`- BARRA	Do cliente ao serviço	Entrada bruta do terminal.
`0x01`- ROBUSTO	Atendimento ao cliente	Saída bruta de PTY. O PTY combina o comando stdout e stderr nesse canal.
`0x02`- STERR	Atendimento ao cliente	Diagnóstico de serviços ou plataformas. O comando stderr faz parte da saída `0x01` PTY.
`0x03`- STATUS	Atendimento ao cliente	UTF-8 JSON contendo metadados de conexão ou o status de saída do shell.
`0x04`- REDIMENSIONAR	Do cliente ao serviço	UTF-8 JSON no formulário`{"width":120,"height":40}`. Cada dimensão deve ser de 1 a 1.000.
`0x05`- BATIMENTO CARDÍACO	Ambas as direções	Pulsação opcional do aplicativo. O serviço ecoa a carga útil. WebSocket quadros de ping também são suportados.
`0xFF`- FECHAR	Ambas as direções	Encerra a sessão do shell.

Os quadros de texto não fazem parte do protocolo. O serviço ignora quadros de texto isolados e fecha a conexão com o código 1003 após cinco quadros de texto consecutivos.

O primeiro STATUS quadro confirma a conexão e inclui metadados semelhantes aos seguintes:


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

Quando o shell sai com um status diferente de zero, o STATUS quadro final inclui uma ExitCode causa em. details.causes

Reconecte-se a um shell

Armazene o ID da sessão de tempo de execução e o ID do shell. Para se reconectar, use o mesmo cabeçalho de ID de sessão em tempo de execução e adicione o ID do URL-encoded shell como um parâmetro de consulta:


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

O processo do shell continua em execução enquanto a conexão é desconectada. Na reconexão, o serviço reproduz até 256 KB de saída armazenada em buffer. A STATUS estrutura de conexão é definida metadata.reconnected como true e inclui metadata.bytesDropped se o invólucro separado produziu mais saída do que o buffer de repetição poderia reter.

Abrir outra conexão com o mesmo ID de shell substitui a conexão existente. O cliente substituído recebe o código de fechamento4000.

Casos de uso comuns

Depuração interativa: Inspecione pacotes, arquivos, processos e configurações do ambiente instalados no mesmo ambiente do agente de arnês.
Validação de ambiente personalizado: Para um equipamento com um contêiner personalizado, verifique as dependências instaladas e as montagens do sistema de arquivos de dentro desse contêiner.
Acesso ao terminal do agente de codificação: Forneça um ambiente de execução persistente para agentes de codificação que precisam criar arquivos, executar testes, inspecionar a saída e iterar.
Long-running processos: Inicie um processo, desconecte-se do WebSocket e reconecte-se mais tarde para verificar o progresso ou fornecer informações.

Considerações sobre segurança

Importante

Um diretor que pode abrir um shell de arnês tem acesso de comando interativo à sessão de arnês. Restrinja bedrock-agentcore:InvokeAgentRuntimeCommandShell a diretores confiáveis e ARNs de arnês específicos.

O shell pode acessar dados, arquivos e segredos fornecidos pelo cliente no ambiente selecionado ou em sistemas de arquivos montados. Ele também pode se conectar a destinos de rede que a sessão pode alcançar. O ambiente shell usa uma lista de permissões e não injeta credenciais de AgentCore plataforma ou carga de trabalho. O shell permanece dentro da microVM isolada da sessão e não pode acessar a carga de trabalho de outro cliente.

AgentCore envia o ID da solicitação e os metadados da conexão para o grupo de logs Harness Runtime no Amazon CloudWatch Logs. O serviço não registra a entrada ou a saída do terminal.

AWS CloudTrail registra chamadas de InvokeAgentRuntimeCommandShell API, incluindo a identidade do chamador, o carimbo de data/hora, o endereço IP de origem, o recurso de tempo de execução resolvido e o status da resposta. CloudTrail não registra a entrada ou saída do terminal.

Para obter mais orientações sobre segurança do Harness, consulteSegurança e controles de acesso.

Tratamento de erros

A WebSocket atualização pode retornar os seguintes erros:

ValidationException: Os parâmetros da solicitação são inválidos. Verifique se o ID da sessão de tempo de execução contém pelo menos 33 caracteres, se o ID do shell é válido e se o recurso está disponível na região de destino. Use o ARN do URL-encoded harness no caminho da solicitação; o uso direto do ARN de tempo de execução gerenciado é rejeitado.
AccessDeniedException: O chamador não tem bedrock-agentcore:InvokeAgentRuntimeCommandShell permissão para usar o cinto.
ResourceNotFoundException: O arnês especificado não existe. Verifique se o URL contém o URL-encoded ARN do chicote.
ServiceQuotaExceededException (429): O máximo de 10 projéteis ativos já está aberto. Encerre um shell ativo ou desconecte-o e tente novamente.
RuntimeClientError (424): O tempo de execução não pôde ser alcançado.
ThrottlingException: A solicitação excedeu o limite de taxa da API. Novas tentativas com recuo exponencial.
RetryableConflictException (409): O serviço está provisionando ou destruindo a sessão de destino. Tente novamente com um pequeno recuo exponencial.

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

Código	Significado	Ação do cliente
`1000`	O projétil saiu limpo.	Trate como terminação normal.
`1003`	O cliente enviou cinco quadros de texto consecutivos para o protocolo somente binário.	Mude para quadros binários. Não se reconecte automaticamente com o mesmo comportamento.
`1006`	A conexão terminou sem um quadro fechado devido a uma falha na rede ou interrupção do serviço.	Reconecte-se com o ID do shell armazenado.
`1008`	A duração da conexão de uma hora expirou, a taxa de quadros excedeu 250 quadros por segundo ou o buffer de gravação transbordou.	Reconecte-se para que a duração expire. Para violações de taxa ou buffer, recue antes de se reconectar.
`1009`	A carga útil do quadro excedeu 64 KB.	Divida a carga em quadros menores que 64 KB e reconecte.
`1011`	Ocorreu uma falha inesperada no servidor.	Novas tentativas com recuo exponencial.
`4000`	Outro cliente conectado com o mesmo ID de shell.	Não se reconecte automaticamente. Informe ao usuário que outro cliente está conectado ao shell.

Práticas recomendadas

Gere e retenha um ID de shell exclusivo para cada terminal lógico.
Mantenha o ID da sessão de tempo de execução com o ID do shell. Ambos os valores são necessários para a reconexão.
Leia a saída imediatamente para que o buffer de gravação da conexão não seja preenchido.
Divida a entrada grande em quadros binários menores que 64 KB.
Reconecte-se antes ou depois do limite de conexão de uma hora se o shell precisar permanecer disponível por mais tempo.
Encerre as conchas explicitamente quando elas não forem mais necessárias. Projéteis separados não contam para o limite de 10 projéteis ativos. O serviço retém no máximo 20 entradas ativas e separadas do shell e despeja o shell separado mais antigo quando necessário.
Use um tempo limite de atualização de pelo menos 330 segundos quando uma conexão puder iniciar uma sessão de cold harness. Aplique um tempo limite separado enquanto aguarda o STATUS quadro inicial após a atualização.

Cotas e limites

Limite	Valor	Description
Carga útil máxima do quadro	64 KB	Quadros maiores resultam em código fechado`1009`.
Taxa de quadros	250 quadros por segundo	Exceder o limite resulta em código `1008` fechado.
Duração máxima da conexão	1 hora	Reconecte-se com o mesmo ID de sessão de tempo de execução e ID de shell para continuar.
Projéteis ativos simultâneos por sessão de arnês	10	Novas conexões são rejeitadas quando 10 projéteis estão ativos. Os projéteis isolados não contam para esse limite.
Entradas de shell ativas e desconectadas mantidas	20	Quando o limite é atingido, o serviço despeja o shell separado mais antigo antes de criar outro shell.
Tampão de reconexão	256 KB	Saída máxima reproduzida após a reconexão.

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

Tópicos relacionados

Ambiente e sistema de arquivos- configure o ambiente padrão ou um contêiner personalizado
Segurança e controles de acesso- controlar o acesso ao arnês e seu ambiente de execução
Observabilidade e controles de custos- monitorar a atividade e os custos do Harness
Conchas interativas para AgentCore Runtime

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Ambiente e sistema de arquivos

Observabilidade e controles de custos