Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Delegação e Trabalho em Paralelo

O Hermes consegue criar agentes filhos isolados para trabalhar em tarefas em paralelo. Cada subagente ganha a própria conversa, a própria sessão de terminal e o próprio conjunto de ferramentas. Só o resumo final volta — as chamadas de ferramenta intermediárias nunca entram na sua janela de contexto.

Para a referência completa do recurso, veja Delegação para subagentes.

Quando delegar​

Bons candidatos à delegação:

  • Subtarefas pesadas em raciocínio (depuração, revisão de código, síntese de pesquisa)
  • Tarefas que inundariam o seu contexto com dados intermediários
  • Frentes de trabalho independentes em paralelo (pesquisar A e B ao mesmo tempo)
  • Tarefas de contexto novo, em que você quer que o agente chegue sem viés

Use outra coisa:

  • Uma chamada de ferramenta só → use a ferramenta direto
  • Trabalho mecânico de vários passos com lógica entre eles → execute_code
  • Tarefas que precisam de interação com você — subagentes não podem usar o clarify
  • Edições rápidas de arquivo → faça você mesmo
  • Trabalho longo e durável que precisa sobreviver ao fechamento da sessão ou ao reinício do processo → cronjob ou terminal(background=True, notify_on_complete=True). A delegação de primeiro nível é assíncrona, mas continua presa ao processo.

Padrão: pesquisa em paralelo​

Pesquise três assuntos ao mesmo tempo e receba resumos estruturados de volta:

Pesquise estes três assuntos em paralelo:
1. Situação atual do WebAssembly fora do navegador
2. Adoção de chips RISC-V em servidores em 2025
3. Aplicações práticas de computação quântica

Foque nos desenvolvimentos recentes e nos principais participantes.

Nos bastidores, o Hermes usa:

delegate_task(tasks=[
    {
        "goal": "Pesquisar WebAssembly fora do navegador em 2025",
        "context": "Foque em: runtimes (Wasmtime, Wasmer), casos de uso em nuvem/borda, avanço do WASI"
    },
    {
        "goal": "Pesquisar a adoção de chips RISC-V em servidores",
        "context": "Foque em: chips de servidor já entregues, provedores de nuvem adotando, ecossistema de software"
    },
    {
        "goal": "Pesquisar aplicações práticas de computação quântica",
        "context": "Foque em: avanços em correção de erro, casos de uso reais, principais empresas"
    }
])

Os três rodam ao mesmo tempo. Cada subagente pesquisa na web por conta própria e devolve um resumo. Aí o agente pai sintetiza tudo num briefing coerente.

Padrão: revisão de código​

Delegue uma revisão de segurança a um subagente de contexto novo, que chega ao código sem ideias preconcebidas:

Revise o módulo de autenticação em src/auth/ em busca de problemas de segurança.
Procure injeção de SQL, falhas na validação de JWT, tratamento de senha
e gerenciamento de sessão. Conserte o que encontrar e rode os testes.

A chave é o campo context — ele precisa trazer tudo de que o subagente vai precisar:

delegate_task(
    goal="Revisar src/auth/ em busca de problemas de segurança e corrigir os que aparecerem",
    context="""Projeto em /home/usuario/webapp. Python 3.11, Flask, PyJWT, bcrypt.
    Arquivos de autenticação: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py
    Comando de teste: pytest tests/auth/ -v
    Foque em: injeção de SQL, validação de JWT, hash de senha, gerenciamento de sessão.
    Conserte o que encontrar e confirme que os testes passam."""
)
O problema do contexto

Os subagentes não sabem absolutamente nada sobre a sua conversa. Eles começam do zero. Se você delegar "conserte o bug que a gente estava discutindo", o subagente não faz ideia de qual bug é. Passe sempre, de forma explícita, os caminhos de arquivo, as mensagens de erro, a estrutura do projeto e as restrições.

Padrão: comparar alternativas​

Avalie várias abordagens para o mesmo problema em paralelo e depois escolha a melhor:

Preciso acrescentar busca em texto completo ao nosso app em Django. Avalie três
abordagens em paralelo:
1. tsvector do PostgreSQL (nativo)
2. Elasticsearch via django-elasticsearch-dsl
3. Meilisearch via meilisearch-python

Para cada uma: complexidade de configuração, capacidade de consulta, exigência de
recursos e custo de manutenção. Compare e recomende uma.

Cada subagente pesquisa uma opção por conta própria. Como estão isolados, não há contaminação cruzada — cada avaliação se sustenta pelos próprios méritos. O agente pai recebe os três resumos e faz a comparação.

Padrão: refatoração em vários arquivos​

Divida uma refatoração grande entre subagentes paralelos, cada um cuidando de uma parte do código:

delegate_task(tasks=[
    {
        "goal": "Refatorar todos os handlers de endpoint da API para usar o novo formato de resposta",
        "context": """Projeto em /home/usuario/api-server.
        Arquivos: src/handlers/users.py, src/handlers/auth.py, src/handlers/billing.py
        Formato antigo: return {"data": result, "status": "ok"}
        Formato novo: return APIResponse(data=result, status=200).to_dict()
        Import: from src.responses import APIResponse
        Rode os testes depois: pytest tests/handlers/ -v"""
    },
    {
        "goal": "Atualizar todos os métodos do SDK cliente para lidar com o novo formato de resposta",
        "context": """Projeto em /home/usuario/api-server.
        Arquivos: sdk/python/client.py, sdk/python/models.py
        Parsing antigo: result = response.json()["data"]
        Parsing novo: result = response.json()["data"] (mesma chave, mas confira o código de status)
        Atualize também sdk/python/tests/test_client.py"""
    },
    {
        "goal": "Atualizar a documentação da API refletindo o novo formato de resposta",
        "context": """Projeto em /home/usuario/api-server.
        Documentos em: docs/api/. Formato: Markdown com exemplos de código.
        Atualize todos os exemplos de resposta do formato antigo para o novo.
        Acrescente uma seção 'Formato de Resposta' em docs/api/overview.md explicando o schema."""
    }
])
dica

Cada subagente ganha a própria sessão de terminal. Eles conseguem trabalhar no mesmo diretório de projeto sem pisar no pé um do outro — desde que estejam editando arquivos diferentes. Se dois subagentes puderem mexer no mesmo arquivo, cuide desse arquivo você mesmo depois que o trabalho paralelo terminar.

Padrão: coletar e depois analisar​

Use o execute_code para a coleta mecânica de dados e depois delegue a análise pesada em raciocínio:

# Passo 1: coleta mecânica (execute_code é melhor aqui — não precisa raciocinar)
execute_code("""
from hermes_tools import web_search, web_extract

results = []
for query in ["AI funding Q1 2026", "AI startup acquisitions 2026", "AI IPOs 2026"]:
    r = web_search(query, limit=5)
    for item in r["data"]["web"]:
        results.append({"title": item["title"], "url": item["url"], "desc": item["description"]})

# Extrai o conteúdo completo dos 5 mais relevantes
urls = [r["url"] for r in results[:5]]
content = web_extract(urls)

# Salva para o passo de análise
import json
with open("/tmp/ai-funding-data.json", "w") as f:
    json.dump({"search_results": results, "extracted": content["results"]}, f)
print(f"Coletados {len(results)} resultados, extraídas {len(content['results'])} páginas")
""")

# Passo 2: análise pesada em raciocínio (aqui a delegação é melhor)
delegate_task(
    goal="Analisar os dados de financiamento em IA e escrever um relatório de mercado",
    context="""Os dados crus em /tmp/ai-funding-data.json trazem resultados de busca e
    páginas web extraídas sobre financiamento, aquisições e IPOs em IA no 1º trimestre de 2026.
    Escreva um relatório de mercado estruturado: principais negócios, tendências, participantes
    notáveis e perspectivas. Foque em negócios acima de US$ 100 milhões."""
)

Este costuma ser o padrão mais eficiente: o execute_code dá conta das 10 ou mais chamadas sequenciais de ferramenta barato, e depois um subagente faz a única tarefa cara de raciocínio com um contexto limpo.

Acesso herdado a ferramentas​

Os subagentes herdam os conjuntos de ferramentas ligados no pai. O delegate_task não aceita um parâmetro toolsets exposto ao modelo, então o trabalho delegado não consegue se conceder capacidades que o pai não tem. Configure as ferramentas do pai antes de começar a conversa quando uma tarefa delegada precisar de acesso à web, ao terminal, a arquivos ou a qualquer outra coisa. O Hermes ainda remove as ferramentas bloqueadas para filhos, como clarify, memory e send_message; os filhos ficam com o execute_code para chamar ferramentas programaticamente.

Restrições​

  • 3 tarefas paralelas por padrão: os lotes usam 3 subagentes simultâneos por padrão (configurável por delegation.max_concurrent_children no config.yaml, sem teto rígido, só um piso de 1)
  • Delegação aninhada é opcional: subagentes folha (o padrão) não podem chamar delegate_task, clarify, memory nem execute_code. Subagentes orquestradores (role="orchestrator") mantêm o delegate_task para delegar de novo, mas só quando delegation.max_spawn_depth sobe acima do padrão de 1 (piso 1, sem teto); os outros três continuam bloqueados. Desligue globalmente com delegation.orchestrator_enabled: false.

Ajustar simultaneidade e profundidade​

ConfiguraçãoPadrãoFaixaEfeito
max_concurrent_children3>=1Tamanho do lote paralelo por chamada de delegate_task
max_spawn_depth1>=1Quantos níveis de delegação podem criar novos filhos

Exemplo: rodar 30 workers em paralelo com subagentes aninhados:

delegation:
  max_concurrent_children: 30
  max_spawn_depth: 2
  • Terminais separados — cada subagente ganha a própria sessão de terminal, com diretório de trabalho e estado próprios
  • Sem histórico da conversa — os subagentes veem só o goal e o context que o agente pai passa ao chamar o delegate_task
  • 50 iterações por padrão — baixe o max_iterations em tarefas simples para economizar
  • Não é durável — a delegação de primeiro nível roda em segundo plano e devolve o resultado depois, mas continua atrelada à sessão dona e ao processo do Hermes. Fechar a sessão, /stop, /new ou reiniciar o processo pode cancelar ou abandonar o trabalho em andamento. Use cronjob ou terminal(background=True, notify_on_complete=True) para trabalho que precisa passar por essas fronteiras.

Dicas​

Seja específico nas metas. "Conserte o bug" é vago demais. "Conserte o TypeError em api/handlers.py, linha 47, onde process_request() recebe None de parse_body()" dá ao subagente material suficiente.

Inclua os caminhos de arquivo. Os subagentes não conhecem a estrutura do seu projeto. Passe sempre os caminhos absolutos dos arquivos relevantes, a raiz do projeto e o comando de teste.

Use a delegação para isolar contexto. Às vezes você quer uma perspectiva nova. Delegar obriga você a formular o problema com clareza, e o subagente chega nele sem as suposições que se acumularam na sua conversa.

Confira os resultados. Os resumos dos subagentes são só isso — resumos. Se um subagente diz "consertei o bug e os testes passam", verifique rodando os testes você mesmo ou lendo o diff.

Para a referência completa de delegação — todos os parâmetros, integração com ACP e configuração avançada — veja Delegação para subagentes.