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:
{
"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:
- Claude mengembalikan blok
tool_useyang berisicommandyang akan dijalankan. - Aplikasi Anda menjalankan perintah tersebut dalam sesi bash-nya.
- Aplikasi Anda mengembalikan output perintah, stdout dan stderr bersama-sama, kepada Claude dalam blok
tool_result. - 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.
| Parameter | Wajib | Deskripsi |
|---|---|---|
command | Ya* | Perintah bash yang akan dijalankan |
restart | Tidak | Atur 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.
Menjalankan perintah:
{
"command": "ls -la *.py"
}Memulai ulang sesi:
{
"restart": true
}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.
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:
Pythonimport 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 stateSesi 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.
Memproses pemanggilan alat Claude
Ekstrak dan jalankan perintah dari respons Claude:
Pythontool_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} )Mengembalikan hasil ke Claude
Kirim
tool_resultkembali dalam pesanuseryang melanjutkan percakapan yang sama. Claude kemudian meminta perintah lain dalam sesi yang sama atau menyelesaikan jawabannya:Pythonclient = 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_reasonbernilaitool_use. Untuk loop lengkapnya, lihat Menangani hasil dari alat klien.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:
Pythonimport 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, NonePemeriksaan 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, seperticat data.txt|grep x, karena tokenizer menyimpandata.txt|grepdi 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.
Jika suatu perintah membutuhkan waktu terlalu lama untuk dijalankan:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: command did not finish within 30 seconds",
"is_error": true
}
]
}Jika suatu perintah tidak ada:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: nonexistentcommand: command not found",
"is_error": true
}
]
}Jika ada masalah izin:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: /root/sensitive-file: Permission denied",
"is_error": true
}
]
}Mengikuti praktik terbaik implementasi
Perintah yang tidak pernah selesai, seperti perintah yang menunggu input, memblokir sesi selamanya karena baris sentinelnya tidak pernah tiba. Berikan tenggat waktu untuk setiap perintah. Ketika tenggat waktu terlewati, hentikan shell dan semua yang dimulai oleh perintah tersebut, lalu mulai ulang sesi:
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 tersebut adalah shell beserta setiap proses yang dijalankan oleh perintah tersebut
os.killpg(session.process.pid, signal.SIGKILL)
session.restart()
return f"Error: command did not finish within {timeout} seconds"Penghentian ini menghentikan perintah yang macet dan semua yang dimulainya. Kembalikan pesan sebagai tool_result kesalahan (lihat Menangani kesalahan), yang menandai pemanggilan alat sebagai gagal.
Jaga sesi bash tetap persisten untuk mempertahankan variabel lingkungan dan direktori kerja:
# Perintah yang dijalankan dalam sesi yang sama mempertahankan state
commands = [
"cd /tmp",
"echo 'Hello' > test.txt",
"cat test.txt", # The session is still in /tmp
]Potong output besar untuk mencegah masalah batas 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 truncated ({len(lines)} total lines) ..."
return outputSimpan jejak audit. Arahkan setiap perintah melalui satu wrapper yang mencatat perintah sebelum dijalankan dan output setelah selesai. Perintah yang macet atau merusak sesi tetap meninggalkan catatan:
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 outputCatatan dikirim ke stderr secara default; arahkan ke file atau pipeline logging Anda untuk menyimpannya. Sertakan apa pun yang mengaitkan catatan dengan permintaan di aplikasi Anda, seperti pengguna akhir dan tool_use_id.
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.
| Model | Token input tambahan |
|---|---|
| Model Claude 4.7 dan yang lebih baru serta Claude Mythos Preview | 325 token |
| Model Claude 4.6 dan yang lebih lama | 244 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_resultdalam 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
Claude API
- API
- Messages API
- Model
- Semua model
Amazon Bedrock
- API
- Messages API
- Model
- Semua model
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Model
- Semua model
Claude Platform on AWS
- API
- Messages API
- Model
- Semua model
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Model
- Semua model
Microsoft Foundry
- API
- Messages API
- Model
- Semua model
Penanganan data
Ikhtisar penanganan dataEndpoint yang berlaku
/v1/messagesdengan alatbash
Tidak termasuk Model yang dicakup
Alat sisi klien yang dijalankan di environment Anda.
Apakah halaman ini membantu?