Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Shell: Vykonávanie príkazov

Lekcia 18 z 20 Vývojár
Na tejto strane
  1. Shell: Vykonávanie príkazov
  2. Koncept a architektúra
  3. Prípad použitia: Systémová diagnóza
  4. Zabezpečenie vykonávania
  5. Implementácia ako vlastná funkcia
  6. Automatizačné pracovné postupy
  7. Kľúčové poznatky

Shell: Vykonávanie príkazov

Toto je najmocnejší nástroj v tomto kurze a zároveň jediný, kde sa chyba môže obrátiť proti tebe. Ostatné nástroje čítajú, počítajú alebo vyhľadávajú; tento koná na stroji. Zle formulovaná systémová diagnóza zostáva len diagnózou; zle formulovaný príkaz na upratanie však vymaže súbory.

Táto lekcia pokrýva použitie aj ochranné mechanizmy spoločne, pretože ich nemožno oddeliť. Zlaté pravidlo znie: model nikdy nesmie vykonať príkaz, ktorý si vopred výslovne nepovolil.

Koncept a architektúra

Rozdiel oproti Code Interpreter je kľúčový a dá sa vyjadriť jedným slovom: izolácia. Code Interpreter beží v jednorazovom pieskovisku izolovanom od siete, kde je najhorším scenárom zlý výpočet. Shell beží v prostredí, ktoré konfiguruješ ty – potenciálne na tvojom lokálnom stroji, potenciálne na serveri – kde je najhorším scenárom nevratná operácia.

Táto sloboda je pointou: bez nej je automatizované nasadzovanie a údržba nemožná. Vyžaduje si to však, aby si si vedome zvolil rozsah vykonávania. Vyhradený kontajner s obmedzenými právami je takmer vždy lepšou voľbou než priamy prístup k hostiteľovi.

from openai import OpenAI

client = OpenAI()

# The Shell tool is used via the Agents SDK
# because it requires a controlled execution environment
from agents import Agent, Runner

agent = Agent(
    name="devops-assistant",
    model="gpt-5.6-terra",
    instructions=(
        "You are a DevOps assistant. You execute system commands "
        "to diagnose and resolve infrastructure issues. "
        "Explain each command before executing it."
    ),
    tools=[{"type": "shell"}]
)

Prípad použitia: Systémová diagnóza

# The agent can execute diagnostic commands
agent = Agent(
    name="diagnostic",
    model="gpt-5.6-terra",
    instructions=(
        "Diagnose the system state by executing appropriate commands. "
        "Start with basic checks (disk, memory, CPU) "
        "then dig deeper based on symptoms."
    ),
    tools=[{"type": "shell"}]
)

# The agent will execute commands like:
# df -h          -> disk space
# free -m        -> memory
# top -bn1       -> CPU load
# systemctl status nginx  -> service status

Zabezpečenie vykonávania

Spoločne fungujú tri ochranné mechanizmy a žiadny z nich sám o sebe nestačí. Základom je allowlist (zoznam povolených): vymenuješ, čo je povolené, namiesto toho, čo je zakázané, pretože blocklist (zoznam zakázaných) vždy prehliadne nejakú variantu – a stačí jedna jediná. Časový limit (timeout) zabráni tomu, aby zaseknutý príkaz zastavil systém. Obmedzený pracovný adresár obmedzí škody, ak legitímny príkaz ukazuje na nesprávne miesto.

Štvrtý ochranný mechanizmus nie je technický, ale stojí za všetky ostatné tri dokopy: vyžaduj ľudské potvrdenie pre akúkoľvek deštruktívnu alebo nevratnú operáciu. Model sa mýli s rovnakou istotou, s akou má pravdu.

# Pattern: wrapper function with validation
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:
    """Executes a command with security validation."""
    # Parse the command
    parts = shlex.split(command)
    executable = parts[0]

    # Check prohibitions
    if executable in FORBIDDEN_COMMANDS:
        return {
            "error": f"Forbidden command: {executable}",
            "reason": "This command is on the blocklist"
        }

    # Check permissions
    allowed = ALLOWED_COMMANDS.get(category, [])
    if executable not in allowed:
        return {
            "error": f"Command not allowed in category '{category}'",
            "allowed": allowed
        }

    # Execute with timeout
    try:
        result = subprocess.run(
            parts,
            capture_output=True,
            text=True,
            timeout=30,
            cwd="/tmp"  # Restricted working directory
        )
        return {
            "stdout": result.stdout,
            "stderr": result.stderr,
            "return_code": result.returncode
        }
    except subprocess.TimeoutExpired:
        return {"error": "Timeout: command exceeded 30 seconds"}

Implementácia ako vlastná funkcia

Implementácia tohto riešenia vlastnými silami prostredníctvom volania funkcií (function calling) prináša výhodu, ktorú by si nemal považovať za náhradné riešenie: validácia žije v tvojom kóde. Ty rozhoduješ o allowliste, logovaní a krokoch potvrdenia a môžeš všetko auditovať. Pri nástroji s takouto úrovňou rizika je lepšie udržať si kontrolu nad kontrolným bodom, aj keď sa stane dostupná natívna verzia.

tools = [
    {
        "type": "function",
        "name": "execute_command",
        "description": (
            "Execute a shell command on the server. "
            "Allowed commands: system diagnostics (df, free, top, uptime, ps), "
            "file reading (ls, cat, head, tail, grep), "
            "network (curl, ping, netstat). "
            "Destructive commands are forbidden."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "command": {
                    "type": "string",
                    "description": "The shell command to execute"
                },
                "directory": {
                    "type": "string",
                    "description": "Working directory (default: /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

# Full loop
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Check disk space and available memory",
    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)

Automatizačné pracovné postupy

Automatizované nasadzovanie

Nasadzovanie je najcennejším prípadom použitia, za predpokladu, že rozumieš tomu, čo deleguješ. Model nevymýšľa postup: spája kroky, ktoré si definoval ty, overuje čiastkové výstupy a pri akejkoľvek anomálii sa zastaví. Je to pozorný operátor, nie rozhodovateľ.

tools_deploy = [
    {
        "type": "function",
        "name": "execute_deploy_step",
        "description": (
            "Execute a deployment step. "
            "Possible steps: git_pull, tests, build, deploy, rollback. "
            "Each step is validated before proceeding to the next."
        ),
        "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")

Monitorovanie a alerty

Monitorovanie obracia logiku zvyšku tejto lekcie: príkazy sú tu len na čítanie, takže sú neškodné a hodnota spočíva v interpretácii. Model, ktorý číta využitie disku, záťaž a chybové logy, odhalí korelácie, ktoré izolovaný prahový limit prehliadne – čo z neho robí najbezpečnejší vstupný bod pre začiatok práce s týmto nástrojom.

def check_system_health() -> dict:
    """Checks system health and returns a report."""
    checks = {}

    # Disk space
    r = execute_secure_command("df -h /", "diagnostic")
    checks["disk"] = r

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

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

    return checks

# The AI analyzes the results and suggests actions
response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Analyze this system health report and identify issues:\n"
          f"{json.dumps(check_system_health(), indent=2)}",
    tools=tools
)

Kľúčové poznatky

  • Nástroj Shell prepája model s tvojou infraštruktúrou
  • Implementuj allowlisty a blocklisty pre príkazy
  • Používaj časové limity a obmedzené pracovné adresáre
  • Volanie funkcií ti umožňuje implementovať Shell ako vlastný nástroj
  • Kombinuj Shell s ďalšími nástrojmi pre kompletné DevOps pracovné postupy