MensajesHerramientas

Herramienta Bash

Esta función es elegible para Zero Data Retention (ZDR). Cuando tu organización tiene un acuerdo de ZDR, los datos enviados a través de esta función no se almacenan después de que se devuelve la respuesta de la API.

La herramienta bash permite a Claude ejecutar comandos de shell en una sesión de bash persistente, lo que posibilita operaciones del sistema, ejecución de scripts y automatización desde la línea de comandos. El acceso al shell es una capacidad fundamental de los agentes. En Terminal-Bench 2.0, un benchmark que evalúa tareas reales de terminal usando validación exclusivamente de shell, Claude muestra mejoras significativas de rendimiento cuando tiene acceso a una sesión de bash persistente.

Descripción general

La herramienta bash proporciona a Claude:

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

Para ver la compatibilidad con 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 de entornos: Instalar paquetes, configurar entornos

Inicio rápido

import anthropic

client = anthropic.Anthropic()

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

print(response)

Cómo funciona

La herramienta bash mantiene una sesión persistente:

Claude determina qué comando ejecutar
Tú ejecutas el comando en un shell de 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	Obligatorio	Descripción
`command`	Sí*	El comando de bash a ejecutar
`restart`	No	Establécelo en `true` para reiniciar la sesión de bash

*Obligatorio a menos que se use restart

Ejemplo: Automatización de múltiples pasos

Claude puede encadenar comandos para completar tareas complejas:

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

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.

Configura un entorno de bash

Crea una sesión de 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()

Gestiona la ejecución de comandos

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

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

    # Captura la salida con tiempo de espera
    output = self._read_output(timeout=10)
    return output

Procesa las llamadas a herramientas de Claude

Extrae y ejecuta los 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)

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

Implementa medidas de seguridad

Agrega validación y restricciones. Usa una lista de permitidos (allowlist) en lugar de una lista de bloqueados (blocklist), ya que las listas de bloqueados son fáciles de eludir. Rechaza los operadores de shell para que los comandos encadenados no puedan saltarse 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 los comandos validados con shell=False y pasa shlex.split(command) como lista de argumentos, de modo que el shell nunca interprete la cadena.

Gestionar errores

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

Sigue las mejores prácticas de implementación

Seguridad

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

Ejecución en entornos aislados (Docker/VM)
Implementación de filtrado de comandos y listas de permitidos
Establecimiento de límites de recursos (CPU, memoria, disco)
Registro de 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

La herramienta bash agrega 245 tokens de entrada a tus llamadas a la API.

Se consumen tokens adicionales por:

Salidas de comandos (stdout/stderr)
Mensajes de error
Contenidos de archivos grandes

Consulta precios del uso de herramientas para obtener detalles completos sobre los 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"

Puntos de control basados 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:

Captura una línea base: Antes de que comience cualquier trabajo del agente, haz commit del estado actual. Este es el punto de partida conocido y correcto.
Haz commit por cada funcionalidad: Cada funcionalidad completada recibe su propio commit. Estos sirven como puntos de reversión si algo sale mal más adelante.
Reconstruye el estado al inicio de la sesión: Lee git log junto con un archivo de progreso para entender qué se ha hecho ya y qué viene después.
Revierte en caso de fallo: Si el trabajo se desvía, git checkout revierte al último commit correcto en lugar de intentar depurar un estado roto.

Operaciones con archivos

Procesar datos: wc -l *.csv && ls -lh *.csv
Buscar 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 ni solicitudes de contraseña
Sin aplicaciones GUI: Solo línea de comandos
Alcance de la sesión: El estado de la sesión de bash está del lado del cliente. La API no tiene 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 completarse

Combinación con otras herramientas

La herramienta bash es más potente 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 de bash local y el contenedor aislado de Anthropic. El estado no se comparte entre ellos. Consulta Uso de la ejecución de código con otras herramientas de ejecución para obtener orientación sobre cómo indicarle 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

Visualiza y edita archivos de texto con Claude

Was this page helpful?

MensajesHerramientas

Herramienta Bash

Descripción general

La herramienta bash proporciona a Claude:

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

Para ver la compatibilidad con 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 de entornos: Instalar paquetes, configurar entornos

Inicio rápido

import anthropic

client = anthropic.Anthropic()

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

print(response)

Cómo funciona

La herramienta bash mantiene una sesión persistente:

Claude determina qué comando ejecutar
Tú ejecutas el comando en un shell de 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	Obligatorio	Descripción
`command`	Sí*	El comando de bash a ejecutar
`restart`	No	Establécelo en `true` para reiniciar la sesión de bash

*Obligatorio a menos que se use restart

Ejemplo: Automatización de múltiples pasos

Claude puede encadenar comandos para completar tareas complejas:

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

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

Configura un entorno de bash

Crea una sesión de 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()

Gestiona la ejecución de comandos

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

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

    # Captura la salida con tiempo de espera
    output = self._read_output(timeout=10)
    return output

Procesa las llamadas a herramientas de Claude

Extrae y ejecuta los 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)

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

Implementa medidas de seguridad

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

Gestionar errores

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

Sigue las mejores prácticas de implementación

Seguridad

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

Ejecución en entornos aislados (Docker/VM)
Implementación de filtrado de comandos y listas de permitidos
Establecimiento de límites de recursos (CPU, memoria, disco)
Registro de 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

La herramienta bash agrega 245 tokens de entrada a tus llamadas a la API.

Se consumen tokens adicionales por:

Salidas de comandos (stdout/stderr)
Mensajes de error
Contenidos de archivos grandes

Consulta precios del uso de herramientas para obtener detalles completos sobre los 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"

Puntos de control basados 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:

Captura una línea base: Antes de que comience cualquier trabajo del agente, haz commit del estado actual. Este es el punto de partida conocido y correcto.
Haz commit por cada funcionalidad: Cada funcionalidad completada recibe su propio commit. Estos sirven como puntos de reversión si algo sale mal más adelante.
Reconstruye el estado al inicio de la sesión: Lee git log junto con un archivo de progreso para entender qué se ha hecho ya y qué viene después.
Revierte en caso de fallo: Si el trabajo se desvía, git checkout revierte al último commit correcto en lugar de intentar depurar un estado roto.

Operaciones con archivos

Procesar datos: wc -l *.csv && ls -lh *.csv
Buscar 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 ni solicitudes de contraseña
Sin aplicaciones GUI: Solo línea de comandos
Alcance de la sesión: El estado de la sesión de bash está del lado del cliente. La API no tiene 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 completarse

Combinación con otras herramientas

La herramienta bash es más potente 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

Visualiza y edita archivos de texto con Claude

Was this page helpful?

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

Gestionar errores

Tiempo de espera agotado en la ejecución del comando

Comando no encontrado

Permiso denegado

Sigue las mejores prácticas de implementación

Usa tiempos de espera para los comandos

Mantén el estado de la sesión

Gestiona salidas grandes

Registra todos los comandos

Sanea las salidas

Seguridad

Recomendaciones clave

Precios

Patrones comunes

Flujos de trabajo de desarrollo

Puntos de control basados en Git

Operaciones con archivos

Tareas del sistema

Limitaciones

Combinación con otras herramientas

Próximos pasos

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

Gestionar errores

Tiempo de espera agotado en la ejecución del comando

Comando no encontrado

Permiso denegado

Sigue las mejores prácticas de implementación

Usa tiempos de espera para los comandos

Mantén el estado de la sesión

Gestiona salidas grandes

Registra todos los comandos

Sanea las salidas

Seguridad

Recomendaciones clave

Precios

Patrones comunes

Flujos de trabajo de desarrollo

Puntos de control basados en Git

Operaciones con archivos

Tareas del sistema

Limitaciones

Combinación con otras herramientas

Próximos pasos

Descripción general

Casos de uso

Inicio rápido

Cómo funciona

Parámetros

Ejemplo: Automatización de múltiples pasos

Implementar la herramienta bash

Gestionar errores

Sigue las mejores prácticas de implementación

Seguridad

Recomendaciones clave

Precios

Patrones comunes

Flujos de trabajo de desarrollo

Puntos de control basados en Git

Operaciones con archivos

Tareas del sistema

Limitaciones

Combinación con otras herramientas

Próximos pasos

Descripción general

Casos de uso

Inicio rápido

Cómo funciona

Parámetros

Ejemplo: Automatización de múltiples pasos

Implementar la herramienta bash

Gestionar errores

Sigue las mejores prácticas de implementación

Seguridad

Recomendaciones clave

Precios

Patrones comunes

Flujos de trabajo de desarrollo

Puntos de control basados en Git

Operaciones con archivos

Tareas del sistema

Limitaciones

Combinación con otras herramientas

Próximos pasos