⚡ Hermes — Chat agentico multi-agente em Streamlit

Um único assistente que pensa em voz alta, chama tools, gera imagens validadas — e ainda delega missões a uma "Mesa de Reunião" de agentes coordenada por um CEO.

---

📌 Visão geral

Hermes é um app agentico em Streamlit construído sobre dois primitivos de orquestração com LLM:

1. Loop ReAct com function-calling nativo — o agente selecionado raciocina, chamada tools (busca web, gera valida imagem, ler/escrever arquivos, melhorar prompt, criar agentes...) e devolve cada passo (pensamento, tool_call, tool_result, resposta final) num stream transparente exibido ao vivo.
2. Mesa de Reunião (multi-agente ao vivo) — o CEO recebe a missão, planeja, delega sub-tarefas aos agentes laterais, observa balões 🟢🟡🔴 de status, intervém quando um agente fica vermelho (reescreve a tarefa e re-tenta) e ao final consolida um relatório honesto do executivo.

Stack de providers ( divisão de responsabilidade ):

• z.ai ( GLM-5.2 / GLM-5-turbo / GLM-4.6V-flash ) → todo texto, function-calling e vision-judge de imagens.
• OpenAI ( gpt-image-1 ) → somente geração de imagens ( rota principal glm-image na z.ai, fallback OpenAI para acentos perfeitos em PT-BR ).

✨ Destaques

• 7 personas prontas + agentes customizados criados em tempo de execução e persistidos em JSON.
• Vision-judge com gate duro: imagem só "passa" se score ≥ 8 E value_demonstrated E clutter ≤ 6 E texto_com_acento. (tools/image_tool.py:66-99)
• Configuração em 2 camadas: .env imutável ( modelos padrão ) + ActiveConfig mutável persistida em config_local.json ( hot-swap de modelo por tier via UI ou tool definir_modelo ).
• Base de conhecimento curada em knowledge/ injetada no system-prompt do Editor ( núcleo ) + lookup just-in-time via tool ler_conhecimento com whitelist.
• Sandbox de arquivos — todas as tools de arquivo operam só dentro de gerados/ ( path-escape bloqueado e testado ).
• Testes automatizados ( agente, tools, providers, ciclo de meta-agentes ) + live integration test que auto-skippa sem ZAI_API_KEY.

🏢 Mesa de Reunião — como funciona

sequenceDiagram
    actor U as Usuário
    participant CEO as CEO (GLM-5.2)
    participant A as Agentes laterais
    U->>CEO: Missão
    CEO-->>CEO: Decomposição em ≤4 sub-tarefas (JSON)
    loop delegação
        CEO->>A: sub-tarefa (assento OCUPADO 🟡)
        A->>A: loop ReAct (cap=4)
        alt sucesso
            A-->>CEO: resumo (assento LIVRE 🟢)
        else falha
            A-->>CEO: erro (assento ERRO 🔴)
            CEO->>A: _ceo_fix reescreve a tarefa
            A->>A: retry (1×)
        end
    end
    CEO-->>U: _consolidar (síntese honesta, ✅/❌ por agente)

Loading

• 🟢 LIVRE · 🟡 OCUPADO (mostra o que faz) · 🔴 ERRO (falhou/esperando)
• Cada assento é editável em tempo de execução (clique no ✏️ sob o balão).
• Tudo atualiza ao vivo (um evento por rerun do Streamlit) + log da reunião.

👥 Personas incluídas

Agente	persona key	O que faz
Hermes (Geral)	hermes	Assistente agentico principal — pesquisa, escreve, gera imagens, melhora prompts, cria agentes e troca modelos ao vivo
Editor de Posts LinkedIn	editor_linkedin	Pipeline completo: ideias → post denso + humano "pronto pra publicar" + capa validada
Gerador de Imagens	imagens	Gera 2-3 variantes e itera com o juiz GLM-4.6V até score ≥ 8
Crítico de Prompts	critico_prompt	Analisa prompt, mostra score e versão melhorada
Pesquisador	pesquisador	Busca fontes confiáveis (Fowler, Netflix, Uber, Stripe, GitHub, arXiv)
Revisor / Corretor	revisor	Revisa clareza, concisão, voz editorial
Crítico de Entregas (Auto-juiz)	critico_entrega	Pontua entrega contra o pedido (0-10) e reescreve até merecer 8+ — o "eval-driven dev" em agente

🚀 Quick start

git clone https://github.com/PedroMMGomes/hermes-multiagent.git
cd hermes-multiagent
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -r requirements.txt
copy .env.example .env   # edite .env com SUAS chaves
streamlit run app.py

Abre em http://localhost:8501.

Atalho Windows: dê dois cliques em run.bat ( cria venv, instala deps, semeia .env a partir do .env.example e roda o Streamlit ).

Variáveis de ambiente ( .env.example )

Var	Provedor	Uso
ZAI_API_KEY	z.ai	Obrigatória. Texto, function-calling e vision-judge
OPENAI_API_KEY	OpenAI	Opcional. Só fallback de geração de imagem ( gpt-image-1 )
ZAI_CHAT_MODEL, ZAI_CEO_MODEL, ZAI_VISION_MODEL, ZAI_ATENDENTE_MODEL, OPENAI_IMAGE_MODEL	—	Modelos padrão por tier ( trocáveis ao vivo na aba Config )
MAX_ITERATIONS	—	Teto de segurança do loop agentic ( default 8 )

🧪 Testes

pytest -q

A suite unitária cobre: loop ReAct com mocks, registro de tools, sandbox de arquivos, providers ( com e sem chave ), ActiveConfig + ciclo de meta-agentes. O live integration test se auto-skippa sem ZAI_API_KEY.

🗂️ Estrutura

hermes/
  app.py                 # entrada Streamlit (chat · mesa · postagens · agentes · config)
  ui.py                  # CSS de marca + primitivas de UI
  mesa_ui.py             # render ao vivo dos balões da Mesa de Reunião
  postagens_ui.py        # aba do editor de LinkedIn
  agentes_ui.py          # CRUD de personas
  core/
    config.py            # Settings imutável (lê .env)
    active_config.py     # ActiveConfig mutável + persistência (config_local.json)
    providers.py         # ZaiProvider (texto+tools+visão) + OpenAIImageProvider
    agent.py             # loop ReAct com function-calling (gera Steps transparentes)
    mesa.py              # orquestração multi-agente (CEO planeja/delega/intervém/consolida)
    image_provider.py    # router de imagem z.ai vs OpenAI com retry/backoff
  agents/personas.py     # 7 personas + Agent dataclass + AGENTS registry
  tools/                 # buscar_web, ler_url, gerar_imagem, validar_imagem,
                         # ler/escrever/listar arquivos, melhorar_prompt,
                         # ler_conhecimento, definir_modelo, meta_agentes (CRUD)
  knowledge/             # núcleo editorial + 7 posts-exemplo (whitelist)
  gerados/               # sandbox de saídas (imagens, posts, rascunhos)
  tests/                 # pytest (loop, tools, providers, meta-agentes, live)
  .env.example           # template de chaves — éste é o arquivo que se commita
  requirements.txt
  run.bat                # launcher Windows

🛣️ Roadmap

• Suporte a mais providers de imagem ( Stable Diffusion local )
• Memória vetorial longa ( RAG sobre o knowledge/ )
• Exportação do master carousel em PDF
• Streaming incremental do vision-judge

🔒 Segurança

• .env nunca é commitado ( está no .gitignore ). Use .env.example como template e preencha com suas chaves.
• A OpenAI key trafega somente para https://api.openai.com/v1/images/generations. Todo o resto ( chat, tools, visão ) vai pela z.ai.
• O sandbox de arquivos bloqueia qualquer path fora de gerados/.
• Para compartilhar o projeto — zip só o código; nunca inclua .env. Quem receber deve copy .env.example .env e preencher as próprias chaves.

📄 Licença

MIT — use, modifique e distribua livremente. Veja LICENSE.

🙌 Créditos

• z.ai / BigModel (Zhipu) — GLM-5.2, GLM-5-turbo, GLM-4.6V-flash, glm-image
• OpenAI — gpt-image-1
• Streamlit — UI

---

_{Construído por Pedro Gomes — Tech Lead / Product Builder de IA.}