A ferramenta bash é uma ferramenta de cliente: o Claude não executa comandos por conta própria. Quando você inclui a ferramenta em uma requisição, o Claude responde com um bloco tool_use que indica o comando a ser executado. Sua aplicação executa esse comando em uma sessão bash que ela controla e retorna a saída em um bloco tool_result.
Sua aplicação mantém um processo bash ativo entre as chamadas de ferramenta, de modo que o estado persiste entre os comandos. O diretório de trabalho, as variáveis de ambiente e quaisquer arquivos que um comando crie continuam disponíveis para o próximo comando.
A versão atual da ferramenta é bash_20250124. Para suporte de modelos, cabeçalhos beta e a versão anterior, consulte Versões da ferramenta. Para todas as ferramentas fornecidas pela Anthropic, consulte a Referência de ferramentas.
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)O Claude responde com stop_reason: "tool_use" e um bloco tool_use que contém o comando para sua aplicação executar:
{
"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"
}
}
]
}Execute input.command na sua sessão bash e envie a saída de volta como um tool_result. Consulte Implementar a ferramenta bash para ver o ciclo completo.
Cada chamada de ferramenta é uma ida e volta entre o Claude e sua aplicação:
tool_use contendo o command a ser executado.tool_result.O Claude também pode retornar vários blocos tool_use em uma única resposta. Execute-os em ordem na mesma sessão e retorne todos os resultados em uma única mensagem user. Consulte Uso de ferramentas em paralelo.
A API é stateless (sem estado). Nada sobre sua sessão de shell é transmitido entre requisições, então sua aplicação decide quando a sessão começa, quanto tempo ela dura e quando reiniciá-la. Para o ciclo completo de requisição e resposta, consulte Tratar chamadas de ferramenta.
Uma definição de ferramenta bash tem dois campos obrigatórios, type e name, e o name deve ser bash. A ferramenta não tem esquema: você não fornece um input_schema, porque o esquema está embutido no modelo do Claude e não pode ser modificado. A tabela a seguir lista os campos de entrada que o Claude define quando chama a ferramenta.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
command | Sim* | O comando bash a ser executado |
restart | Não | Defina como true para reiniciar a sessão bash |
*Obrigatório, a menos que esteja usando restart
Para tratar restart: true, encerre o processo do shell, inicie um novo e retorne um tool_result que confirme a reinicialização. Uma sessão reiniciada começa limpa: o diretório de trabalho, as variáveis de ambiente e quaisquer processos em execução são perdidos.
bash_20250124 é a versão atual da ferramenta e não requer cabeçalho beta. Todos os modelos a partir do Claude Sonnet 3.7 (desativado) a aceitam, incluindo todos os modelos Claude atuais.
A versão original bash_20241022 faz parte do beta de computer use, e o lançamento de outubro de 2024 do Claude Sonnet 3.5 (desativado) é o único modelo que a aceita. Requisições que a usam precisam do cabeçalho anthropic-beta: computer-use-2024-10-22, e os SDKs a expõem apenas em seus namespaces beta. Novas integrações devem usar bash_20250124.
O Claude pode encadear comandos entre chamadas de ferramenta para concluir uma tarefa de várias etapas:
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"}A sessão mantém o estado entre os comandos, então os arquivos criados na etapa 2 estão disponíveis na etapa 3.
O Claude determina qual comando executar. Sua aplicação é responsável por todo o resto: o processo do shell, o timeout e as verificações de segurança. As etapas a seguir mostram uma implementação mínima.
Criar uma sessão bash persistente
Inicie um processo bash de longa duração e execute todos os comandos dentro dele. Como um pipe para um processo ativo nunca reporta fim de arquivo, a sessão imprime uma linha sentinela única após cada comando para marcar onde a saída desse comando termina:
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 stateA sessão intercala stderr com stdout, de modo que as mensagens de erro aparecem onde ocorreram. O exemplo omite o que uma implementação completa também precisa: um timeout que encerra o shell e todos os processos que ele iniciou quando um comando trava, e então reinicia a sessão. A prática recomendada Usar timeouts de comando mostra uma forma de adicionar isso.
Processar as chamadas de ferramenta do Claude
Extraia e execute comandos das respostas do 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)
# Um tool_result por bloco tool_use, todos retornados na próxima mensagem do usuário
tool_results.append(
{"type": "tool_result", "tool_use_id": content.id, "content": result}
)Retornar o resultado para o Claude
Envie o tool_result de volta em uma mensagem user que continua a mesma conversa. O Claude solicita outro comando na mesma sessão ou finaliza sua resposta:
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)Repita o ciclo de executar e retornar enquanto stop_reason for tool_use. Para o loop completo, consulte Tratando resultados de ferramentas de cliente.
Implementar medidas de segurança
Adicione validação e restrições. Use uma lista de permissões em vez de uma lista de bloqueios: uma lista de bloqueios deixa passar qualquer comando que não tenha previsto. O exemplo também rejeita operadores de shell que aparecem como palavras separadas:
import shlex
ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}
def validate_command(command):
# Permitir apenas comandos de uma lista de permissões explícita
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"
# Rejeitar operadores de shell escritos como palavras separadas
for token in tokens[1:]:
if token in SHELL_OPERATORS or token.startswith(("$", "`")):
return False, f"Shell operator '{token}' is not allowed"
return True, NoneEssa verificação é um alerta para erros óbvios, não uma barreira de segurança. Ela rejeita o encadeamento com espaços (&&), pipes e redirecionamento que os outros exemplos desta página usam. Ela não detecta um operador colado a uma palavra, como cat data.txt|grep x, porque o tokenizador mantém data.txt|grep dentro de um único token. Decida quais comandos e operadores sua aplicação permite. O controle real é o isolamento: execute toda a sessão dentro de um contêiner ou de uma máquina virtual (consulte Segurança).
Quando um comando falha ou a sessão quebra, informe ao Claude o que aconteceu. Retorne a mensagem como o conteúdo do tool_result e defina is_error como true, o que marca a chamada de ferramenta como falha. Consulte Tratando erros com is_error.
Além do isolamento, adicione estes controles:
ulimit.A definição da ferramenta bash adiciona os seguintes tokens de entrada à sua solicitação. Isso é adicional ao prompt do sistema de uso de ferramentas por modelo que se aplica sempre que qualquer ferramenta está presente.
| Modelo | Tokens de entrada adicionais |
|---|---|
| Claude Opus 5, Claude Opus 4.8 e Claude Opus 4.7 | 325 tokens |
| Claude Opus 4.6, Claude Sonnet 4.6 e anteriores | 244 tokens |
Tokens adicionais são consumidos por:
Consulte preços de uso de ferramentas para obter detalhes completos de preços.
pytest && coverage reportnpm install && npm run buildgit status && git add . && git commit -m "message"Para orientações sobre como usar o git como mecanismo de checkpoint e recuperação em fluxos de trabalho de agentes de longa duração, consulte práticas recomendadas de gerenciamento de estado.
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, prompts de senha ou qualquer comando que espere entrada em stdin.tool_result na próxima requisição.A ferramenta bash combina bem com a Ferramenta de editor de texto: o Claude edita um arquivo com uma ferramenta e solicita o comando que o executa com a outra.
Visualize e modifique arquivos de texto para depurar, corrigir e melhorar código.
Conecte o Claude a ferramentas e APIs externas. Veja onde as ferramentas são executadas, quando o Claude as chama e qual ferramenta se adapta à sua tarefa.
Was this page helpful?