Tutorial 25: Esecuzione del Codice

Questa parte fa parte della serie di tutorial ufficiali di Hermes Agent. Vedi tutti i tutorial

Immagina di dover preparare una torta: invece di recuperare gli ingredienti uno alla volta, scrivi l’intera ricetta, la consegni a un aiutante, e lui ti riporta solo la torta finita. Questo è esattamente ciò che fa l’Esecuzione del Codice per Hermes Agent: permette all’agente di eseguire un intero script Python che chiama più strumenti al suo interno, per poi restituire alla conversazione solo il risultato finale.

---

Cos’è l’Esecuzione del Codice?

Normalmente, quando Hermes deve cercare sul web, leggere un file o eseguire un comando, fa ogni passaggio uno alla volta — e ogni risultato intermedio viene caricato nella sua “memoria” (la finestra di contesto). Questo è lento e spreca token.

Con lo strumento execute_code, Hermes scrive uno script Python che può chiamare gli strumenti in modo programmatico — come web_search, read_file o patch — tutto in un colpo solo. Lo script viene eseguito in un processo figlio separato, e solo l’output di print() torna all’agente. Tutti i dati intermedi disordinati restano nascosti.

---

Come Funziona: Passo Dopo Passo

Passo 1: L’agente scrive uno script Python
Inizia importando gli strumenti da un modulo speciale:

from hermes_tools import web_search, web_extract

Passo 2: Hermes crea un modulo helper
Genera automaticamente uno stub hermes_tools.py che collega il tuo script all’agente principale.

Passo 3: Si apre un canale di comunicazione
Hermes apre un socket di dominio Unix (una “linea telefonica” locale e veloce tra processi) e avvia un thread in ascolto.

Passo 4: Lo script viene eseguito in un processo figlio
Ogni chiamata a uno strumento all’interno del tuo script viaggia attraverso quel socket fino a Hermes, che la esegue e rimanda indietro il risultato.

Passo 5: Solo l’output di print() torna indietro
Le istruzioni print() dello script sono l’unica cosa che il LLM vede. Tutti i risultati intermedi degli strumenti non entrano mai nella finestra di contesto — risparmiando un’enorme quantità di token.

---

Quando Hermes Usa Questa Funzione?

L’agente sceglie automaticamente execute_code quando individua:

• 3 o più chiamate a strumenti con logica nel mezzo (come filtrare o confrontare)
• Elaborazione di dati in blocco — ad esempio, cercare in molti file ed estrarre snippet
• Cicli — ripetere un’azione su molti elementi

Il grande vantaggio? Efficienza dei token. Invece di riversare ogni risultato di ricerca nella conversazione, solo il riepilogo finale passa.

---

Esempi Pratici da Provare

1. Pipeline di Elaborazione Dati

from hermes_tools import search_files, read_file
import json

# Trova tutti i file di configurazione ed estrai le impostazioni del database
matches = search_files("database", path=".", file_glob="*.yaml", limit=20)
configs = []
for match in matches.get("matches", []):
    content = read_file(match["path"])
    configs.append({"file": match["path"], "preview": content["content"][:200]})

print(json.dumps(configs, indent=2))

2. Ricerca Web in Più Fasi

from hermes_tools import web_search, web_extract
import json

results = web_search("Rust async runtime comparison 2025", limit=5)
summaries = []
for r in results["data"]["web"]:
    page = web_extract([r["url"]])
    for p in page.get("results", []):
        if p.get("content"):
            summaries.append({
                "title": r["title"],
                "url": r["url"],
                "excerpt": p["content"][:500]
            })

print(json.dumps(summaries, indent=2))

3. Refactoring di File in Blocco

from hermes_tools import search_files, read_file, patch

matches = search_files("old_api_call", path="src/", file_glob="*.py")
fixed = 0
for match in matches.get("matches", []):
    result = patch(
        path=match["path"],
        old_string="old_api_call(",
        new_string="new_api_call(",
        replace_all=True
    )
    if "error" not in str(result):
        fixed += 1

print(f"Fixed {fixed} files out of {len(matches.get('matches', []))} matches")

4. Pipeline di Build e Test

from hermes_tools import terminal
import json

result = terminal("cd /project && python -m pytest --tb=short -q 2>&1", timeout=120)
output = result.get("output", "")

passed = output.count(" passed")
failed = output.count(" failed")

print(json.dumps({"passed": passed, "failed": failed}, indent=2))

---

Punti Chiave da Ricordare

• Strumenti disponibili negli script: web_search, web_extract, read_file, write_file, search_files, patch e terminal (solo in primo piano).
• Solo l’output di print() torna indietro — tutto il resto rimane nascosto.
• Ottimo per cicli, filtri e flussi di lavoro multi-fase — è come dare a Hermes un mini-ambiente di programmazione.

---

Riepilogo

L’Esecuzione del Codice trasforma Hermes da assistente passo-passo a processore batch. Scrive uno script, lo esegue e ti dà solo la risposta finale — risparmiando tempo, token e carico mentale. Se vedi Hermes fare molte chiamate a strumenti ripetitive, probabilmente sta usando questa funzione sotto il cofano.

Prossimo passo: Tutorial 26 — Elaborazione Batch: eseguire centinaia di prompt in parallelo.

---