Tutorial 25: Execução de Código | Easy Understand Hermes Agent

Esta é parte da série oficial de tutoriais do Hermes Agent. Ver todos os tutoriais

Imagine que você está assando um bolo e, em vez de buscar os ingredientes um a um, você anota a receita inteira, entrega para um ajudante, e ele traz de volta apenas o bolo pronto. É exatamente isso que a Execução de Código faz pelo Hermes Agent — ela permite que o agente execute um script Python completo que chama várias ferramentas internamente e retorna apenas o resultado final para a conversa.

O Que é Execução de Código?

Normalmente, quando o Hermes precisa pesquisar na web, ler um arquivo ou executar um comando, ele faz cada etapa uma de cada vez — e cada resultado intermediário é carregado na sua “memória” (a janela de contexto). Isso é lento e gasta muitos tokens.

Com a ferramenta execute_code, o Hermes escreve um script Python que pode chamar ferramentas programaticamente — como web_search, read_file ou patch — tudo de uma vez. O script roda em um processo filho separado, e apenas a saída do print() volta para o agente. Todos os dados intermediários bagunçados ficam ocultos.

Como Funciona: Passo a Passo

Passo 1: O agente escreve um script Python
Ele começa importando ferramentas de um módulo especial:

from hermes_tools import web_search, web_extract

Passo 2: O Hermes cria um módulo auxiliar
Ele gera automaticamente um stub hermes_tools.py que conecta seu script ao agente principal.

Passo 3: Um canal de comunicação é aberto
O Hermes abre um socket de domínio Unix (uma “linha telefônica” local e rápida entre processos) e inicia uma thread de escuta.

Passo 4: O script roda em um processo filho
Cada chamada de ferramenta dentro do seu script viaja por esse socket de volta para o Hermes, que a executa e envia o resultado de volta.

Passo 5: Apenas a saída do print retorna
As declarações print() do script são a única coisa que o LLM vê. Todos os resultados intermediários das ferramentas nunca entram na janela de contexto — economizando uma quantidade massiva de tokens.

Quando o Hermes Usa Isso?

O agente escolhe automaticamente o execute_code quando detecta:

3 ou mais chamadas de ferramentas com lógica entre elas (como filtrar ou comparar)
Processamento de dados em massa — por exemplo, pesquisar muitos arquivos e extrair trechos
Loops — repetir uma ação em muitos itens

A grande vantagem? Eficiência de tokens. Em vez de alimentar cada resultado de pesquisa de volta na conversa, apenas o resumo final passa.

Exemplos Práticos Que Você Pode Testar

1. Pipeline de Processamento de Dados

from hermes_tools import search_files, read_file
import json

# Encontra todos os arquivos de configuração e extrai as configurações do banco de dados
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. Pesquisa Web em Múltiplas Etapas

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. Refatoração de Arquivos em Massa

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 de Build e Testes

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

Pontos-Chave Para Lembrar

Ferramentas disponíveis dentro dos scripts: web_search, web_extract, read_file, write_file, search_files, patch e terminal (apenas em primeiro plano).
Apenas a saída do print() retorna — todo o resto permanece oculto.
Ótimo para loops, filtragem e fluxos de trabalho em múltiplas etapas — é como dar ao Hermes um mini-ambiente de programação.

Resumo

A Execução de Código transforma o Hermes de um assistente passo a passo em um processador em lote. Ele escreve um script, executa e retorna apenas a resposta final — economizando tempo, tokens e esforço mental. Se você vir o Hermes fazendo muitas chamadas de ferramentas repetitivas, provavelmente ele está usando esse recurso nos bastidores.