Herramienta bash

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.

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.

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

Versiones de herramientas

Modelo	Versión de Herramienta
Modelos Claude 4 y Sonnet 3.7	bash_20250124
Claude Sonnet 3.5 (obsoleto)	bash_20241022

Claude Sonnet 3.5 (obsoleto) requiere el encabezado beta computer-use-2024-10-22 cuando se usa la herramienta bash.

La herramienta bash está generalmente disponible en los modelos Claude 4 y Sonnet 3.7.

Casos de uso

• Flujos de trabajo de desarrollo: Ejecutar comandos de construcció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

Python

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "bash_20250124",
            "name": "bash"
        }
    ],
    messages=[
        {"role": "user", "content": "Lista todos los archivos Python en el directorio actual."}
    ]
)

Cómo funciona

La herramienta bash mantiene una sesión persistente:

1. Claude determina qué comando ejecutar
2. Ejecutas el comando en un shell bash
3. Devuelves la salida (stdout y stderr) a Claude
4. 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	Establecer en true para reiniciar la sesión bash

*Requerido a menos que se use restart

Ejemplo de uso

// Ejecutar un comando
{
  "command": "ls -la *.py"
}

// Reiniciar la sesión
{
  "restart": true
}

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

# Usos de herramientas de Claude:
# 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.

1. 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()
   

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

3. 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 = "Sesión bash reiniciada"
           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
           }
   

4. Implementar medidas de seguridad

   Añade validación y restricciones:

   def validate_command(command):
       # Bloquear comandos peligrosos
       dangerous_patterns = ['rm -rf /', 'format', ':(){:|:&};:']
       for pattern in dangerous_patterns:
           if pattern in command:
               return False, f"El comando contiene un patrón peligroso: {pattern}"
       
       # Añadir más validación según sea necesario
       return True, None
   

Manejar errores

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

Timeout de ejecución de comando

Si un comando tarda demasiado en ejecutarse:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: El comando agotó el tiempo de espera después de 30 segundos",
      "is_error": true
    }
  ]
}

Comando no encontrado

Si un comando no existe:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: comandoinexistente: comando no encontrado",
      "is_error": true
    }
  ]
}

Permiso denegado

Si hay problemas de permisos:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: /root/archivo-sensible: Permiso denegado",
      "is_error": true
    }
  ]
}

Seguir las mejores prácticas de implementación

Usar timeouts de comandos

Implementa timeouts para prevenir comandos colgados:

def execute_with_timeout(command, timeout=30):
    try:
        result = subprocess.run(
            command, 
            shell=True, 
            capture_output=True, 
            text=True, 
            timeout=timeout
        )
        return result.stdout + result.stderr
    except subprocess.TimeoutExpired:
        return f"El comando agotó el tiempo de espera después de {timeout} segundos"

Mantener el estado de la sesión

Mantén la sesión bash persistente para conservar las variables de entorno y el directorio de trabajo:

# Los comandos ejecutados en la misma sesión mantienen el estado
commands = [
    "cd /tmp",
    "echo 'Hola' > test.txt",
    "cat test.txt"  # Esto funciona porque aún estamos en /tmp
]

Manejar salidas grandes

Trunca salidas muy grandes para prevenir problemas de límite de tokens:

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... Salida truncada ({len(lines)} líneas totales) ..."
    return output

Registrar todos los comandos

Mantén un registro de auditoría de los comandos ejecutados:

import logging

def log_command(command, output, user_id):
    logging.info(f"Usuario {user_id} ejecutó: {command}")
    logging.info(f"Salida: {output[:200]}...")  # Registrar los primeros 200 caracteres

Sanitizar salidas

Elimina información sensible de las salidas de comandos:

def sanitize_output(output):
    # Eliminar posibles secretos o credenciales
    import re
    # Ejemplo: Eliminar credenciales de AWS
    output = re.sub(r'aws_access_key_id\s*=\s*\S+', 'aws_access_key_id=***', output)
    output = re.sub(r'aws_secret_access_key\s*=\s*\S+', 'aws_secret_access_key=***', output)
    return output

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 mínimos de usuario
• 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 detalles completos de precios.

Patrones comunes

Flujos de trabajo de desarrollo

• Ejecutar pruebas: pytest && coverage report
• Construir proyectos: npm install && npm run build
• Operaciones Git: git status && git add . && git commit -m "mensaje"

Operaciones de archivos

• Procesar datos: wc -l *.csv && ls -lh *.csv
• Buscar archivos: find . -name "*.py" | xargs grep "patrón"
• Crear respaldos: 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: Persiste dentro de la conversación, se pierde entre llamadas API
• Límites de salida: Las salidas grandes pueden ser truncadas
• Sin streaming: Los resultados se devuelven después de completarse

Combinar con otras herramientas

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

Próximos pasos

Descripción general del uso de herramientas

Aprende sobre el uso de herramientas con Claude

Herramienta de editor de texto

Ver y editar archivos de texto con Claude