MessaggiStrumenti

Strumento Bash

Questa funzionalità è idonea per la Zero Data Retention (ZDR). Quando la tua organizzazione dispone di un accordo ZDR, i dati inviati tramite questa funzionalità non vengono conservati dopo che la risposta dell'API è stata restituita.

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. L'accesso alla shell è una capacità fondamentale per gli agenti. Su Terminal-Bench 2.0, un benchmark che valuta attività reali da terminale utilizzando la validazione solo tramite shell, Claude mostra notevoli miglioramenti nelle prestazioni quando ha accesso a una sessione bash persistente.

Panoramica

Lo strumento bash fornisce a Claude:

Una sessione bash persistente che mantiene lo stato
La capacità di eseguire qualsiasi comando shell
Accesso alle variabili d'ambiente e alla directory di lavoro
Capacità di concatenazione di comandi e scripting

Per il supporto dei modelli, 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 dati: Elabora file, esegui script di analisi, gestisci dataset
Configurazione dell'ambiente: Installa pacchetti, configura ambienti

Avvio rapido

import anthropic

client = anthropic.Anthropic()

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

print(response)

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	Obbligatorio	Descrizione
`command`	Sì*	Il comando bash da eseguire
`restart`	No	Imposta a `true` per riavviare la sessione bash

*Obbligatorio a meno che non si utilizzi restart

Esempio: Automazione multi-step

Claude può concatenare comandi per completare attività complesse:

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

Lo strumento bash è implementato come uno strumento senza schema. Quando utilizzi 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.

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

Gestisci l'esecuzione dei comandi

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

def execute_command(self, command):
    # Invia il comando a bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Cattura l'output con timeout
    output = self._read_output(timeout=10)
    return output

Elabora le chiamate agli strumenti di Claude

Estrai ed esegui i 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 = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Restituisci il risultato a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementa misure di sicurezza

Aggiungi validazione e restrizioni. Usa una allowlist (lista di elementi consentiti) anziché una blocklist, poiché le blocklist sono facili da aggirare. Rifiuta gli operatori shell in modo che i comandi concatenati non possano eludere la allowlist:

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 di shell che concatenerebbero comandi aggiuntivi
    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 è una prima linea di difesa. Per un isolamento più forte, esegui i comandi validati con shell=False e passa shlex.split(command) come lista di argomenti, in modo che la shell non interpreti mai la stringa.

Gestire gli errori

Quando implementi lo strumento bash, gestisci vari scenari di errore:

Segui le best practice 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 i comandi e allowlist
Impostazione di limiti di risorse (CPU, memoria, disco)
Registrazione di tutti i comandi eseguiti

Raccomandazioni chiave

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

Prezzi

Lo strumento bash aggiunge 245 token di input alle tue chiamate API.

Token aggiuntivi vengono consumati da:

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

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

Pattern comuni

Flussi di lavoro di sviluppo

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

Checkpointing basato su Git

Git funge da meccanismo di recupero strutturato nei flussi di lavoro degli agenti a lunga esecuzione, non solo come modo per salvare le modifiche:

Cattura una baseline: Prima che inizi qualsiasi lavoro dell'agente, esegui il commit dello stato corrente. Questo è il punto di partenza noto e funzionante.
Commit per funzionalità: Ogni funzionalità completata riceve il proprio commit. Questi servono come punti di rollback se qualcosa va storto in seguito.
Ricostruisci lo stato all'avvio della sessione: Leggi git log insieme a un file di avanzamento per capire cosa è già stato fatto e cosa viene dopo.
Ripristina in caso di errore: Se il lavoro va male, git checkout ripristina l'ultimo commit valido invece di tentare di eseguire il debug di uno stato corrotto.

Operazioni sui file

Elaborazione dati: wc -l *.csv && ls -lh *.csv
Ricerca di 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: Non può gestire vim, less o prompt di password
Nessuna applicazione GUI: Solo riga di comando
Ambito della sessione: Lo stato della sessione bash è lato client. L'API è stateless. La tua applicazione è responsabile del mantenimento della sessione shell tra i turni.
Limiti di output: Output di grandi dimensioni potrebbero essere troncati
Nessuno streaming: I risultati vengono restituiti dopo il completamento

Combinazione con altri strumenti

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

Se stai utilizzando anche lo strumento di esecuzione del codice, Claude ha accesso a due ambienti di esecuzione separati: la tua sessione bash locale e il container sandbox di Anthropic. Lo stato non è condiviso tra di essi. Consulta Utilizzo dell'esecuzione del codice con altri strumenti di esecuzione per indicazioni su come istruire Claude a distinguere tra gli ambienti.

Passaggi successivi

Panoramica sull'uso degli strumenti

Scopri di più sull'uso degli strumenti con Claude

Strumento editor di testo

Visualizza e modifica file di testo con Claude

Was this page helpful?

MessaggiStrumenti

Strumento Bash

Panoramica

Lo strumento bash fornisce a Claude:

Una sessione bash persistente che mantiene lo stato
La capacità di eseguire qualsiasi comando shell
Accesso alle variabili d'ambiente e alla directory di lavoro
Capacità di concatenazione di comandi e scripting

Per il supporto dei modelli, 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 dati: Elabora file, esegui script di analisi, gestisci dataset
Configurazione dell'ambiente: Installa pacchetti, configura ambienti

Avvio rapido

import anthropic

client = anthropic.Anthropic()

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

print(response)

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	Obbligatorio	Descrizione
`command`	Sì*	Il comando bash da eseguire
`restart`	No	Imposta a `true` per riavviare la sessione bash

*Obbligatorio a meno che non si utilizzi restart

Esempio: Automazione multi-step

Claude può concatenare comandi per completare attività complesse:

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

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

Gestisci l'esecuzione dei comandi

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

def execute_command(self, command):
    # Invia il comando a bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Cattura l'output con timeout
    output = self._read_output(timeout=10)
    return output

Elabora le chiamate agli strumenti di Claude

Estrai ed esegui i 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 = "Bash session restarted"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)

        # Restituisci il risultato a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementa misure di sicurezza

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 di shell che concatenerebbero comandi aggiuntivi
    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

Gestire gli errori

Quando implementi lo strumento bash, gestisci vari scenari di errore:

Segui le best practice 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 i comandi e allowlist
Impostazione di limiti di risorse (CPU, memoria, disco)
Registrazione di tutti i comandi eseguiti

Raccomandazioni chiave

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

Prezzi

Lo strumento bash aggiunge 245 token di input alle tue chiamate API.

Token aggiuntivi vengono consumati da:

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

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

Pattern comuni

Flussi di lavoro di sviluppo

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

Checkpointing basato su Git

Git funge da meccanismo di recupero strutturato nei flussi di lavoro degli agenti a lunga esecuzione, non solo come modo per salvare le modifiche:

Cattura una baseline: Prima che inizi qualsiasi lavoro dell'agente, esegui il commit dello stato corrente. Questo è il punto di partenza noto e funzionante.
Commit per funzionalità: Ogni funzionalità completata riceve il proprio commit. Questi servono come punti di rollback se qualcosa va storto in seguito.
Ricostruisci lo stato all'avvio della sessione: Leggi git log insieme a un file di avanzamento per capire cosa è già stato fatto e cosa viene dopo.
Ripristina in caso di errore: Se il lavoro va male, git checkout ripristina l'ultimo commit valido invece di tentare di eseguire il debug di uno stato corrotto.

Operazioni sui file

Elaborazione dati: wc -l *.csv && ls -lh *.csv
Ricerca di 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: Non può gestire vim, less o prompt di password
Nessuna applicazione GUI: Solo riga di comando
Ambito della sessione: Lo stato della sessione bash è lato client. L'API è stateless. La tua applicazione è responsabile del mantenimento della sessione shell tra i turni.
Limiti di output: Output di grandi dimensioni potrebbero essere troncati
Nessuno streaming: I risultati vengono restituiti dopo il completamento

Combinazione con altri strumenti

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

Passaggi successivi

Panoramica sull'uso degli strumenti

Scopri di più sull'uso degli strumenti con Claude

Strumento editor di testo

Visualizza e modifica file di testo con Claude

Was this page helpful?

Panoramica

Casi d'uso

Avvio rapido

Come funziona

Parametri

Esempio di utilizzo

Esempio: Automazione multi-step

Implementare lo strumento bash

Gestire gli errori

Timeout di esecuzione del comando

Comando non trovato

Permesso negato

Segui le best practice di implementazione

Usa timeout per i comandi

Mantieni lo stato della sessione

Gestisci output di grandi dimensioni

Registra tutti i comandi

Sanitizza gli output

Sicurezza

Raccomandazioni chiave

Prezzi

Pattern comuni

Flussi di lavoro di sviluppo

Checkpointing basato su Git

Operazioni sui file

Attività di sistema

Limitazioni

Combinazione con altri strumenti

Passaggi successivi

Panoramica

Casi d'uso

Avvio rapido

Come funziona

Parametri

Esempio di utilizzo

Esempio: Automazione multi-step

Implementare lo strumento bash

Gestire gli errori

Timeout di esecuzione del comando

Comando non trovato

Permesso negato

Segui le best practice di implementazione

Usa timeout per i comandi

Mantieni lo stato della sessione

Gestisci output di grandi dimensioni

Registra tutti i comandi

Sanitizza gli output

Sicurezza

Raccomandazioni chiave

Prezzi

Pattern comuni

Flussi di lavoro di sviluppo

Checkpointing basato su Git

Operazioni sui file

Attività di sistema

Limitazioni

Combinazione con altri strumenti

Passaggi successivi