Alat bash

Alat bash adalah alat klien: Claude tidak menjalankan perintah sendiri. Saat 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 seluruh pemanggilan alat, sehingga state bertahan antar 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, header beta, dan versi sebelumnya, lihat Versi alat. Untuk semua alat yang disediakan Anthropic, lihat Referensi alat.

Kasus penggunaan

• Alur kerja pengembangan: Menjalankan perintah build, pengujian, dan alat pengembangan
• Otomatisasi sistem: Mengeksekusi skrip, mengelola file, mengotomatiskan tugas
• Pemrosesan data: Memproses file, menjalankan skrip analisis, mengelola dataset
• Penyiapan lingkungan: Menginstal paket, mengonfigurasi 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 aplikasi Anda:

{
  "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 kembali outputnya sebagai tool_result. Lihat Mengimplementasikan alat bash untuk siklus bolak-baliknya.

Cara kerjanya

Setiap pemanggilan alat adalah satu siklus bolak-balik antara Claude dan aplikasi Anda:

1. Claude mengembalikan blok tool_use yang berisi command untuk dijalankan.
2. Aplikasi Anda menjalankan perintah tersebut dalam sesi bash-nya.
3. Aplikasi Anda mengembalikan output perintah, stdout dan stderr bersama-sama, ke Claude dalam blok tool_result.
4. Claude 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. Tidak ada apa pun tentang sesi shell Anda yang berpindah antar permintaan, sehingga aplikasi Anda yang menentukan kapan sesi dimulai, berapa lama sesi hidup, dan kapan memulai ulangnya. Untuk siklus permintaan dan respons lengkap, lihat Menangani pemanggilan alat.

Parameter

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

*Wajib kecuali menggunakan restart

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

{
  "command": "ls -la *.py"
}

{
  "restart": true
}

Versi alat

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

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

Contoh: Otomatisasi multilangkah

Claude dapat merangkai perintah di seluruh 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 antar 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 semua hal lainnya: proses shell, timeout, dan pemeriksaan keamanan. Langkah-langkah berikut menunjukkan implementasi minimal.

1. 1

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   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 per 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 menyelang-nyelingkan stderr dengan stdout, sehingga pesan kesalahan muncul di tempat terjadinya. Contoh ini tidak menyertakan hal yang juga dibutuhkan implementasi lengkap: timeout yang mematikan shell dan setiap proses yang dimulainya ketika suatu perintah macet, lalu memulai ulang sesi. Praktik terbaik Gunakan timeout perintah menunjukkan salah satu cara menambahkannya.

2. 2

   Proses pemanggilan alat dari Claude

   Ekstrak dan jalankan perintah dari respons Claude:

   PythonTypeScriptC#GoJavaPHPRuby

   

   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 per blok tool_use, semuanya dikembalikan dalam pesan pengguna berikutnya
           tool_results.append(
               {"type": "tool_result", "tool_use_id": content.id, "content": result}
           )

3. 3

   Kembalikan hasilnya ke Claude

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

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   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. 4

   Mengimplementasikan langkah-langkah keamanan

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   import shlex
   
   ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
   SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}
   
   
   def validate_command(command):
       # Izinkan hanya 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 alarm untuk kesalahan yang jelas, bukan batas penegakan. Pemeriksaan ini menolak perangkaian berspasi (&&), pipe, dan pengalihan yang digunakan contoh-contoh lain di halaman ini. Pemeriksaan ini tidak menangkap operator yang menempel pada kata, seperti cat data.txt|grep x, karena tokenizer menyimpan data.txt|grep dalam satu token. Tentukan perintah dan operator mana yang diizinkan aplikasi Anda. Kontrol yang sesungguhnya 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 tersebut sebagai konten tool_result dan setel is_error ke true, yang menandai pemanggilan alat sebagai gagal. Lihat Menangani kesalahan dengan is_error.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: command did not finish within 30 seconds",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: nonexistentcommand: command not found",
      "is_error": true
    }
  ]
}

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

Ikuti praktik terbaik implementasi

import concurrent.futures
import os
import signal


def execute_with_timeout(session, command, timeout=30):
    """Run a command in the session, replacing the session if the command hangs."""
    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
        future = pool.submit(session.execute_command, command)
        try:
            return future.result(timeout=timeout)
        except concurrent.futures.TimeoutError:
            # Grup ini mencakup shell dan setiap proses yang dimulai oleh perintah tersebut
            os.killpg(session.process.pid, signal.SIGKILL)
            session.restart()
            return f"Error: command did not finish within {timeout} seconds"

# Perintah yang dijalankan dalam sesi yang sama mempertahankan status
commands = [
    "cd /tmp",
    "echo 'Hello' > test.txt",
    "cat test.txt",  # The session is still in /tmp
]

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 truncated ({len(lines)} total lines) ..."
    return output

import logging

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")


def execute_and_log(session, command):
    """Run a command in the session and keep an audit record of it."""
    logging.info("command=%r", command)
    output = session.execute_command(command)
    logging.info("output=%r", output[:200])  # first 200 characters
    return output

Keamanan

Selain isolasi, tambahkan kontrol berikut:

• Validasi perintah sebelum menjalankannya, dengan allowlist, bukan blocklist. Lihat Mengimplementasikan alat bash.
• Tetapkan batas sumber daya pada proses shell (CPU, memori, dan disk), misalnya dengan ulimit.
• Catat setiap perintah dan outputnya agar Anda dapat mengaudit apa yang dijalankan.
• Sunting 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.

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
• 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
• Manajemen proses: ps aux | grep python
• Penyiapan 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 pada 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 antar 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 cocok dipasangkan dengan Alat editor teks: Claude mengedit file dengan satu alat dan meminta perintah yang menjalankannya dengan alat lainnya.

Langkah selanjutnya