HybridAgent：減少模型 token 用量並提升 LLM 效能

HybridAgent: o agente híbrido que está bombando no Hacker News

Introdução

Você já ficou frustrado ao ver seu custo de tokens disparar enquanto um LLM tenta “pensar” passo a passo? O HybridAgent resolve isso combinando raciocínio simbólico em um espaço latente com geração de texto em linguagem natural. O resultado: menos tokens, planejamento mais robusto e performance que já chamou a atenção da comunidade do Hacker News.

Neste artigo você vai descobrir como o HybridAgent funciona, instalar em poucos minutos (Docker + HuggingFace), rodar dois casos de uso reais (debug de código e planejamento de viagem) e ainda montar um monitoramento de consumo de tokens com alertas Slack. Tudo com exemplos práticos em Python e Node.js.

Nota: Os exemplos foram testados em Ubuntu 22.04 usando o modelo open‑source mistral-7b-instruct da HuggingFace.

1. Como o HybridAgent funciona

1. Espaço latente – Um vetor denso representa conceitos, funções e restrições.
2. Raciocínio simbólico – Algoritmos de busca em grafos, unificação de tipos e resolução de constraints são executados sobre esse vetor, totalmente fora da LLM.
3. Conversão para texto – O resultado simbólico é transformado em um prompt curto que a LLM responde em linguagem natural ou chama APIs externas.

Essa arquitetura corta drasticamente o número de tokens enviados ao modelo porque a maior parte do “pensamento” acontece internamente, na CPU.

2. Instalação rápida (Docker + HuggingFace)

# 1. Clone o repositório
git clone https://github.com/hybridagent/hybridagent.git
cd hybridagent

# 2. Build da imagem Docker (inclui o modelo Mistral)
docker build -t hybridagent:latest .

# 3. Rode o container, expondo a porta 8000
docker run -d -p 8000:8000 \
  -e HF_MODEL=mistral-7b-instruct \
  hybridagent:latest

A API REST do HybridAgent ficará disponível em http://localhost:8000/v1/agent.

3. Tutorial passo a passo

3.1. Endpoint básico

curl -X POST http://localhost:8000/v1/agent \
  -H "Content-Type: application/json" \
  -d '{"task":"qual é a capital da Noruega?"}'

Resposta

{
  "answer": "Oslo",
  "tokens_used": 12
}

3.2. Integração em Python

import requests

url = "http://localhost:8000/v1/agent"
payload = {"task": "gerar lista de compras para um jantar vegano para 4 pessoas"}
r = requests.post(url, json=payload)
print(r.json()["answer"])

3.3. Integração em Node.js

const fetch = require('node-fetch');

(async () => {
  const res = await fetch('http://localhost:8000/v1/agent', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ task: 'qual a melhor rota de carro de São Paulo a Rio de Janeiro?' })
  });
  const data = await res.json();
  console.log(data.answer);
})();

4. Casos de uso práticos

4.1. Debug automático de código (Python)

from hybridagent import Agent

agent = Agent()
code = """
def soma(a, b):
    return a - b   # bug intentional
"""

prompt = f"Encontre e corrija o bug no código abaixo:\n{code}"
result = agent.run(prompt)
print(result["answer"])

Saída esperada

O bug está na operação de subtração. O código corrigido é:

def soma(a, b):
    return a + b

4.2. Planejamento de viagem (Node.js)

const { Agent } = require('hybridagent');

(async () => {
  const agent = new Agent();
  const task = `
    Planeje uma viagem de 5 dias para Lisboa:
    - voos ida/volta em classe econômica
    - 2 hotéis 4★ no centro
    - 3 restaurantes de frutos do mar
    - orçamento máximo de 1500 EUR
  `;
  const plan = await agent.run(task);
  console.log(plan.answer);
})();

Resultado (exemplo resumido)

Dia 1: Chegada, check‑in no Hotel Lisboa Plaza, jantar no Cervejaria Ramiro.
Dia 2: City tour, almoço no Time Out Market, jantar no Sea Me.
...
Custo total estimado: 1.420 EUR.

5. Benchmark de consumo de tokens

A diferença vem do fato de que o HybridAgent resolve a maior parte do problema antes de chamar a LLM.

6. Monitoramento de tokens com alerta Slack

6.1. Wrapper de API (Python)

import time, requests
from prometheus_client import Counter, start_http_server

TOKENS_IN = Counter('hybridagent_tokens_in', 'Tokens de entrada')
TOKENS_OUT = Counter('hybridagent_tokens_out', 'Tokens de saída')

def call_agent(payload):
    r = requests.post('http://localhost:8000/v1/agent', json=payload)
    data = r.json()
    TOKENS_IN.inc(data['tokens_used']['in'])
    TOKENS_OUT.inc(data['tokens_used']['out'])
    return data

6.2. Script de alerta Slack

import os, time, requests
from prometheus_api_client import PrometheusConnect

PROM = PrometheusConnect(url="http://localhost:9090", disable_ssl=True)
SLACK_WEBHOOK = os.getenv("SLACK_WEBHOOK")
LIMIT = 5000  # tokens por hora

def check_and_alert():
    query = 'sum(rate(hybridagent_tokens_out[1h]))'
    result = PROM.custom_query(query=query)
    usage = float(result[0]['value'][1])
    if usage > LIMIT:
        requests.post(SLACK_WEBHOOK, json={"text": f":warning: Consumo de tokens atingiu {usage:.0f} (limite {LIMIT})"})

while True:
    check_and_alert()
    time.sleep(300)  # a cada 5 minutos

7. Checklist de testes e segurança

• [ ] Teste unitário: validar run() com prompts vazios e com entrada mal‑formada.
• [ ] Teste de carga: 100 requisições simultâneas usando locust ou k6.
• [ ] Sanitização: garantir que nenhum prompt seja injetado em comandos de shell.
• [ ] Rate limiting: limitar a 10 requisições por segundo por IP.
• [ ] Auditoria de logs: armazenar task, answer e contagem de tokens em bucket S3 criptografado.

8. Perguntas frequentes

9. Conclusão e recursos adicionais

O HybridAgent demonstra que combinar raciocínio simbólico com LLMs reduz custos, melhora a capacidade de planejamento e mantém a flexibilidade de linguagem natural. Se você está desenvolvendo produtos que exigem múltiplas iterações ou decisões complexas, vale a pena experimentar.

Recursos

- Repositório GitHub: https://github.com/hybridagent/hybridagent

Herramienta mencionada: Groq Cloud