Strumento bash

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 concatenamento di comandi e scripting

Versioni dello strumento

Modello	Versione Strumento
Modelli Claude 4 e Sonnet 3.7	`bash_20250124`
Claude Sonnet 3.5 (deprecato)	`bash_20241022`

Claude Sonnet 3.5 (deprecato) richiede l’header beta computer-use-2024-10-22 quando si utilizza lo strumento bash.Lo strumento bash è generalmente disponibile nei modelli 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:

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

Parametri

Parametro	Richiesto	Descrizione
`command`	Sì*	Il comando bash da eseguire
`restart`	No	Imposta su `true` per riavviare la sessione bash

*Richiesto a meno che non si utilizzi restart

Esempio di utilizzo

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 passo 2 sono disponibili nel passo 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.

Configurare 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()

Gestire 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

Elaborare 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
        }

Implementare 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:

Timeout esecuzione comando

Se un comando impiega troppo tempo per essere eseguito:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Errore: Comando scaduto dopo 30 secondi",
      "is_error": true
    }
  ]
}

Comando non trovato

Se un comando non esiste:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: nonexistentcommand: comando non trovato",
      "is_error": true
    }
  ]
}

Permesso negato

Se ci sono problemi di permessi:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: /root/sensitive-file: Permesso negato",
      "is_error": true
    }
  ]
}

Seguire le migliori pratiche di implementazione

Utilizzare timeout per i comandi

Implementa timeout per prevenire comandi che si bloccano:

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 scaduto dopo {timeout} secondi"

Mantenere lo stato della sessione

Mantieni la sessione bash persistente per conservare variabili d’ambiente e directory di lavoro:

# I comandi eseguiti nella stessa sessione mantengono lo stato
commands = [
    "cd /tmp",
    "echo 'Ciao' > test.txt",
    "cat test.txt"  # Questo funziona perché siamo ancora in /tmp
]

Gestire output di grandi dimensioni

Tronca output molto grandi per prevenire problemi di limite di token:

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... Output troncato ({len(lines)} righe totali) ..."
    return output

Registrare tutti i comandi

Mantieni una traccia di audit dei comandi eseguiti:

import logging

def log_command(command, output, user_id):
    logging.info(f"Utente {user_id} ha eseguito: {command}")
    logging.info(f"Output: {output[:200]}...")  # Registra i primi 200 caratteri

Sanificare gli output

Rimuovi informazioni sensibili dagli output dei comandi:

def sanitize_output(output):
    # Rimuovi potenziali segreti o credenziali
    import re
    # Esempio: Rimuovi credenziali 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

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 liste di comandi consentiti
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.

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

Panoramica

Versioni dello strumento

Casi d’uso

Avvio rapido

Come funziona

Parametri

Esempio: Automazione multi-step

Implementare lo strumento bash

Gestire gli errori

Seguire le migliori pratiche di implementazione

Sicurezza

Raccomandazioni chiave

Prezzi

Pattern comuni

Flussi di lavoro di sviluppo

Operazioni sui file

Attività di sistema

Limitazioni

Combinazione con altri strumenti

Prossimi passi

Panoramica uso strumenti

Strumento editor di testo

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

​Panoramica

​Versioni dello strumento

​Casi d’uso

​Avvio rapido

​Come funziona

​Parametri

​Esempio: Automazione multi-step

​Implementare lo strumento bash

​Gestire gli errori

​Seguire le migliori pratiche di implementazione

​Sicurezza

​Raccomandazioni chiave

​Prezzi

​Pattern comuni

​Flussi di lavoro di sviluppo

​Operazioni sui file

​Attività di sistema

​Limitazioni

​Combinazione con altri strumenti

​Prossimi passi

Panoramica uso strumenti

Strumento editor di testo

Panoramica

Versioni dello strumento

Casi d’uso

Avvio rapido

Come funziona

Parametri

Esempio: Automazione multi-step

Implementare lo strumento bash

Gestire gli errori

Seguire le migliori pratiche di implementazione

Sicurezza

Raccomandazioni chiave

Prezzi

Pattern comuni

Flussi di lavoro di sviluppo

Operazioni sui file

Attività di sistema

Limitazioni

Combinazione con altri strumenti

Prossimi passi