Lo strumento bash consente a Claude di eseguire comandi shell in una sessione bash persistente, permettendo operazioni di sistema, esecuzione di script e automazione da riga di comando.

Panoramica

Lo strumento bash fornisce a Claude:

  • Sessione bash persistente che mantiene lo stato
  • Capacità di eseguire qualsiasi comando shell
  • Accesso alle variabili d’ambiente e alla directory di lavoro
  • Capacità di concatenazione di comandi e scripting

Versioni dello strumento

ModelloVersione Strumento
Claude 4 & Sonnet 3.7bash_20250124
Claude Sonnet 3.5bash_20241022

Claude Sonnet 3.5 richiede l’header beta computer-use-2024-10-22 quando si utilizza lo strumento bash.

Lo strumento bash è generalmente disponibile in Claude 4 e Sonnet 3.7.

Casi d’uso

  • Flussi di lavoro di sviluppo: Eseguire comandi di build, test e strumenti di sviluppo
  • Automazione di sistema: Eseguire script, gestire file, automatizzare attività
  • Elaborazione dati: Elaborare file, eseguire script di analisi, gestire dataset
  • Configurazione ambiente: Installare pacchetti, configurare ambienti

Avvio rapido

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": "Elenca tutti i file Python nella directory corrente."}
    ]
)

Come funziona

Lo strumento bash mantiene una sessione persistente:

  1. Claude determina quale comando eseguire
  2. Esegui il comando in una shell bash
  3. Restituisci l’output (stdout e stderr) a Claude
  4. Lo stato della sessione persiste tra i comandi (variabili d’ambiente, directory di lavoro)

Parametri

ParametroRichiestoDescrizione
commandSì*Il comando bash da eseguire
restartNoImposta su true per riavviare la sessione bash

*Richiesto a meno che non si utilizzi restart

Esempio: Automazione multi-step

Claude può concatenare comandi per completare attività complesse:

# Richiesta dell'utente
"Installa la libreria requests e crea un semplice script Python che recupera una barzelletta da un'API, poi eseguilo."

# Utilizzi dello strumento di Claude:
# 1. Installa pacchetto
{"command": "pip install requests"}

# 2. Crea 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. Esegui script
{"command": "python fetch_joke.py"}

La sessione mantiene lo stato tra i comandi, quindi i file creati nel passaggio 2 sono disponibili nel passaggio 3.


Implementare lo strumento bash

Lo strumento bash è implementato come strumento senza schema. Quando si utilizza questo strumento, non è necessario fornire uno schema di input come con altri strumenti; lo schema è integrato nel modello di Claude e non può essere modificato.

1

Configura un ambiente bash

Crea una sessione bash persistente con cui Claude può interagire:

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

Gestisci l'esecuzione dei comandi

Crea una funzione per eseguire comandi e catturare l’output:

def execute_command(self, command):
    # Invia comando a bash
    self.process.stdin.write(command + '\n')
    self.process.stdin.flush()
    
    # Cattura output con timeout
    output = self._read_output(timeout=10)
    return output
3

Elabora le chiamate agli strumenti di Claude

Estrai ed esegui comandi dalle risposte di Claude:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Sessione bash riavviata"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)
        
        # Restituisci risultato a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }
4

Implementa misure di sicurezza

Aggiungi validazione e restrizioni:

def validate_command(command):
    # Blocca comandi pericolosi
    dangerous_patterns = ['rm -rf /', 'format', ':(){:|:&};:']
    for pattern in dangerous_patterns:
        if pattern in command:
            return False, f"Il comando contiene un pattern pericoloso: {pattern}"
    
    # Aggiungi più validazione secondo necessità
    return True, None

Gestire gli errori

Quando si implementa lo strumento bash, gestisci vari scenari di errore:

Segui le migliori pratiche di implementazione

Sicurezza

Lo strumento bash fornisce accesso diretto al sistema. Implementa queste misure di sicurezza essenziali:

  • Esecuzione in ambienti isolati (Docker/VM)
  • Implementazione di filtri per comandi e allowlist
  • Impostazione di limiti di risorse (CPU, memoria, disco)
  • Registrazione di tutti i comandi eseguiti

Raccomandazioni chiave

  • Usa ulimit per impostare vincoli di risorse
  • Filtra comandi pericolosi (sudo, rm -rf, ecc.)
  • Esegui con permessi utente minimi
  • Monitora e registra tutta l’esecuzione dei comandi

Prezzi

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

Vedi prezzi uso strumenti per dettagli completi sui prezzi.

Pattern comuni

Flussi di lavoro di sviluppo

  • Esecuzione test: pytest && coverage report
  • Build progetti: npm install && npm run build
  • Operazioni Git: git status && git add . && git commit -m "messaggio"

Operazioni sui file

  • Elaborazione dati: wc -l *.csv && ls -lh *.csv
  • Ricerca file: find . -name "*.py" | xargs grep "pattern"
  • Creazione backup: tar -czf backup.tar.gz ./data

Attività di sistema

  • Controllo risorse: df -h && free -m
  • Gestione processi: ps aux | grep python
  • Configurazione ambiente: export PATH=$PATH:/new/path && echo $PATH

Limitazioni

  • Nessun comando interattivo: Non può gestire vim, less, o prompt di password
  • Nessuna applicazione GUI: Solo riga di comando
  • Ambito sessione: Persiste all’interno della conversazione, perso tra chiamate API
  • Limiti output: Output grandi potrebbero essere troncati
  • Nessuno streaming: Risultati restituiti dopo il completamento

Combinazione con altri strumenti

Lo strumento bash è più potente quando combinato con l’editor di testo e altri strumenti.

Prossimi passi