Ferramenta bash

A ferramenta bash permite que Claude execute comandos shell em uma sessão bash persistente, permitindo operações do sistema, execução de scripts e automação de linha de comando.

A ferramenta bash permite que Claude execute comandos shell em uma sessão bash persistente, permitindo operações do sistema, execução de scripts e automação de linha de comando.

Visão geral

A ferramenta bash fornece ao Claude:

• Sessão bash persistente que mantém o estado
• Capacidade de executar qualquer comando shell
• Acesso a variáveis de ambiente e diretório de trabalho
• Capacidades de encadeamento de comandos e scripts

Versões da ferramenta

Modelo	Versão da Ferramenta
Modelos Claude 4 e Sonnet 3.7	bash_20250124
Claude Sonnet 3.5 (descontinuado)	bash_20241022

Claude Sonnet 3.5 (descontinuado) requer o cabeçalho beta computer-use-2024-10-22 ao usar a ferramenta bash.

A ferramenta bash está geralmente disponível nos modelos Claude 4 e Sonnet 3.7.

Casos de uso

• Fluxos de trabalho de desenvolvimento: Executar comandos de build, testes e ferramentas de desenvolvimento
• Automação do sistema: Executar scripts, gerenciar arquivos, automatizar tarefas
• Processamento de dados: Processar arquivos, executar scripts de análise, gerenciar conjuntos de dados
• Configuração de ambiente: Instalar pacotes, configurar ambientes

Início rápido

Python

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "bash_20250124",
            "name": "bash"
        }
    ],
    messages=[
        {"role": "user", "content": "Liste todos os arquivos Python no diretório atual."}
    ]
)

Como funciona

A ferramenta bash mantém uma sessão persistente:

1. Claude determina qual comando executar
2. Você executa o comando em um shell bash
3. Retorna a saída (stdout e stderr) para Claude
4. O estado da sessão persiste entre comandos (variáveis de ambiente, diretório de trabalho)

Parâmetros

Parâmetro	Obrigatório	Descrição
command	Sim*	O comando bash a ser executado
restart	Não	Defina como true para reiniciar a sessão bash

*Obrigatório a menos que usando restart

Exemplo de uso

// Executar um comando
{
  "command": "ls -la *.py"
}

// Reiniciar a sessão
{
  "restart": true
}

Exemplo: Automação multi-etapas

Claude pode encadear comandos para completar tarefas complexas:

# Solicitação do usuário
"Instale a biblioteca requests e crie um script Python simples que busque uma piada de uma API, depois execute-o."

# Usos da ferramenta do Claude:
# 1. Instalar pacote
{"command": "pip install requests"}

# 2. Criar script
{"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

# 3. Executar script
{"command": "python fetch_joke.py"}

A sessão mantém o estado entre comandos, então os arquivos criados na etapa 2 estão disponíveis na etapa 3.

---

Implementar a ferramenta bash

A ferramenta bash é implementada como uma ferramenta sem esquema. Ao usar esta ferramenta, você não precisa fornecer um esquema de entrada como com outras ferramentas; o esquema está integrado no modelo do Claude e não pode ser modificado.

1. Configurar um ambiente bash

   Crie uma sessão bash persistente com a qual Claude possa interagir:

   import subprocess
   import threading
   import queue
   
   class BashSession:
       def __init__(self):
           self.process = subprocess.Popen(
               ['/bin/bash'],
               stdin=subprocess.PIPE,
               stdout=subprocess.PIPE,
               stderr=subprocess.PIPE,
               text=True,
               bufsize=0
           )
           self.output_queue = queue.Queue()
           self.error_queue = queue.Queue()
           self._start_readers()
   

2. Lidar com execução de comandos

   Crie uma função para executar comandos e capturar saída:

   def execute_command(self, command):
       # Enviar comando para bash
       self.process.stdin.write(command + '\n')
       self.process.stdin.flush()
       
       # Capturar saída com timeout
       output = self._read_output(timeout=10)
       return output
   

3. Processar chamadas de ferramenta do Claude

   Extrair e executar comandos das respostas do Claude:

   for content in response.content:
       if content.type == "tool_use" and content.name == "bash":
           if content.input.get("restart"):
               bash_session.restart()
               result = "Sessão bash reiniciada"
           else:
               command = content.input.get("command")
               result = bash_session.execute_command(command)
           
           # Retornar resultado para Claude
           tool_result = {
               "type": "tool_result",
               "tool_use_id": content.id,
               "content": result
           }
   

4. Implementar medidas de segurança

   Adicionar validação e restrições:

   def validate_command(command):
       # Bloquear comandos perigosos
       dangerous_patterns = ['rm -rf /', 'format', ':(){:|:&};:']
       for pattern in dangerous_patterns:
           if pattern in command:
               return False, f"Comando contém padrão perigoso: {pattern}"
       
       # Adicionar mais validação conforme necessário
       return True, None
   

Lidar com erros

Ao implementar a ferramenta bash, lide com vários cenários de erro:

Timeout de execução de comando

Se um comando demorar muito para executar:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Comando expirou após 30 segundos",
      "is_error": true
    }
  ]
}

Comando não encontrado

Se um comando não existir:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: comandoinexistente: comando não encontrado",
      "is_error": true
    }
  ]
}

Permissão negada

Se houver problemas de permissão:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: /root/arquivo-sensivel: Permissão negada",
      "is_error": true
    }
  ]
}

Seguir melhores práticas de implementação

Usar timeouts de comando

Implementar timeouts para prevenir comandos travados:

def execute_with_timeout(command, timeout=30):
    try:
        result = subprocess.run(
            command, 
            shell=True, 
            capture_output=True, 
            text=True, 
            timeout=timeout
        )
        return result.stdout + result.stderr
    except subprocess.TimeoutExpired:
        return f"Comando expirou após {timeout} segundos"

Manter estado da sessão

Manter a sessão bash persistente para manter variáveis de ambiente e diretório de trabalho:

# Comandos executados na mesma sessão mantêm o estado
commands = [
    "cd /tmp",
    "echo 'Olá' > teste.txt",
    "cat teste.txt"  # Isso funciona porque ainda estamos em /tmp
]

Lidar com saídas grandes

Truncar saídas muito grandes para prevenir problemas de limite de tokens:

def truncate_output(output, max_lines=100):
    lines = output.split('\n')
    if len(lines) > max_lines:
        truncated = '\n'.join(lines[:max_lines])
        return f"{truncated}\n\n... Saída truncada ({len(lines)} linhas totais) ..."
    return output

Registrar todos os comandos

Manter uma trilha de auditoria dos comandos executados:

import logging

def log_command(command, output, user_id):
    logging.info(f"Usuário {user_id} executou: {command}")
    logging.info(f"Saída: {output[:200]}...")  # Registrar primeiros 200 caracteres

Sanitizar saídas

Remover informações sensíveis das saídas de comando:

def sanitize_output(output):
    # Remover possíveis segredos ou credenciais
    import re
    # Exemplo: Remover credenciais AWS
    output = re.sub(r'aws_access_key_id\s*=\s*\S+', 'aws_access_key_id=***', output)
    output = re.sub(r'aws_secret_access_key\s*=\s*\S+', 'aws_secret_access_key=***', output)
    return output

Segurança

A ferramenta bash fornece acesso direto ao sistema. Implemente estas medidas de segurança essenciais:

• Executar em ambientes isolados (Docker/VM)
• Implementar filtragem de comandos e listas de permissão
• Definir limites de recursos (CPU, memória, disco)
• Registrar todos os comandos executados

Recomendações principais

• Use ulimit para definir restrições de recursos
• Filtre comandos perigosos (sudo, rm -rf, etc.)
• Execute com permissões mínimas de usuário
• Monitore e registre toda execução de comando

Preços

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

• Command outputs (stdout/stderr)
• Error messages
• Large file contents

Veja preços de uso de ferramentas para detalhes completos de preços.

Padrões comuns

Fluxos de trabalho de desenvolvimento

• Executar testes: pytest && coverage report
• Construir projetos: npm install && npm run build
• Operações Git: git status && git add . && git commit -m "mensagem"

Operações de arquivo

• Processar dados: wc -l *.csv && ls -lh *.csv
• Buscar arquivos: find . -name "*.py" | xargs grep "padrão"
• Criar backups: tar -czf backup.tar.gz ./dados

Tarefas do sistema

• Verificar recursos: df -h && free -m
• Gerenciamento de processos: ps aux | grep python
• Configuração de ambiente: export PATH=$PATH:/novo/caminho && echo $PATH

Limitações

• Sem comandos interativos: Não pode lidar com vim, less, ou prompts de senha
• Sem aplicações GUI: Apenas linha de comando
• Escopo da sessão: Persiste dentro da conversa, perdido entre chamadas da API
• Limites de saída: Saídas grandes podem ser truncadas
• Sem streaming: Resultados retornados após conclusão

Combinando com outras ferramentas

A ferramenta bash é mais poderosa quando combinada com o editor de texto e outras ferramentas.

Próximos passos

Visão geral de uso de ferramentas

Aprenda sobre uso de ferramentas com Claude

Ferramenta de editor de texto

Visualize e edite arquivos de texto com Claude