Documentação e análise de uma arquitetura multi-agent de IA…
INEMA
sistema:
src/router.ts
src/ollama.ts
src/openrouter.ts
src/codex.ts
src/bot.ts
src/config.ts
Função de cada um:
router.ts⌗
lógica de decisão do agente.
ollama.ts⌗
cliente para comunicação com Ollama.
openrouter.ts⌗
cliente para API OpenRouter.
codex.ts⌗
executa o Codex CLI.
bot.ts⌗
comandos do Telegram.
config.ts⌗
variáveis de ambiente.
8. Pontos fortes dessa arquitetura⌗
1️⃣ Redução de custo⌗
Modelos locais resolvem tarefas simples.
2️⃣ Escalabilidade⌗
Novos agentes podem ser adicionados.
3️⃣ Especialização⌗
Cada modelo faz o que ele faz melhor.
4️⃣ Automação⌗
O usuário não precisa escolher sempre o modelo.
9. Possíveis melhorias (arquitetura avançada)⌗
Esse sistema poderia evoluir com:
Memory layer⌗
Exemplo:
- Redis
- vector DB
- embeddings
para contexto persistente.
Tool registry⌗
Um sistema de ferramentas como:
tool: run_bash
tool: edit_file
tool: deploy_project
Agent planning⌗
Planejamento de tarefas:
planner agent
executor agents
review agent
Arquitetura usada em:
- AutoGPT
- CrewAI
- Devin-like systems
Conclusão⌗
O documento descreve uma arquitetura moderna de agentes de IA baseada em:
- roteamento inteligente
- modelos especializados
- execução local + APIs externas
Resumo da lógica:
Usuário
↓
Telegram Bot
↓
Ollama (router)
↓
decide:
├─ responde
├─ Claude
├─ Codex
└─ OpenRouter
Isso cria um sistema híbrido poderoso e barato.
Análise do plano de arquitetura Multi-Agent⌗
O documento descreve uma arquitetura de sistema com múltiplos agentes de IA, onde diferentes modelos são usados para tarefas diferentes, coordenados por um orquestrador central.
A ideia principal é:
Usar o modelo certo para cada tipo de tarefa, em vez de depender de um único modelo.
Isso melhora custo, velocidade e capacidade.
1. Estrutura geral do sistema⌗
O sistema recebe mensagens (por exemplo do Telegram) e decide qual agente usar.
Fluxo simplificado:
Usuário → Telegram Bot → Orquestrador (Ollama) → Agente correto → resposta
Fluxo descrito no documento:
Telegram msg
|
|-- /claude
|-- /codex
|-- /ollama
|-- /openrouter
|
+-- sem comando → Ollama decide
Ou seja:
- Se o usuário usa um comando, o sistema chama diretamente o agente.
- Se não usa comando, o Ollama decide automaticamente qual agente usar.
2. O papel do Ollama (orquestrador)⌗
O Ollama tem duas funções importantes:
1️⃣ Orquestrador⌗
Ele analisa a mensagem e decide:
- responder sozinho
- chamar outro agente
2️⃣ Agente local⌗
Ele também pode responder diretamente.
Isso reduz custos porque:
- modelos locais são gratuitos
- modelos pagos são usados apenas quando necessário
No fluxo descrito:
Classificação:
1️⃣ Simple
Exemplos:
- perguntas
- conversa
- tradução
→ Ollama responde direto
2️⃣ Code / tools
Exemplos:
- editar arquivos
- executar comandos
- debug
→ envia para:
- Codex
- Claude
3️⃣ Heavy / multi-step
Exemplos:
- refatoração grande
- deploy
- análise complexa
→ envia para Claude
3. Os agentes do sistema⌗
O sistema possui 4 tipos de agentes.
Claude Agent (mais poderoso)⌗
Comando:
/claude [model]
Modelos possíveis:
- opus
- sonnet
- haiku
Capacidades:
- executar bash
- editar arquivos
- web search
- sub-agents
- ferramentas completas
Limitação:
- quota de uso (plano pago).
Codex CLI⌗
Comando:
/codex
Função principal:
programação automática
Ele roda como subprocesso:
codex --full-auto "mensagem"
Capaz de:
- editar arquivos
- executar comandos
- gerar código
Usa:
OPENAI_API_KEY
Ollama (local)⌗
Comando:
/ollama [model]
Modelos possíveis:
- qwen2.5-coder
- llama3
- deepseek-coder
- outros
Características:
✔ roda localmente ✔ custo zero ✔ rápido
Limitação:
- não possui ferramentas de sistema (bash etc).
Mas ele serve como:
- orquestrador
- agente simples
OpenRouter⌗
Comando:
/openrouter [model]
Serve para acessar vários modelos via API:
- DeepSeek
- Mistral
- Claude
- outros
Endpoint:
https://openrouter.ai/api/v1/chat/completions
Vantagem:
- acesso fácil a muitos modelos.
4. Sistema de roteamento (router)⌗
O orquestrador usa um prompt de classificação.
Exemplo do documento:
{"action": "respond", "response": "..."}
ou
{"action": "route", "agent": "claude|codex|openrouter", "instructions": "..."}
Isso significa:
O modelo retorna somente JSON, dizendo:
- responder
- ou enviar para outro agente.
Esse padrão é comum em AI routing architectures.
5. Configuração de modelos⌗
Cada sistema pode trocar de modelo em runtime.
Tabela do documento:
| Sistema | Comando |
|---|---|
| Claude | /claude |
| Ollama | /ollama |
| OpenRouter | /openrouter |
| Codex | /codex |
Também existe:
/models
para ver os modelos ativos.
6. Variáveis de ambiente⌗
O sistema depende de variáveis no .env.
Principais:
TELEGRAM_BOT_TOKEN
ALLOWED_CHAT_ID
OPENAI_API_KEY
OPENROUTER_API_KEY
OLLAMA_MODEL
OLLAMA_ROUTER_MODEL
OLLAMA_URL
Essas variáveis controlam:
- acesso ao Telegram
- chaves de API
- modelo do Ollama
- endpoint do Ollama
7. Estrutura de código do projeto⌗
Arquivos principais do
Assistente MultiAgente via Telegram
1