Alat bash adalah client tool (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 seluruh panggilan 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, header beta, dan versi sebelumnya, lihat Versi alat. Untuk semua alat yang disediakan Anthropic, lihat Referensi alat.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-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",
"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 output sebagai tool_result. Lihat Mengimplementasikan alat bash untuk siklus lengkapnya.
Setiap panggilan alat adalah satu siklus bolak-balik antara Claude dan aplikasi Anda:
tool_use yang berisi command untuk dijalankan.tool_result.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 informasi tentang sesi shell Anda yang berpindah antar permintaan, sehingga aplikasi Anda yang menentukan kapan sesi dimulai, berapa lama sesi berlangsung, dan kapan harus memulai ulang. Untuk siklus permintaan dan respons lengkap, lihat Menangani panggilan alat.
Definisi alat bash memiliki dua field wajib, type dan name, dan name harus bernilai bash. Alat ini tidak memiliki skema: Anda tidak menyediakan input_schema, karena skema sudah tertanam dalam model Claude dan tidak dapat dimodifikasi. Tabel berikut mencantumkan field input yang diatur 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 akan hilang.
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 asli bash_20241022 adalah bagian dari beta computer use, dan rilis Claude Sonnet 3.5 Oktober 2024 (dihentikan) adalah satu-satunya model yang menerimanya. Permintaan yang menggunakannya memerlukan header anthropic-beta: computer-use-2024-10-22, dan SDK hanya mengeksposnya di namespace beta mereka. Integrasi baru sebaiknya menggunakan bash_20250124.
Claude dapat merangkai perintah di seluruh panggilan 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.
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.
Buat sesi bash persisten
Mulai satu proses bash yang 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 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 stateSesi menyisipkan stderr dengan stdout, sehingga pesan kesalahan muncul di tempat terjadinya. Contoh ini tidak menyertakan apa yang juga dibutuhkan oleh implementasi lengkap: timeout yang menghentikan shell dan setiap proses yang dimulainya ketika perintah macet, lalu memulai ulang sesi. Praktik terbaik Gunakan timeout perintah menunjukkan salah satu cara untuk menambahkannya.
Proses panggilan 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 per blok tool_use, semuanya dikembalikan dalam pesan pengguna berikutnya
tool_results.append(
{"type": "tool_result", "tool_use_id": content.id, "content": result}
)Kembalikan hasil ke Claude
Kirim kembali tool_result dalam pesan user yang melanjutkan percakapan yang sama. Claude meminta perintah lain dalam sesi yang sama atau menyelesaikan jawabannya:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-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 adalah tool_use. Untuk loop lengkap, lihat Menangani hasil dari alat klien.
Terapkan langkah-langkah keamanan
Tambahkan validasi dan pembatasan. Gunakan allowlist (daftar izin) daripada blocklist (daftar blokir): blocklist melewatkan perintah apa pun yang tidak diantisipasi. 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):
# 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, NonePemeriksaan ini adalah pengaman untuk kesalahan yang jelas, bukan batas penegakan. Pemeriksaan ini menolak chaining dengan spasi (&&), pipe, dan redirection yang digunakan oleh 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 sebenarnya adalah isolasi: jalankan seluruh sesi di dalam container atau mesin virtual (lihat Keamanan).
Ketika 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 panggilan alat sebagai gagal. Lihat Menangani kesalahan dengan is_error.
Selain isolasi, tambahkan kontrol berikut:
ulimit.Definisi bash tool menambahkan token input berikut ke permintaan Anda. Ini merupakan tambahan dari prompt sistem penggunaan alat per-model yang berlaku setiap kali ada alat apa pun.
| Model | Token input tambahan |
|---|---|
| Claude Opus 5, Claude Opus 4.8, dan Claude Opus 4.7 | 325 token |
| Claude Opus 4.6, Claude Sonnet 4.6, dan versi sebelumnya | 244 token |
Token tambahan dikonsumsi oleh:
Lihat harga penggunaan alat untuk detail harga lengkap.
pytest && coverage reportnpm install && npm run buildgit 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.
wc -l *.csv && ls -lh *.csvfind . -name "*.py" | xargs grep "pattern"tar -czf backup.tar.gz ./datadf -h && free -mps aux | grep pythonexport PATH=$PATH:/new/path && echo $PATHvim, less, prompt kata sandi, atau perintah apa pun yang menunggu input pada stdin.tool_result dalam permintaan berikutnya.Alat bash cocok dipasangkan dengan Alat text editor: Claude mengedit file dengan satu alat dan meminta perintah yang menjalankannya dengan alat lainnya.
Lihat dan modifikasi file teks untuk melakukan debug, memperbaiki, dan meningkatkan kode.
Hubungkan Claude ke alat dan API eksternal. Lihat di mana alat dieksekusi, kapan Claude memanggilnya, dan alat mana yang sesuai dengan tugas Anda.
Was this page helpful?