03 — Stack Tecnológico Completo

Visão geral

Camada	Tecnologia	Versão	Por quê
Linguagem principal	Python	3.11+	Ecosistema LangChain maduro
Framework de agente	LangChain + LangGraph	latest	Padrão de mercado, controle de fluxo
LLM principal	Claude Sonnet 4.7	api	Qualidade da conversa, PT-BR forte
LLM de volume	Claude Haiku 4.5	api	Custo baixo para tarefas estruturadas
Vector store	Qdrant	1.11+	Multi-tenant nativo via collections
Embeddings	OpenAI text-embedding-3-small	api	Custo baixo, qualidade alta
Cache + memória	Redis	7.4+	Histórico de conversa, fila
Filas	BullMQ	5+	Robusta, integra Redis
Banco relacional	Postgres	16+	Tenants, configurações
Observabilidade	Langfuse	self-hosted	Tracing + eval + annotation
Orquestrador	Docker Compose	-	Simples para começar
Reverse proxy	Caddy	2+	TLS automático, simples
Servidor	Hetzner CPX21	-	Custo-benefício excelente

Mensageria WhatsApp

Evolution API (clientes Kommo)

# Documentação: https://doc.evolution-api.com/
provider: evolution
versao_minima: v2.0
hospedagem: self-hosted (Triadeflow)
custo: gratuita (open-source)

Quando usar: sempre que cliente usa Kommo CRM ou pediu instância dedicada.

Webhook esperado:

{
  "event": "messages.upsert",
  "instance": "tenant_id_aqui",
  "data": {
    "key": { "remoteJid": "5585999...", "id": "..." },
    "message": { "conversation": "texto" },
    "messageTimestamp": 1234567890
  }
}

Stevo (clientes GHL)

# Stevo é integração GHL → WhatsApp via API oficial Meta
provider: stevo
hospedagem: SaaS
custo: variável por mensagem

Quando usar: clientes que usam GoHighLevel.

Webhook esperado:

{
  "type": "InboundMessage",
  "locationId": "ghl_location",
  "contactId": "...",
  "body": "texto",
  "phone": "+5585999..."
}

CRM

Kommo

crm: kommo
auth: OAuth 2.0
docs: https://developers.kommo.com/

Recursos usados:

Criar/atualizar leads
Mover etapa de pipeline
Atualizar campos customizados (BANT, etc)
Adicionar tags
Criar tasks
Buscar histórico

GoHighLevel (GHL)

crm: ghl
auth: API Key (Location)
docs: https://highlevel.stoplight.io/

Recursos usados:

Contacts API
Opportunities API
Custom Fields
Calendars
Workflows trigger

Pagamentos (para agent-vendas, agent-cobranca)

Gateway	Quando usar	API docs
Stripe	SaaS, internacional	stripe.com/docs
Asaas	Brasil, recorrência forte	docs.asaas.com
PagBank	Brasil, varejo	dev.pagbank.uol.com.br
Hotmart	Infoprodutos	api.hotmart.com
Kiwify	Infoprodutos	docs.kiwify.com.br
Iugu	Brasil, B2B	dev.iugu.com

E-commerce (para agent-vendedor-catalogo)

Plataforma	Integração	Status
Shopify	API REST + Webhook	Planejado
Loja Integrada	API	Planejado
Nuvemshop	API	Planejado
Bling	API	Planejado
API customizada	Adapter	Sob demanda

Calendar (para agent-agendamento)

google_calendar:
  auth: Service Account ou OAuth 2.0
  scopes:
    - https://www.googleapis.com/auth/calendar.events

outlook:
  status: futuro

Versões de Python e dependências principais

[project]
requires-python = ">=3.11,<3.13"

dependencies = [
    "langchain>=0.3.0",
    "langgraph>=0.2.0",
    "anthropic>=0.40.0",
    "langfuse>=2.50.0",
    "qdrant-client>=1.11.0",
    "openai>=1.50.0",  # apenas para embeddings
    "redis>=5.1.0",
    "fastapi>=0.115.0",
    "uvicorn>=0.32.0",
    "pydantic>=2.9.0",
    "pyyaml>=6.0",
    "httpx>=0.27.0",
    "python-dotenv>=1.0.0",
    "structlog>=24.4.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-asyncio>=0.24",
    "ruff>=0.7.0",
    "mypy>=1.13",
]

Variáveis de ambiente padrão

Todo agente precisa destas envs (definidas no .env do tenant ou globais):

# === LLM ===
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...                        # apenas embeddings

# === Observabilidade ===
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.triadeflow.com.br

# === Vector Store ===
QDRANT_URL=https://qdrant.triadeflow.com.br
QDRANT_API_KEY=...

# === Redis ===
REDIS_URL=redis://default:senha@redis:6379

# === Postgres ===
DATABASE_URL=postgresql://user:pass@postgres:5432/triadeflow

# === Por tenant (substituir TENANT_ID) ===
MESSAGING_INSTANCE_USA_SALUS=...
MESSAGING_TOKEN_USA_SALUS=...
CRM_API_KEY_USA_SALUS=...
CRM_LOCATION_USA_SALUS=...

# === Notificação ===
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...

Custos estimados de infraestrutura

Item	Custo mensal	Observação
Hetzner CPX21 (4vCPU, 8GB RAM)	€11	Suficiente para 10-15 tenants ativos
Hetzner CPX31 (recomendado)	€19	Mais folga para crescimento
Backup Hetzner	€2	Snapshots semanais
Domínio + DNS	€1	Cloudflare
Anthropic API	variável	~$0.003-0.015 por conversa
OpenAI Embeddings	variável	$0.020 por milhão de tokens
Total fixo aproximado	€20-25/mês	Antes da API

Limites e quotas relevantes

Claude API (Anthropic)

Tier	Tokens/min	Mensagens/dia	Quando atingir
Tier 1	50.000	1.000	Volume baixo
Tier 2	100.000	-	Solicitar upgrade
Tier 3	200.000	-	Volume médio-alto
Tier 4	400.000	-	Volume alto

WhatsApp Business API

Cloud API (Meta): 1.000 conversas/mês grátis. Depois R$ 0,06-0,28 por conversa.
Evolution API: sem custo direto, mas usa WhatsApp Web (limite de instância: 1 número por instância).
Cuidado: evitar bulk messaging não solicitado (banimento do número).

Decisões pendentes

Revisão em 90 dias:

Avaliar se vale migrar Postgres do Docker para Hetzner Managed
Avaliar se vale Hetzner Storage Box para backup do Qdrant
Avaliar suporte a outros modelos (GPT-4, Gemini) via abstração
Avaliar Cloudflare R2 para armazenamento de mídia (áudios WhatsApp)

Atualizações desta página

Data	Mudança	Quem
Mai/2026	Criação inicial	Alex