Salt la conținutul principal
Română— Alege o limbă
Meniu

Shell: Executarea comenzilor

Lecția 18 din 20 Dezvoltator
Pe această pagină
  1. Shell: Executarea comenzilor
  2. Concept și Arhitectură
  3. Caz de utilizare: Diagnosticul sistemului
  4. Securizarea execuției
  5. Implementarea ca funcție personalizată
  6. Fluxuri de lucru automate
  7. Puncte cheie

Shell: Executarea comenzilor

Acesta este cel mai puternic instrument din acest curs și singurul în care o greșeală poate întoarce puterea sa împotriva dumneavoastră. Alte instrumente citesc, calculează sau caută; acesta acționează asupra unei mașini. Un diagnostic de sistem formulat greșit rămâne doar un diagnostic; o comandă de curățare formulată greșit șterge fișiere.

Această lecție acoperă utilizarea și măsurile de siguranță împreună, deoarece ele nu pot fi separate. Regula de aur: modelul nu trebuie niciodată să execute o comandă pe care nu ați autorizat-o explicit în prealabil.

Concept și Arhitectură

Diferența față de Code Interpreter este critică și se rezumă la un singur cuvânt: izolare. Code Interpreter rulează într-un sandbox eliminabil, izolat de rețea, unde scenariul cel mai defavorabil este un calcul eronat. Shell rulează într-un mediu configurat de dumneavoastră – potențial mașina locală, potențial un server – unde scenariul cel mai defavorabil este o operațiune ireversibilă.

Această libertate este scopul: fără ea, implementarea și mentenanța automatizate sunt imposibile. Totuși, aceasta necesită să alegeți conștient domeniul de execuție. Un container dedicat cu privilegii limitate este aproape întotdeauna alegerea corectă în detrimentul accesului direct la gazdă.

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

Caz de utilizare: Diagnosticul sistemului

# 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

Securizarea execuției

Trei măsuri de siguranță funcționează împreună, iar niciuna nu este suficientă de una singură. Lista de permisiuni (allowlist) este fundamentul: enumerați ce este permis, nu ce este interzis, deoarece o listă de blocare (blocklist) ratează întotdeauna o variantă – și este nevoie doar de una singură. Un timeout previne blocarea sistemului de către o comandă blocată. Un director de lucru restricționat limitează daunele dacă o comandă legitimă indică o locație greșită.

O a patra măsură, non-tehnică, dar care valorează cât celelalte trei la un loc: cereți confirmarea umană pentru orice operațiune distructivă sau ireversibilă. Un model face greșeli cu aceeași încredere cu care are dreptate.

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

Implementarea ca funcție personalizată

Implementarea acestui mecanism dumneavoastră înșivă prin apelarea de funcții (function calling) oferă un avantaj pe care nu ar trebui să-l considerați o soluție de rezervă: validarea reside în codul dumneavoastră. Dumneavoastră decideți lista de permisiuni, jurnalizarea (logging) și pașii de confirmare, iar puteți audita totul. Pentru un instrument cu acest nivel de risc, menținerea controlului asupra punctului de verificare este preferabilă, chiar și atunci când o versiune nativă devine disponibilă.

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)

Fluxuri de lucru automate

Implementare automată (Deployment)

Implementarea este cel mai valoros caz de utilizare, cu condiția să înțelegeți ce delegați. Modelul nu inventează procedura: el înlănțuie pași pe care i-ați definit, verifică rezultatele intermediare și se oprește la orice anomalie. Este un operator atent, nu un factor de decizie.

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

Monitorizare și alerte

Monitorizarea inversează logica restului acestei lecții: comenzile de aici sunt doar pentru citire, deci sunt inofensive, iar valoarea constă în interpretare. Un model care citește spațiul pe disc, sarcina procesorului și jurnalele de erori observă corelații pe care un prag izolat le ratează – făcând din aceasta cea mai sigură poartă de intrare pentru a începe cu acest instrument.

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
)

Puncte cheie

  • Instrumentul Shell conectează modelul la infrastructura dumneavoastră
  • Implementați liste de permisiuni (allowlists) și liste de blocare (blocklists) pentru comenzi
  • Utilizați timeout-uri și directoare de lucru restricționate
  • Apelarea de funcții (Function calling) vă permite să implementați Shell ca un instrument personalizat
  • Combinați Shell cu alte instrumente pentru fluxuri de lucru DevOps complete