Ir al contenido principal
Español— Elegir un idioma
Menú

Shell: Ejecución de comandos

Lección 18 de 20 Desarrollador
En esta página
  1. Shell: Ejecución de comandos
  2. Concepto y arquitectura
  3. Caso de uso: Diagnóstico del sistema
  4. Asegurar la ejecución
  5. Implementación como función personalizada
  6. Flujos de trabajo de automatización
  7. Puntos clave

Shell: Ejecución de comandos

Esta es la herramienta más potente del curso y la única en la que un error puede volver su potencia contra ti. Otras herramientas leen, calculan o buscan; esta actúa sobre una máquina. Un diagnóstico del sistema mal redactado sigue siendo solo un diagnóstico; un comando de limpieza mal formulado borra archivos.

Esta lección aborda el uso y las salvaguardas conjuntamente porque no pueden separarse. La regla de oro: el modelo nunca debe ejecutar un comando que no hayas autorizado explícitamente con antelación.

Concepto y arquitectura

La diferencia respecto al Intérprete de código es crítica y se resume en una palabra: aislamiento. El Intérprete de código se ejecuta en un entorno aislado de la red y desechable, donde el peor de los casos es un cálculo erróneo. Shell se ejecuta en un entorno que configuras tú —posiblemente tu máquina local, posiblemente un servidor—, donde el peor de los casos es una operación irreversible.

Esta libertad es la razón de ser de la herramienta: sin ella, el despliegue y el mantenimiento automatizados son imposibles. No obstante, exige que elijas conscientemente el ámbito de ejecución. Un contenedor dedicado con privilegios limitados es casi siempre la opción correcta frente al acceso directo al host.

from openai import OpenAI

client = OpenAI()

# La herramienta Shell se usa mediante el SDK de Agents
# porque requiere un entorno de ejecución controlado
from agents import Agent, Runner

agent = Agent(
    name="devops-assistant",
    model="gpt-5.6-terra",
    instructions=(
        "Eres un asistente de DevOps. Ejecutas comandos del sistema "
        "para diagnosticar y resolver problemas de infraestructura. "
        "Explica cada comando antes de ejecutarlo."
    ),
    tools=[{"type": "shell"}]
)

Caso de uso: Diagnóstico del sistema

# El agente puede ejecutar comandos de diagnóstico
agent = Agent(
    name="diagnostic",
    model="gpt-5.6-terra",
    instructions=(
        "Diagnostica el estado del sistema ejecutando los comandos adecuados. "
        "Comienza con comprobaciones básicas (disco, memoria, CPU) "
        "y profundiza según los síntomas."
    ),
    tools=[{"type": "shell"}]
)

# El agente ejecutará comandos como:
# df -h          -> espacio en disco
# free -m        -> memoria
# top -bn1       -> carga de CPU
# systemctl status nginx  -> estado del servicio

Asegurar la ejecución

Tres salvaguardas trabajan conjuntamente y ninguna es suficiente por sí sola. La lista de permitidos (allowlist) es la base: enumeras lo que está permitido en lugar de lo prohibido, porque una lista de bloqueados (blocklist) siempre deja pasar alguna variante, y basta con una para causar daños. Un tiempo de espera (timeout) evita que un comando bloqueado cuelgue el sistema. Un directorio de trabajo restringido limita el daño si un comando legítimo apunta a la ubicación equivocada.

Una cuarta salvaguarda, no técnica pero que vale tanto como las otras tres combinadas: exige confirmación humana para cualquier operación destructiva o irreversible. Un modelo comete errores con la misma confianza con la que acierta.

# Patrón: función contenedora con validación
import subprocess
import shlex

ALLOWED_COMMANDS = {
    "diagnostic": ["df", "free", "top", "uptime", "ps", "netstat", "curl", "ping"],
    "deployment": ["git", "docker", "npm", "pip"],
    "files": ["ls", "cat", "head", "tail", "wc", "grep", "find"],
}

FORBIDDEN_COMMANDS = ["rm", "dd", "mkfs", "shutdown", "reboot", "kill", "passwd"]

def execute_secure_command(command: str, category: str = "diagnostic") -> dict:
    """Ejecuta un comando con validación de seguridad."""
    # Analizar el comando
    parts = shlex.split(command)
    executable = parts[0]

    # Comprobar prohibiciones
    if executable in FORBIDDEN_COMMANDS:
        return {
            "error": f"Comando prohibido: {executable}",
            "reason": "Este comando está en la lista de bloqueados"
        }

    # Comprobar permisos
    allowed = ALLOWED_COMMANDS.get(category, [])
    if executable not in allowed:
        return {
            "error": f"Comando no permitido en la categoría '{category}'",
            "allowed": allowed
        }

    # Ejecutar con tiempo de espera
    try:
        result = subprocess.run(
            parts,
            capture_output=True,
            text=True,
            timeout=30,
            cwd="/tmp"  # Directorio de trabajo restringido
        )
        return {
            "stdout": result.stdout,
            "stderr": result.stderr,
            "return_code": result.returncode
        }
    except subprocess.TimeoutExpired:
        return {"error": "Tiempo de espera agotado: el comando superó los 30 segundos"}

Implementación como función personalizada

Implementar esto tú mismo mediante llamadas a funciones ofrece una ventaja que no debes considerar un plan B: la validación reside en tu código. Tú decides la lista de permitidos, el registro de eventos (logging) y los pasos de confirmación, y puedes auditarlo todo. Para una herramienta con este nivel de riesgo, mantener el control del punto de comprobación es preferible, incluso cuando haya disponible una versión nativa.

tools = [
    {
        "type": "function",
        "name": "execute_command",
        "description": (
            "Ejecuta un comando de shell en el servidor. "
            "Comandos permitidos: diagnóstico del sistema (df, free, top, uptime, ps), "
            "lectura de archivos (ls, cat, head, tail, grep), "
            "red (curl, ping, netstat). "
            "Los comandos destructivos están prohibidos."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "description": "El comando de shell a ejecutar"
                },
                "directory": {
                    "type": "string",
                    "description": "Directorio de trabajo (predeterminado: /tmp)"
                }
            },
            "required": ["command"],
            "additionalProperties": False
        },
        "strict": True
    }
]

import json

def handle_calls(response):
    results = []
    for item in response.output:
        if item.type == "function_call" and item.name == "execute_command":
            args = json.loads(item.arguments)
            result = execute_secure_command(
                args["command"],
                category="diagnostic"
            )
            results.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result)
            })
    return results

# Bucle completo
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Comprueba el espacio en disco y la memoria disponible",
    tools=tools
)

results = handle_calls(response)
final_response = client.responses.create(
    model="gpt-5.6-terra",
    input=response.output + results,
    tools=tools
)
print(final_response.output_text)

Flujos de trabajo de automatización

Despliegue automatizado

El despliegue es el caso de uso más valioso, siempre que entiendas qué estás delegando. El modelo no inventa el procedimiento: encadena pasos que tú has definido, verifica las salidas intermedias y se detiene ante cualquier anomalía. Es un operador atento, no un tomador de decisiones.

tools_deploy = [
    {
        "type": "function",
        "name": "execute_deploy_step",
        "description": (
            "Ejecuta un paso de despliegue. "
            "Pasos posibles: git_pull, tests, build, deploy, rollback. "
            "Cada paso se valida antes de pasar al siguiente."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "step": {
                    "type": "string",
                    "enum": ["git_pull", "tests", "build", "deploy", "rollback"]
                },
                "parameters": {
                    "type": "object",
                    "properties": {
                        "branch": {"type": "string"},
                        "environment": {"type": "string", "enum": ["staging", "production"]}
                    }
                }
            },
            "required": ["step"],
            "additionalProperties": False
        },
        "strict": True
    }
]

def execute_step(step: str, params: dict) -> dict:
    scripts = {
        "git_pull": "cd /app && git pull origin {branch}",
        "tests": "cd /app && npm test",
        "build": "cd /app && npm run build",
        "deploy": "cd /app && ./deploy.sh {environment}",
        "rollback": "cd /app && ./rollback.sh {environment}"
    }
    command = scripts[step].format(**params)
    return execute_secure_command(command, "deployment")

Monitorización y alertas

La monitorización invierte la lógica del resto de esta lección: los comandos aquí son de solo lectura, por lo que son inofensivos, y el valor reside en la interpretación. Un modelo que lee el espacio en disco, la carga y los registros de errores detecta correlaciones que un umbral aislado pasa por alto, lo que convierte a esta en la puerta de entrada más segura para empezar a usar esta herramienta.

def check_system_health() -> dict:
    """Comprueba el estado del sistema y devuelve un informe."""
    checks = {}

    # Espacio en disco
    r = execute_secure_command("df -h /", "diagnostic")
    checks["disk"] = r

    # Memoria
    r = execute_secure_command("free -m", "diagnostic")
    checks["memory"] = r

    # Servicios
    for service in ["nginx", "postgresql", "redis"]:
        r = execute_secure_command(
            f"systemctl is-active {service}",
            "diagnostic"
        )
        checks[f"service_{service}"] = r

    return checks

# La IA analiza los resultados y sugiere acciones
response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Analiza este informe de estado del sistema e identifica problemas:\n"
          f"{json.dumps(check_system_health(), indent=2)}",
    tools=tools
)

Puntos clave

  • La herramienta Shell conecta el modelo con tu infraestructura
  • Implementa listas de permitidos y de bloqueados para los comandos
  • Usa tiempos de espera y directorios de trabajo restringidos
  • Las llamadas a funciones te permiten implementar Shell como una herramienta personalizada
  • Combina Shell con otras herramientas para flujos de trabajo completos de DevOps