Claude Platform Docs
MessaggiStrumenti

Strumento Bash

Consenti a Claude di richiedere comandi shell che la tua applicazione esegue in una sessione bash persistente e restituisce come risultati dello strumento.

Lo strumento bash è un client tool (strumento client): Claude non esegue i comandi da sé. Quando includi lo strumento in una richiesta, Claude risponde con un blocco tool_use che indica il comando da eseguire. La tua applicazione esegue quel comando in una sessione bash di sua proprietà e restituisce l’output in un blocco tool_result.

La tua applicazione mantiene attivo un unico processo bash tra le chiamate allo strumento, quindi lo stato persiste tra un comando e l’altro. La directory di lavoro, le variabili d’ambiente e qualsiasi file creato da un comando sono ancora presenti per il comando successivo.

La versione attuale dello strumento è bash_20250124. Per il supporto dei modelli, i beta header e la versione precedente, consulta Versioni dello strumento. Per tutti gli strumenti forniti da Anthropic, consulta il Riferimento degli strumenti.

Casi d’uso

  • Flussi di lavoro di sviluppo: Esegui comandi di build, test e strumenti di sviluppo
  • Automazione di sistema: Esegui script, gestisci file, automatizza attività
  • Elaborazione dei dati: Elabora file, esegui script di analisi, gestisci dataset
  • Configurazione dell’ambiente: Installa pacchetti, configura ambienti

Avvio rapido

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Claude risponde con stop_reason: "tool_use" e un blocco tool_use che contiene il comando che la tua applicazione deve eseguire:

Output
{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-5-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll list all Python files in the current directory for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "bash",
      "input": {
        "command": "ls *.py"
      }
    }
  ]
}

Esegui input.command nella tua sessione bash e invia l’output come tool_result. Consulta Implementare lo strumento bash per il ciclo completo.

Come funziona

Ogni chiamata allo strumento è un ciclo completo tra Claude e la tua applicazione:

  1. Claude restituisce un blocco tool_use contenente il command da eseguire.
  2. La tua applicazione esegue il comando nella sua sessione bash.
  3. La tua applicazione restituisce a Claude l’output del comando, stdout e stderr insieme, in un blocco tool_result.
  4. Claude richiede un altro comando nella stessa sessione oppure risponde con del testo.

Claude può anche restituire più blocchi tool_use in un’unica risposta. Eseguili in ordine nella stessa sessione e restituisci tutti i risultati in un unico messaggio user. Consulta Uso parallelo degli strumenti.

L’API è stateless. Nulla della tua sessione shell viaggia tra le richieste, quindi è la tua applicazione a determinare quando la sessione inizia, quanto dura e quando riavviarla. Per il ciclo completo di richiesta e risposta, consulta Gestire le chiamate agli strumenti.

Parametri

Una definizione dello strumento bash ha due campi obbligatori, type e name, e name deve essere bash. Lo strumento è privo di schema: non fornisci un input_schema, perché lo schema è integrato nel modello di Claude e non può essere modificato. La tabella seguente elenca i campi di input che Claude imposta quando chiama lo strumento.

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

*Obbligatorio a meno che non si usi restart

Per gestire restart: true, termina il processo shell, avviane uno nuovo e restituisci un tool_result che confermi il riavvio. Una sessione riavviata parte da zero: la directory di lavoro, le variabili d’ambiente e qualsiasi processo in esecuzione non esistono più.

Versioni dello strumento

bash_20250124 è la versione attuale dello strumento e non richiede alcun header beta. Ogni modello a partire da Claude Sonnet 3.7 (ritirato) la accetta, inclusi tutti i modelli Claude attuali.

La versione bash_20241022 funziona solo con il modello Claude Sonnet 3.5 di ottobre 2024 (ritirato). Le richieste che la utilizzano necessitano dell’header anthropic-beta: computer-use-2024-10-22, e l’SDK la espone solo nel suo namespace beta. Le nuove integrazioni dovrebbero usare bash_20250124.

Esempio: automazione in più passaggi

Claude può concatenare comandi attraverso più chiamate allo strumento per completare un’attività in più passaggi:

User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Claude's tool uses:
1. Install package
   {"command": "pip install requests"}

2. Create 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. Run 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

Claude determina quale comando eseguire. Tutto il resto spetta alla tua applicazione: il processo shell, il timeout e i controlli di sicurezza. I passaggi seguenti mostrano un’implementazione minima.

  1. Crea una sessione bash persistente

    Avvia un unico processo bash di lunga durata ed esegui ogni comando al suo interno. Poiché una pipe verso un processo attivo non segnala mai la fine del file, la sessione stampa una riga sentinella univoca dopo ogni comando per indicare dove termina l’output di quel comando:

    import subprocess
    import uuid
    
    
    class BashSession:
        """A bash process that stays alive between commands so state persists."""
    
        def __init__(self):
            self.process = subprocess.Popen(
                ["/bin/bash"],
                stdin=subprocess.PIPE,
                stdout=subprocess.PIPE,
                stderr=subprocess.STDOUT,  # interleave errors with output, in order
                start_new_session=True,  # own process group: a timeout can kill every child
                text=True,
            )
    
        def execute_command(self, command):
            """Run a command in the session and return its output."""
            sentinel = f"__CLAUDE_BASH_DONE_{uuid.uuid4().hex}__"  # unique for each call
            self.process.stdin.write(f"{command}\necho {sentinel}\n")
            self.process.stdin.flush()
    
            output = []
            for line in self.process.stdout:
                if sentinel in line:  # this command's output is complete
                    break
                output.append(line)
            return "".join(output)
    
        def restart(self):
            self.process.kill()
            self.process.wait()
            self.__init__()
    
    
    bash_session = BashSession()
    print(bash_session.execute_command("cd /tmp && pwd"))
    print(bash_session.execute_command("pwd"))  # still /tmp: the session kept its state

    La sessione intercala stderr con stdout, quindi i messaggi di errore compaiono nel punto in cui si sono verificati. L’esempio omette ciò di cui un’implementazione completa ha bisogno: un timeout che, quando un comando si blocca, termini la shell e ogni processo da essa avviato, e poi riavvii la sessione. La best practice Usa i timeout dei comandi mostra un modo per aggiungerlo.

  2. Elabora le chiamate agli strumenti di Claude

    Estrai ed esegui i comandi dalle risposte di Claude:

    tool_results = []
    for content in response.content:
        if content.type == "tool_use" and content.name == "bash":
            if content.input.get("restart"):
                bash_session.restart()
                result = "Bash session restarted"
            else:
                command = content.input.get("command")
                result = bash_session.execute_command(command)
    
            # Un tool_result per ogni blocco tool_use, tutti restituiti nel successivo messaggio dell'utente
            tool_results.append(
                {"type": "tool_result", "tool_use_id": content.id, "content": result}
            )
  3. Restituisci il risultato a Claude

    Invia il tool_result in un messaggio user che prosegue la stessa conversazione. Claude richiede un altro comando nella stessa sessione oppure completa la sua risposta:

    client = anthropic.Anthropic()
    
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        tools=[{"type": "bash_20250124", "name": "bash"}],
        messages=[
            {"role": "user", "content": "List all Python files in the current directory."},
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "tool_use",
                        "id": "toolu_01A09q90qw90lq917835lq9",
                        "name": "bash",
                        "input": {"command": "ls *.py"},
                    }
                ],
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                        "content": "analysis.py\nprocess_data.py\n",
                    }
                ],
            },
        ],
    )
    
    print(response.content)

    Ripeti il ciclo di esecuzione e restituzione finché stop_reason è tool_use. Per il ciclo completo, consulta Gestire i risultati degli strumenti client.

  4. Implementa misure di sicurezza

    Aggiungi convalida e restrizioni. Usa una allowlist anziché una blocklist: una blocklist non intercetta alcun comando che non abbia previsto. L’esempio rifiuta anche gli operatori shell che compaiono come parole separate:

    import shlex
    
    ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
    SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}
    
    
    def validate_command(command):
        # Consenti solo i comandi presenti in una allowlist esplicita
        try:
            tokens = shlex.split(command)
        except ValueError:
            return False, "Could not parse command"
    
        if not tokens:
            return False, "Empty command"
    
        executable = tokens[0]
        if executable not in ALLOWED_COMMANDS:
            return False, f"Command '{executable}' is not in the allowlist"
    
        # Rifiuta gli operatori della shell scritti come parole separate
        for token in tokens[1:]:
            if token in SHELL_OPERATORS or token.startswith(("$", "`")):
                return False, f"Shell operator '{token}' is not allowed"
    
        return True, None

    Questo controllo è un campanello d’allarme per gli errori evidenti, non un confine di applicazione delle regole. Rifiuta la concatenazione con spazi (&&), le pipe e il reindirizzamento che gli altri esempi di questa pagina utilizzano. Non intercetta un operatore attaccato a una parola, come cat data.txt|grep x, perché il tokenizer mantiene data.txt|grep all’interno di un unico token. Decidi quali comandi e operatori la tua applicazione consente. Il vero controllo è l’isolamento: esegui l’intera sessione all’interno di un container o di una macchina virtuale (consulta Sicurezza).

Gestire gli errori

Quando un comando fallisce o la sessione si interrompe, comunica a Claude cosa è successo. Restituisci il messaggio come contenuto del tool_result e imposta is_error su true, il che contrassegna la chiamata allo strumento come fallita. Consulta Gestire gli errori con is_error.

Segui le best practice di implementazione

Sicurezza

Oltre all’isolamento, aggiungi questi controlli:

  • Convalida i comandi prima di eseguirli, con una allowlist anziché una blocklist. Consulta Implementare lo strumento bash.
  • Imposta limiti di risorse sul processo shell (CPU, memoria e disco), ad esempio con ulimit.
  • Registra ogni comando e il relativo output in modo da poter verificare cosa è stato eseguito.
  • Oscura credenziali e altri segreti dall’output prima di restituirlo a Claude.

Prezzi

La definizione dello strumento bash aggiunge i seguenti token di input alla tua richiesta. Questo si aggiunge al prompt di sistema per l’uso degli strumenti specifico per modello, che si applica ogni volta che è presente uno strumento qualsiasi.

ModelloToken di input aggiuntivi
Claude 4.7 e modelli successivi e Claude Mythos Preview325 token
Claude 4.6 e modelli precedenti244 token

Token aggiuntivi vengono consumati da:

  • Output dei comandi (stdout/stderr)
  • Messaggi di errore
  • Contenuti di file di grandi dimensioni

Consulta i prezzi dell’uso degli strumenti per i dettagli completi sui prezzi.

Schemi comuni

Flussi di lavoro di sviluppo

  • Esecuzione dei test: pytest && coverage report
  • Build dei progetti: npm install && npm run build
  • Esecuzione di operazioni Git: git status && git add . && git commit -m "message"

Per indicazioni sull’uso di Git come meccanismo di checkpoint e ripristino nei flussi di lavoro di agenti a lunga esecuzione, consulta le best practice per la gestione dello stato.

Operazioni sui file

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

Attività di sistema

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

Limitazioni

  • Nessun comando interattivo: La sessione non può eseguire vim, less, richieste di password o qualsiasi comando che attenda un input su stdin.
  • Nessuna applicazione GUI: La sessione è solo a riga di comando.
  • Ambito della sessione: Lo stato della sessione bash è lato client. La tua applicazione è responsabile del mantenimento della sessione shell tra i turni.
  • Limiti di output: L’API non tronca i risultati degli strumenti (una richiesta sovradimensionata viene rifiutata). Tronca gli output di grandi dimensioni nella tua applicazione prima di restituirli a Claude.
  • Nessuno streaming: L’output raggiunge Claude solo quando la tua applicazione restituisce il tool_result nella richiesta successiva.

Combinazione con altri strumenti

Lo strumento bash si abbina bene allo strumento editor di testo: Claude modifica un file con uno strumento e richiede con l’altro il comando che lo esegue.

Passaggi successivi

Visualizza e modifica file di testo per eseguire il debug, correggere e migliorare il codice.

Collega Claude a strumenti e API esterni. Scopri dove vengono eseguiti gli strumenti, quando Claude li chiama e quale strumento è adatto al tuo compito.

Disponibilità

Strumento Bash
I requisiti di disponibilità per Strumento Bash sono gli stessi su tutte le piattaforme supportate.
API
  • Messages API
Modelli
  • Tutti i modelli

Endpoint applicabili

  • /v1/messages con lo strumento bash
Conservazione zero dei datiIdoneo

Esclude Modelli coperti

Strumento lato client eseguito nel tuo ambiente.

HIPAAIdoneo

Questa pagina ti è stata utile?