Claude Platform Docs
PesanAlat

Alat bash

Biarkan Claude meminta perintah shell yang dijalankan aplikasi Anda dalam sesi bash persisten dan dikembalikan sebagai hasil alat.

Alat bash adalah alat klien: Claude tidak menjalankan perintah sendiri. Ketika Anda menyertakan alat ini dalam permintaan, Claude membalas dengan blok tool_use yang menyebutkan perintah yang akan dijalankan. Aplikasi Anda menjalankan perintah tersebut dalam sesi bash yang dimilikinya dan mengembalikan output dalam blok tool_result.

Aplikasi Anda menjaga satu proses bash tetap hidup di sepanjang pemanggilan alat, sehingga state tetap bertahan di antara perintah. Direktori kerja, variabel lingkungan, dan file apa pun yang dibuat oleh suatu perintah masih ada untuk perintah berikutnya.

Versi alat saat ini adalah bash_20250124. Untuk dukungan model, beta header, dan versi sebelumnya, lihat Versi alat. Untuk semua alat yang disediakan Anthropic, lihat Referensi alat.

Kasus penggunaan

  • Alur kerja pengembangan: Jalankan perintah build, pengujian, dan alat pengembangan
  • Otomatisasi sistem: Jalankan skrip, kelola file, otomatiskan tugas
  • Pemrosesan data: Proses file, jalankan skrip analisis, kelola dataset
  • Penyiapan lingkungan: Instal paket, konfigurasikan lingkungan

Mulai cepat

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 merespons dengan stop_reason: "tool_use" dan blok tool_use yang berisi perintah untuk dijalankan oleh aplikasi Anda:

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"
      }
    }
  ]
}

Jalankan input.command dalam sesi bash Anda dan kirim output kembali sebagai tool_result. Lihat Mengimplementasikan alat bash untuk alur bolak-baliknya.

Cara kerjanya

Setiap pemanggilan alat adalah satu “round trip” (perjalanan bolak-balik) antara Claude dan aplikasi Anda:

  1. Claude mengembalikan blok tool_use yang berisi command yang akan dijalankan.
  2. Aplikasi Anda menjalankan perintah tersebut dalam sesi bash-nya.
  3. Aplikasi Anda mengembalikan output perintah, stdout dan stderr bersama-sama, kepada Claude dalam blok tool_result.
  4. Claude kemudian meminta perintah lain dalam sesi yang sama atau merespons dengan teks.

Claude juga dapat mengembalikan beberapa blok tool_use dalam satu respons. Jalankan secara berurutan dalam sesi yang sama dan kembalikan semua hasilnya dalam satu pesan user. Lihat Penggunaan alat paralel.

API bersifat “stateless” (tanpa state). Tidak ada apa pun tentang sesi shell Anda yang dibawa di antara permintaan, sehingga aplikasi Anda yang menentukan kapan sesi dimulai, berapa lama sesi bertahan, dan kapan harus memulai ulang. Untuk siklus permintaan dan respons lengkap, lihat Menangani pemanggilan alat.

Parameter

Definisi alat bash memiliki dua field wajib, type dan name, dan name harus bash. Alat ini tanpa skema: Anda tidak menyediakan input_schema, karena skema sudah tertanam dalam model Claude dan tidak dapat diubah. Tabel berikut mencantumkan field input yang ditetapkan Claude saat memanggil alat.

ParameterWajibDeskripsi
commandYa*Perintah bash yang akan dijalankan
restartTidakAtur ke true untuk memulai ulang sesi bash

*Wajib kecuali menggunakan restart

Untuk menangani restart: true, hentikan proses shell, mulai yang baru, dan kembalikan tool_result yang mengonfirmasi restart. Sesi yang dimulai ulang dimulai dalam keadaan bersih: direktori kerja, variabel lingkungan, dan proses apa pun yang sedang berjalan hilang.

Versi alat

bash_20250124 adalah versi alat saat ini, dan tidak memerlukan header beta. Setiap model mulai dari Claude Sonnet 3.7 (dihentikan) dan seterusnya menerimanya, termasuk semua model Claude saat ini.

Versi bash_20241022 hanya berfungsi dengan model Claude Sonnet 3.5 Oktober 2024 (dihentikan). Permintaan yang menggunakannya memerlukan header anthropic-beta: computer-use-2024-10-22, dan SDK hanya mengeksposnya di namespace beta-nya. Integrasi baru sebaiknya menggunakan bash_20250124.

Contoh: Otomatisasi multilangkah

Claude dapat merangkai perintah di sepanjang pemanggilan alat untuk menyelesaikan tugas multilangkah:

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

Sesi mempertahankan state di antara perintah, sehingga file yang dibuat pada langkah 2 tersedia pada langkah 3.

Mengimplementasikan alat bash

Claude menentukan perintah mana yang akan dijalankan. Aplikasi Anda memiliki segala hal lainnya: proses shell, timeout, dan pemeriksaan keamanan. Langkah-langkah berikut menunjukkan implementasi minimal.

  1. Membuat sesi bash persisten

    Mulai satu proses bash berumur panjang dan jalankan setiap perintah di dalamnya. Karena pipe ke proses yang masih hidup tidak pernah melaporkan end-of-file, sesi mencetak baris sentinel unik setelah setiap perintah untuk menandai di mana output perintah tersebut berakhir:

    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

    Sesi menggabungkan stderr dengan stdout, sehingga pesan kesalahan muncul di tempat terjadinya. Contoh ini tidak menyertakan hal yang juga dibutuhkan implementasi lengkap: timeout yang menghentikan shell dan setiap proses yang dimulainya ketika suatu perintah macet, lalu memulai ulang sesi. Praktik terbaik Menggunakan timeout perintah menunjukkan salah satu cara untuk menambahkannya.

  2. Memproses pemanggilan alat Claude

    Ekstrak dan jalankan perintah dari respons 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)
    
            # Satu tool_result untuk setiap blok tool_use, semuanya dikembalikan di pesan user berikutnya
            tool_results.append(
                {"type": "tool_result", "tool_use_id": content.id, "content": result}
            )
  3. Mengembalikan hasil ke Claude

    Kirim tool_result kembali dalam pesan user yang melanjutkan percakapan yang sama. Claude kemudian meminta perintah lain dalam sesi yang sama atau menyelesaikan jawabannya:

    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)

    Ulangi siklus jalankan-dan-kembalikan selama stop_reason bernilai tool_use. Untuk loop lengkapnya, lihat Menangani hasil dari alat klien.

  4. Menerapkan langkah-langkah keamanan

    Tambahkan validasi dan pembatasan. Gunakan “allowlist” (daftar izin) alih-alih “blocklist” (daftar blokir): blocklist akan melewatkan perintah apa pun yang tidak diantisipasinya. Contoh ini juga menolak operator shell yang muncul sebagai kata terpisah:

    import shlex
    
    ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
    SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}
    
    
    def validate_command(command):
        # Hanya izinkan perintah dari allowlist eksplisit
        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"
    
        # Tolak operator shell yang ditulis sebagai kata terpisah
        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

    Pemeriksaan ini adalah penanda peringatan untuk kesalahan yang jelas, bukan batas penegakan. Pemeriksaan ini menolak perangkaian berspasi (&&), pipe, dan pengalihan yang digunakan oleh contoh lain di halaman ini. Pemeriksaan ini tidak menangkap operator yang menempel pada sebuah kata, seperti cat data.txt|grep x, karena tokenizer menyimpan data.txt|grep di dalam satu token. Tentukan perintah dan operator mana yang diizinkan aplikasi Anda. Kontrol yang sebenarnya adalah isolasi: jalankan seluruh sesi di dalam container atau mesin virtual (lihat Keamanan).

Menangani kesalahan

Ketika suatu perintah gagal atau sesi rusak, beri tahu Claude apa yang terjadi. Kembalikan pesan sebagai konten tool_result dan atur is_error ke true, yang menandai pemanggilan alat sebagai gagal. Lihat Menangani kesalahan dengan is_error.

Mengikuti praktik terbaik implementasi

Keamanan

Selain isolasi, tambahkan kontrol berikut:

  • Validasi perintah sebelum menjalankannya, dengan allowlist alih-alih blocklist. Lihat Mengimplementasikan alat bash.
  • Tetapkan batas sumber daya pada proses shell (CPU, memori, dan disk), misalnya dengan ulimit.
  • Catat setiap perintah dan outputnya sehingga Anda dapat mengaudit apa yang dijalankan.
  • Sembunyikan kredensial dan rahasia lainnya dari output sebelum mengembalikannya ke Claude.

Harga

Definisi alat bash menambahkan token input berikut ke permintaan Anda. Ini merupakan tambahan dari prompt sistem penggunaan alat per model yang berlaku setiap kali ada alat yang disertakan.

ModelToken input tambahan
Model Claude 4.7 dan yang lebih baru serta Claude Mythos Preview325 token
Model Claude 4.6 dan yang lebih lama244 token

Token tambahan dikonsumsi oleh:

  • Output perintah (stdout/stderr)
  • Pesan kesalahan
  • Konten file berukuran besar

Lihat harga penggunaan alat untuk detail harga lengkap.

Pola umum

Alur kerja pengembangan

  • Menjalankan pengujian: pytest && coverage report
  • Membangun proyek: npm install && npm run build
  • Menjalankan operasi Git: git status && git add . && git commit -m "message"

Untuk panduan menggunakan Git sebagai mekanisme checkpoint-dan-pemulihan dalam alur kerja agen yang berjalan lama, lihat praktik terbaik manajemen state.

Operasi file

  • Memproses data: wc -l *.csv && ls -lh *.csv
  • Mencari file: find . -name "*.py" | xargs grep "pattern"
  • Membuat cadangan: tar -czf backup.tar.gz ./data

Tugas sistem

  • Memeriksa sumber daya: df -h && free -m
  • Mengelola proses: ps aux | grep python
  • Menyiapkan lingkungan: export PATH=$PATH:/new/path && echo $PATH

Keterbatasan

  • Tidak ada perintah interaktif: Sesi tidak dapat menjalankan vim, less, prompt kata sandi, atau perintah apa pun yang menunggu input di stdin.
  • Tidak ada aplikasi GUI: Sesi hanya berbasis baris perintah.
  • Cakupan sesi: State sesi bash berada di sisi klien. Aplikasi Anda bertanggung jawab untuk mempertahankan sesi shell di antara giliran.
  • Batas output: API tidak memotong hasil alat (permintaan yang terlalu besar akan ditolak). Potong output besar di aplikasi Anda sebelum mengembalikannya ke Claude.
  • Tidak ada streaming: Output hanya sampai ke Claude ketika aplikasi Anda mengembalikan tool_result dalam permintaan berikutnya.

Menggabungkan dengan alat lain

Alat bash berpasangan dengan baik dengan Alat editor teks: Claude mengedit file dengan satu alat dan meminta perintah yang menjalankannya dengan alat lainnya.

Langkah selanjutnya

Lihat dan ubah file teks untuk men-debug, memperbaiki, dan meningkatkan kode.

Hubungkan Claude ke alat dan API eksternal. Lihat di mana alat berjalan, kapan Claude memanggilnya, dan alat mana yang sesuai dengan tugas Anda.

Ketersediaan

Alat bash
Persyaratan ketersediaan untuk Alat bash sama di semua platform yang didukung.
API
  • Messages API
Model
  • Semua model

Endpoint yang berlaku

  • /v1/messages dengan alat bash
Retensi data nolLayak

Tidak termasuk Model yang dicakup

Alat sisi klien yang dijalankan di environment Anda.

HIPAALayak

Apakah halaman ini membantu?