Módulo 1.3 — Glossário e mental model

🤖 Agent vs LLM vs Assistente

Os três termos andam juntos, mas não são sinônimos. Um LLM gera texto; um assistente embrulha um LLM com prompt; um agente vai além — observa, decide, executa ferramentas e mantém estado entre turnos.

💡 Três níveis de capacidade

•LLM: função pura texto → texto. Sem memória, sem ferramentas. Ex.: llama-4-scout, claude-sonnet-4.6.
•Assistente: LLM + system prompt + janela de chat. Lembra dentro da conversa, esquece ao fechar. Ex.: ChatGPT free.
•Agente: assistente + tools + loop de raciocínio + memória persistente. Ex.: Hermes Agent.

Característica	LLM puro	Assistente	Agente (Hermes)
Estado entre turnos	❌	Em uma sessão	Persistente (Honcho)
Executa ações	❌	Limitado	✅ via tools
Decide próximo passo	❌	❌	✅ ReAct loop
Multi-canal	❌	UI única	✅ adapters
Custo típico	Token	Assinatura	Token + infra leve

💡 Dica de leitura

Sempre que alguém disser "agente" mas a coisa não tem memória persistente nem chama ferramentas externas, é só um assistente com nome bonito. Use essa régua antes de comparar produtos.

🛠️ Tool vs Skill — quando usar cada um

A confusão #1 entre iniciantes. Tool é um verbo que o agente pode invocar (uma função). Skill é uma receita que orquestra tools, prompts e regras para resolver uma tarefa repetitiva.

🛠️ Tool

Granularidade: atômica (1 ação)
Exemplo: http.get, fs.read, shell.exec
Quem cria: dev (código Python/JS)
Discovery: registrada no toolset
Reuso: múltiplas skills usam a mesma

📚 Skill

Granularidade: tarefa (N passos)
Exemplo: "publicar release no GitHub"
Quem cria: usuário (markdown + frontmatter)
Discovery: auto-descoberta por descrição
Reuso: compartilhável via agentskills.io

# Tool: definida em Python, registrada no toolset
@tool
def http_get(url: str) -> str:
    """Faz GET HTTP e retorna o body."""
    return requests.get(url).text

# Skill: definida em markdown, descoberta por descrição
---
name: github-release
description: Publica uma release nova no GitHub a partir do CHANGELOG.
tools: [shell.exec, fs.read, http.get]
---
1. Ler CHANGELOG.md
2. Extrair versão da seção topo
3. Rodar: gh release create vX.Y.Z --notes "..."

✓ Quando criar TOOL

✓Precisa acessar API/SDK novo
✓Quer controle de tipos/validação
✓Ação será usada por várias skills
✓Performance importa (sem overhead de LLM)

✓ Quando criar SKILL

✓Orquestra tools existentes
✓É uma rotina/procedimento humano
✓Quer iteração rápida (sem deploy)
✓Vai compartilhar com outros usuários

🔌 MCP vs Tool Gateway — protocolos vs implementação

MCP (Model Context Protocol) é um padrão aberto de comunicação entre agentes e servidores de ferramentas. Tool Gateway é a implementação local do Hermes que fala MCP (e outros protocolos) com o mundo externo.

Aspecto	MCP	Tool Gateway
Natureza	Protocolo (spec)	Processo (binário)
Criador	Anthropic (aberto)	Hermes Agent runtime
Camada	Transporte (JSON-RPC)	Aplicação (multiplexador)
Fala com	Servidor MCP	MCP, REST, gRPC, shell
Onde roda	Qualquer agente compatível	Dentro do Hermes

📊 Por que importa

200+ servidores MCP públicos disponíveis (filesystem, GitHub, Slack, Postgres…)
1 Tool Gateway no Hermes consome qualquer um deles sem código
0 linhas de Python para adicionar uma fonte nova — basta apontar a URL

# config.yaml — Tool Gateway consumindo 3 servidores MCP
tool_gateway:
  mcp_servers:
    - name: filesystem
      command: npx -y @modelcontextprotocol/server-filesystem /workspace
    - name: github
      command: npx -y @modelcontextprotocol/server-github
      env: { GITHUB_TOKEN: "${GITHUB_TOKEN}" }
    - name: postgres
      command: uvx mcp-server-postgres
      env: { DB_URL: "${DATABASE_URL}" }

📡 Gateway vs Channel vs Provider — confusões comuns

Três palavras com "porta" no nome, três camadas diferentes. Provider é de onde vem o cérebro (LLM). Channel é por onde o humano fala. Gateway é por onde o agente acessa o mundo.

🧠 Provider

Backend de LLM. Devolve completion para o agente.

• OpenRouter
• Anthropic direto
• OpenAI direto
• Ollama (local)

📱 Channel

Interface humana. Entrega mensagens em ambos sentidos.

• CLI
• Telegram bot
• Slack adapter
• Discord adapter

🔌 Gateway

Multiplexador de tools. Conecta agente a serviços externos.

• MCP servers
• REST APIs
• Shell local
• Plugins próprios

✓ Mnemônico que funciona

✓Provider = de onde vem a inteligência
✓Channel = por onde entra/sai o humano
✓Gateway = por onde sai/entra o mundo externo
✓Você pode ter N de cada um simultaneamente

✗ Erros típicos

✗"Provider Telegram" — Telegram é channel, não provider
✗"Channel GitHub" — GitHub é gateway/tool, não channel
✗"Gateway Claude" — Claude é provider (modelo)
✗Misturar config de provider com config de gateway no YAML

💾 Session vs Memory vs Context — escopos temporais

A trinca temporal. Context dura uma chamada de LLM. Session dura uma conversa. Memory dura para sempre (ou até você apagar).

Context (segundos)

Janela do modelo na chamada atual. Limitada por max_tokens do provider (128k–1M).

Tudo aqui é enviado a cada turno. Cobra token. Esquece após resposta.

Session (minutos a horas)

Identificador único por conversa (session_id). Acumula histórico de turnos e estado intermediário.

Persiste enquanto o usuário "continuar". Pode ser sumarizado para caber no context.

Memory (dias a anos)

Fatos consolidados via Honcho ou backend de vetor. Sobrevive entre sessões e canais.

Recuperada por busca semântica e injetada no context quando relevante.

💡 Regra de ouro de custo

Context custa token a cada turno. Memory custa storage uma vez. Sempre que algo for usado mais de 3 vezes, mova de context para memory — economia direta na fatura OpenRouter.

🧩 Mental model completo

Junte tudo num diagrama. O Agent Loop no centro orquestra: recebe mensagem do channel, lê memory + session, chama provider, decide tool no gateway, escreve de volta.

┌──────────────┐         ┌──────────────────────────────┐         ┌────────────┐
│   CHANNEL    │ ──msg──▶│         AGENT LOOP           │◀─tool───│  GATEWAY   │
│ (Telegram,   │         │                              │         │ (MCP, REST,│
│  Slack, CLI) │◀─reply──│  ┌────────────────────────┐  │──call──▶│  shell)    │
└──────────────┘         │  │  1. read session       │  │         └─────┬──────┘
                         │  │  2. fetch memory       │  │               │
       ┌─────────────────│  │  3. build context      │  │               ▼
       │                 │  │  4. call provider      │  │      ┌──────────────┐
       ▼                 │  │  5. parse tool calls   │  │      │ External APIs│
┌──────────────┐         │  │  6. execute via gw     │  │      │ (GitHub, DB, │
│   SESSION    │◀────────│  │  7. observe & loop     │  │      │  filesystem) │
│  (in-memory) │         │  └────────────────────────┘  │      └──────────────┘
└──────┬───────┘         └──────┬───────────────────────┘
       │                        │
       ▼                        ▼
┌──────────────┐         ┌──────────────┐
│   MEMORY     │         │   PROVIDER   │
│   (Honcho)   │         │ (OpenRouter, │
│              │         │  Ollama)     │
└──────────────┘         └──────────────┘

🔑 Glossário-relâmpago

Agent: runtime que decide e age em loop.

LLM: função texto→texto (Provider).

Tool: função executável atômica.

Toolset: grupo de tools registradas.

Skill: receita markdown que usa tools.

MCP: protocolo aberto agent↔tools.

Tool Gateway: processo Hermes que fala MCP+REST+shell.

Channel: interface humana (Telegram, CLI).

Provider: origem do LLM (OpenRouter).

Session: conversa com ID e histórico.

Memory: fatos persistentes (Honcho).

Context: tokens enviados ao LLM agora.

⚠️ Falsos amigos — cuidado

• "Memory" do ChatGPT ≠ Memory do Hermes (Honcho é vetor + grafo, não só array de fatos).
• "Plugin" do ChatGPT ≠ Tool do Hermes (plugins usam OpenAPI, tools usam MCP).
• "Skill" da Alexa ≠ Skill do Hermes (Alexa = aplicativo de voz; Hermes = receita textual).
• "Agent" do LangChain ≃ Agent do Hermes, mas Hermes embute memory + channels nativos.

🔗 Referências oficiais

• Docs Hermes: hermes-agent.nousresearch.com/docs
• Repo: github.com/NousResearch/hermes-agent
• Spec MCP: modelcontextprotocol.io

✅ Resumo do Módulo

✓

Agent ≠ LLM ≠ Assistente: só agente tem loop, tools e memory persistente.

✓

Tool é verbo, Skill é receita: tools em código, skills em markdown — tools são reutilizadas por várias skills.

✓

MCP é spec, Tool Gateway é processo: o gateway fala MCP, REST e shell sem você escrever Python.

✓

Provider/Channel/Gateway são três portas distintas: inteligência, humano e mundo externo — nunca confunda.

✓

Context/Session/Memory são três escopos temporais: segundos, horas e anos respectivamente.

✓

Mental model = Agent Loop no centro: orquestra channel ↔ memory ↔ provider ↔ gateway.

Próximo módulo:

Módulo 1.4 — 📈 Estudo de caso real: 30 dias com Hermes. Como ficou na prática para uma pessoa real: custo, skills criadas, lições aprendidas.

← Voltar para Trilha Próximo Módulo →