Herramienta bash

Herramienta Bash

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

La herramienta bash permite a Claude ejecutar comandos de shell en una sesión bash persistente, permitiendo operaciones del sistema, ejecución de scripts y automatización de línea de comandos. El acceso a shell es una capacidad fundamental del agente. En Terminal-Bench 2.0, un benchmark que evalúa tareas de terminal del mundo real usando validación solo con shell, Claude muestra ganancias de rendimiento sólidas con acceso a una sesión bash persistente.

Descripción general

La herramienta bash proporciona a Claude:

Sesión bash persistente que mantiene el estado
Capacidad de ejecutar cualquier comando de shell
Acceso a variables de entorno y directorio de trabajo
Capacidades de encadenamiento de comandos y scripting

Para soporte de modelos, consulta la Referencia de herramientas.

Casos de uso

Flujos de trabajo de desarrollo: Ejecutar comandos de compilación, pruebas y herramientas de desarrollo
Automatización del sistema: Ejecutar scripts, gestionar archivos, automatizar tareas
Procesamiento de datos: Procesar archivos, ejecutar scripts de análisis, gestionar conjuntos de datos
Configuración del entorno: Instalar paquetes, configurar entornos

Inicio rápido

Cómo funciona

La herramienta bash mantiene una sesión persistente:

Claude determina qué comando ejecutar
Ejecutas el comando en un shell bash
Devuelves la salida (stdout y stderr) a Claude
El estado de la sesión persiste entre comandos (variables de entorno, directorio de trabajo)

Parámetros

Parámetro	Requerido	Descripción
`command`	Sí*	El comando bash a ejecutar
`restart`	No	Establece en `true` para reiniciar la sesión bash

*Requerido a menos que uses restart

Ejemplo: Automatización de múltiples pasos

Claude puede encadenar comandos para completar tareas complejas:

Solicitud del usuario:
"Instala la biblioteca requests y crea un script Python simple que
obtenga un chiste de una API, luego ejecútalo."

La herramienta de Claude usa:
1. Instalar paquete
   {"command": "pip install requests"}

2. Crear 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. Ejecutar script
   {"command": "python fetch_joke.py"}

La sesión mantiene el estado entre comandos, por lo que los archivos creados en el paso 2 están disponibles en el paso 3.

Implementar la herramienta bash

La herramienta bash se implementa como una herramienta sin esquema. Al usar esta herramienta, no necesitas proporcionar un esquema de entrada como con otras herramientas; el esquema está integrado en el modelo de Claude y no se puede modificar.

Manejar errores

Al implementar la herramienta bash, maneja varios escenarios de error:

Seguir las mejores prácticas de implementación

Seguridad

La herramienta bash proporciona acceso directo al sistema. Implementa estas medidas de seguridad esenciales:

Ejecutar en entornos aislados (Docker/VM)
Implementar filtrado de comandos y listas de permitidos
Establecer límites de recursos (CPU, memoria, disco)
Registrar todos los comandos ejecutados

Recomendaciones clave

Usa ulimit para establecer restricciones de recursos
Filtra comandos peligrosos (sudo, rm -rf, etc.)
Ejecuta con permisos de usuario mínimos
Monitorea y registra toda la ejecución de comandos

Precios

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

Command outputs (stdout/stderr)
Error messages
Large file contents

Consulta precios de uso de herramientas para obtener detalles completos de precios.

Patrones comunes

Flujos de trabajo de desarrollo

Ejecutar pruebas: pytest && coverage report
Compilar proyectos: npm install && npm run build
Operaciones de Git: git status && git add . && git commit -m "message"

Punto de control basado en Git

Git sirve como un mecanismo de recuperación estructurado en flujos de trabajo de agentes de larga duración, no solo como una forma de guardar cambios:

Capturar una línea de base: Antes de que comience cualquier trabajo del agente, confirma el estado actual. Este es el punto de partida conocido y bueno.
Confirmar por característica: Cada característica completada obtiene su propio commit. Estos sirven como puntos de reversión si algo sale mal más tarde.
Reconstruir el estado al inicio de la sesión: Lee git log junto con un archivo de progreso para entender qué ya se ha hecho y qué viene después.
Revertir en caso de fallo: Si el trabajo sale mal, git checkout revierte al último commit bueno en lugar de intentar depurar un estado roto.

Operaciones de archivo

Procesar datos: wc -l *.csv && ls -lh *.csv
Buscar en archivos: find . -name "*.py" | xargs grep "pattern"
Crear copias de seguridad: tar -czf backup.tar.gz ./data

Tareas del sistema

Verificar recursos: df -h && free -m
Gestión de procesos: ps aux | grep python
Configuración del entorno: export PATH=$PATH:/new/path && echo $PATH

Limitaciones

Sin comandos interactivos: No puede manejar vim, less o solicitudes de contraseña
Sin aplicaciones GUI: Solo línea de comandos
Alcance de sesión: El estado de la sesión bash es del lado del cliente. La API es sin estado. Tu aplicación es responsable de mantener la sesión de shell entre turnos.
Límites de salida: Las salidas grandes pueden truncarse
Sin streaming: Los resultados se devuelven después de la finalización

Combinar con otras herramientas

La herramienta bash es más poderosa cuando se combina con el editor de texto y otras herramientas.

Si también estás usando la herramienta de ejecución de código, Claude tiene acceso a dos entornos de ejecución separados: tu sesión bash local y el contenedor sandbox de Anthropic. El estado no se comparte entre ellos. Consulta Usar ejecución de código con otras herramientas de ejecución para obtener orientación sobre cómo indicar a Claude que distinga entre entornos.

Próximos pasos

Descripción general del uso de herramientas

Aprende sobre el uso de herramientas con Claude

Herramienta de editor de texto

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

Configurar un entorno bash

Crea una sesión bash persistente con la que Claude pueda interactuar:

import subprocess
import threading
import queue


class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ["/bin/bash"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0,
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()

Manejar la ejecución de comandos

Crea una función para ejecutar comandos y capturar la salida:

def execute_command(self, command):
    # Enviar comando a bash
    self.process.stdin.write(command + "\n")
    self.process.stdin.flush()

    # Capturar salida con timeout
    output = self._read_output(timeout=10)
    return output

Procesar las llamadas de herramientas de Claude

Extrae y ejecuta comandos de las respuestas de Claude:

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)

        # Devolver resultado a Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

Implementar medidas de seguridad

Agrega validación y restricciones. Usa una lista de permitidos en lugar de una lista de bloqueados, ya que las listas de bloqueados son fáciles de eludir. Rechaza operadores de shell para que los comandos encadenados no puedan pasar desapercibidos por la lista de permitidos:

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # Permitir solo comandos de una lista de permitidos 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"

    # Rechazar operadores de shell que encadenarían comandos adicionales
    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

Esta verificación es una primera línea de defensa. Para un aislamiento más fuerte, ejecuta comandos validados con shell=False y pasa shlex.split(command) como la lista de argumentos, para que el shell nunca interprete la cadena.

Descripción general

Casos de uso

Inicio rápido

Cómo funciona

Parámetros

Ejemplo de uso

Ejemplo: Automatización de múltiples pasos

Implementar la herramienta bash

Manejar errores

Timeout de ejecución de comando

Comando no encontrado

Seguir las mejores prácticas de implementación

Usar timeouts de comando

Seguridad

Recomendaciones clave

Precios

Patrones comunes

Flujos de trabajo de desarrollo

Punto de control basado en Git

Operaciones de archivo

Tareas del sistema

Limitaciones

Combinar con otras herramientas

Próximos pasos

Permiso denegado

Mantener el estado de la sesión

Manejar salidas grandes

Registrar todos los comandos

Desinfectar salidas