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 name="harness-command-shell"></a>

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
<a name="harness-command-shell-how-it-works"></a>

 `InvokeAgentRuntimeCommandShell`estabelece 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
<a name="harness-command-shell-prerequisites"></a>
+ 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` e`dash`, não são suportados atualmente.

Para obter mais informações sobre o modelo completo de permissões de arnês, consulte[Permissões de IAM necessárias para chamadores](harness-security.md#harness-iam-permissions).

## Connect por meio da WebSocket API
<a name="harness-command-shell-connect"></a>

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
<a name="harness-command-shell-protocol"></a>

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
<a name="harness-command-shell-reconnect"></a>

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 fechamento`4000`.

## Casos de uso comuns
<a name="harness-command-shell-use-cases"></a>

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
<a name="harness-command-shell-security"></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, consulte[Segurança e controles de acesso](harness-security.md).

## Tratamento de erros
<a name="harness-command-shell-errors"></a>

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
<a name="harness-command-shell-best-practices"></a>
+ 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
<a name="harness-command-shell-limits"></a>


| 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](bedrock-agentcore-limits.md).

## Tópicos relacionados
<a name="_related_topics"></a>
+  [Ambiente e sistema de arquivos](harness-environment.md)- configure o ambiente padrão ou um contêiner personalizado
+  [Segurança e controles de acesso](harness-security.md)- controlar o acesso ao arnês e seu ambiente de execução
+  [Observabilidade e controles de custos](harness-operations.md)- monitorar a atividade e os custos do Harness
+  [Conchas interativas para AgentCore Runtime](runtime-get-started-command-shell.md)