Contabilizei.CLI — alternativas de escopo para uma CLI/TUI de orquestração de agentes IA

Este post é um caderno de decisão — discuto alternativas de escopo de um projeto interno que estou propondo. Nada de números internos, slides ou dados de cliente. Só a arquitetura, os tradeoffs técnicos e o porquê das escolhas. Existe pra que, quando eu (ou outra pessoa) revisitar daqui a seis meses, a trilha de raciocínio esteja documentada.

Contexto

Trabalho como analista de Novos Negócios na Contabilizei. Boa parte do meu dia é ler material de pesquisa, cruzar com dashboards de produto, e propor ação. Quase tudo isso é trabalho com texto + planilha + agente conversacional. Faz três meses que uso Claude/ChatGPT/Gemini direto, e a fricção é sempre a mesma:

• Cada conversa começa do zero — perde-se o contexto que vive em PDFs e

planilhas;

• O agente não tem acesso aos dados que importam (CRM, BI), só ao texto que

eu colo;

• Não dá pra orquestrar dois ou três agentes especializados em paralelo

("um lê o estudo de mercado, outro filtra leads, outro escreve briefing") sem fazer copy-paste manual entre janelas;

• E o time, quando vê o que eu estou fazendo, pede a mesma análise pra si

— mas a análise mora no meu histórico de chat, não num lugar que eles possam reaproveitar.

A solução natural seria construir uma CLI/TUI corporativa com agentes IA já especializados pro contexto da casa, capaz de ler os dados internos sob política de acesso, e que sirva tanto pro time interno quanto, no futuro, pros clientes finais (PMEs no painel da Contabilizei).

O nome de trabalho é Contabilizei.CLI (no repo: ctbz-agents).

A decisão de construir em vez de comprar tem uma justificativa simples: o estado da arte de orquestração de agentes ainda não estabilizou. Quem constrói agora, escolhe a arquitetura. Quem compra agora, fica preso a abstração de fornecedor antes mesmo do mercado decidir o vencedor.

A parte difícil é definir escopo. É isso que esse post documenta.

As seis bifurcações

1. SaaS web vs CLI/TUI vs extensão de IDE

Três superfícies possíveis. A primeira é uma web app interna estilo "Contabilizei Copilot" rodando no domínio interno. A segunda é uma CLI/TUI Python que vive no terminal de quem trabalha com dados. A terceira é uma extensão pro VS Code/Cursor parecida com Pixel Agents ou Cline — agentes IA visíveis dentro do editor que cada analista já usa.

A web app tem o ROI mais óbvio porque atinge mais gente (não-técnicos inclusos), mas o custo de plataforma é alto (auth, DB, deploy, CI). A extensão de IDE é elegante mas restrita a quem programa — e numa área de Novos Negócios isso é minoria.

A CLI/TUI acaba sendo o ponto ótimo pra MVP: zero infraestrutura, acoplamento mínimo a sistemas internos, mas suficiente pra demonstrar valor real em uma semana. E, crucialmente, ela vira a base headless que um widget web (fase 2) consome via gateway. O caminho da CLI à plataforma cliente é incremental; o caminho da web ao terminal é uma reescrita.

Decisão: CLI/TUI como camada de apresentação do MVP; widget web embedado na plataforma vem depois, consumindo a mesma engine.

2. Hermes Agent (fork) vs Anthropic SDK direto vs build-from-scratch

Três caminhos pra montar o loop de agente.

Hermes Agent (Nous Research) chega com 40+ tools prontas, MCP nativo, subagent delegation, suporte a duzentos modelos via OpenRouter. Em troca, herdo a complexidade de fazer fork pra cima, lidar com versão beta de um projeto novo, e adaptar branding.

Anthropic SDK direto é o caminho mais simples: três páginas de código implementam o tool_use loop (chama API → recebe tool_use → executa → manda tool_result → loop até end_turn). Quase nada do que o Hermes oferece é blocker pra MVP — subagent delegation pode esperar; MCP entra quando os agentes virarem servers independentes (fase 3).

Build-from-scratch num framework como Bubbletea (Go) ou Ink (TS) tira o problema do streaming pra o jeito que o framework faz, mas requer reinventar tool calling do zero.

A diferença prática: com Hermes ou Anthropic SDK direto eu fico em Python, plugando no ecossistema (pandas, pydantic, httpx) que já uso pra análise. Em Go/TS eu ganho UX, mas perco velocidade de iteração.

Decisão: começar com Anthropic SDK direto (cobre 80% do que preciso em uma semana), mantendo a interface engine/bridge.py como camada única — se mais tarde fizer sentido trocar pro Hermes, troco implementação atrás da mesma interface. Caso pessimista: nunca migro e fico no SDK.

3. Funcionários primeiro vs cliente primeiro vs paralelo

Quem é o usuário do MVP?

Funcionários primeiro entrega valor em 12 dias, mensurável, com métrica clara (volume de análises produzidas, tempo poupado). O risco é ficar parado como ferramenta interna, sem virar produto.

Cliente primeiro ataca o posicionamento "Contabilizei é seu parceiro financeiro integrado" — a contabilidade digital começa a vender orquestração de IA pro próprio cliente PME. Upside maior, mas ciclo de validação muito mais longo (UX cliente, compliance, suporte, billing).

Paralelo desde o início quebra um dev sozinho em duas frentes ao mesmo tempo.

Decisão: funcionários primeiro, mas com a engine desenhada para ser consumida por um widget cliente em três meses. Fase 1 é CLI. Fase 2 é o mesmo engine atrás de um gateway HTTP, consumido por um widget React embedado na plataforma do cliente. Fase 3 transforma cada agente em MCP server, hospedável independentemente e consumível por Claude Code/Cursor/Cline (todos os hosts MCP do mercado), incluindo o widget cliente. Fase 4 abre SDK pra parceiros plugarem agentes próprios.

Esse caminho preserva o ROI rápido sem fechar a porta da plataforma cliente.

4. Um agente generalista vs três agentes especializados

A tentação é construir um único "Contabilizei Bot" superpoderoso. A boa prática emergente em 2025-2026 é o contrário: agentes especialistas estreitos, cada um com seu system prompt, seu set de tools, seu modelo afinado.

Quatro motivos:

• Prompts focados são mais baratos (menos tokens de instrução por turn);
• Erros são localizáveis (sei qual agente está alucinando);
• Iteração é independente (mexo no agente de leads sem quebrar o agente

fiscal);

• Permite roteamento por custo (o agente que só lê documento usa Sonnet;

o que escreve análise estratégica usa Opus).

Decisão: três agentes no MVP — um para observatório de marca em LLMs, um para briefing semanal lendo material interno, um para diagnóstico de qualidade de qualificação em um pipeline operacional. Cada um vira um arquivo agents/<nome>.py, registrado num registry global. Adicionar o quarto agente vira tarefa de meia hora.

5. Piloto: vitrine externa vs ataque interno vs widget cliente

Qual problema atacar primeiro pra provar valor?

Vitrine externa — uma sonda semanal que pergunta a Claude/ChatGPT/ Gemini/Perplexity coisas como "qual a melhor contabilidade online pra autônomo?" e mede share-of-voice da marca. Dado existe (a pesquisa pública de consumo mostra que IA virou canal de pesquisa real), métrica é objetiva, e a entrega vira artefato visível (dashboard). Custo baixo (<US$ 20/mês) e zero dependência de sistemas internos.

Ataque interno — um agente que melhora um KPI operacional concreto (qualidade de qualificação de leads, ressuscitar contatos antigos, FUP automático). Impacto financeiro direto, mas precisa de acesso a CRM e gera dependência de aprovação cross-time.

Widget cliente — chat IA no painel do cliente, grounded em dados fiscais do próprio CNPJ. Demonstra a fase 2 já no MVP, mas exige UX de produto, compliance, e um ciclo de validação que não cabe em duas semanas.

Decisão: piloto é o observatório externo. É o caso de uso onde nenhum concorrente está jogando ainda, o dado existe, o custo é mínimo, e o resultado é uma página visual que serve como vitrine pra explicar "isto é o que ferramentas de agentes podem fazer" pra qualquer stakeholder. Os outros dois agentes (briefing + diagnóstico) entram junto pra mostrar a versatilidade do mesmo engine, mas o piloto-âncora é o observatório.

6. MCP-first vs CLI proprietária

Model Context Protocol é o padrão da Anthropic pra agentes consumirem ferramentas externas via servers isolados. Existe a tentação de pular direto pra MCP — cada agente vira um server, e o "host" pode ser Claude Code, Cursor, Cline, ou um widget custom.

A favor: arquitetura limpa, separação de responsabilidades, possibilidade de venda futura dos servers pra parceiros, e o cliente final pode usar qualquer host MCP pra acessar os agentes.

Contra: MCP ainda está em fase de adoção. Hosts MCP têm UX pobre pra quem não é dev. E o overhead de spin-up de servers separados é grande demais pro tempo de MVP.

Decisão: começar com CLI proprietária monolítica (a TUI Textual) que importa os agentes como módulos Python. MCP entra na fase 3 — cada agente é extraído pra um server independente, consumível tanto pela TUI interna quanto pelo widget cliente. A migração de "módulo Python" pra "MCP server" é cirurgicamente pequena se a interface estiver bem desenhada desde o início. O monolítico de hoje é o microsserviço de amanhã.

O que entra no MVP

Doze dias, um dev. Encerrando dia 31/05/2026 com:

• CLI Python instalável (pipx install ctbz-agents).
• TUI Textual com layout de quatro painéis (lista de agentes, chat

streaming, log de tool calls, input com slash commands).

• Tema corporativo aplicado (cores e tipografia da marca).
• Três agentes funcionando ponta-a-ponta.
• Comando passthrough que invoca outras CLIs de IA (Claude Code,

Codex, Gemini CLI) dentro da mesma janela, com chat unificado.

• Persistência local em SQLite.
• Demo gravada (asciinema) pra circular.

O não-objetivo explícito é igualmente importante:

• Sem widget cliente ainda (fase 2).
• Sem MCP server ainda (fase 3).
• Sem dashboard web ainda (gera HTML, mas serve em 127.0.0.1).
• Sem integração com CRM ainda (mock no MVP; gateway real na fase 2).

Stack final

Camada	Escolha	Por quê
Linguagem	Python 3.11	Velocidade de iteração, ecossistema de análise (pandas, pydantic).
Engine	Anthropic SDK direto (tool_use loop)	Simplicidade. Cabe em 3 páginas. Hermes vira upgrade opcional.
TUI	Textual ≥ 0.82 + Rich	Streaming Markdown nativo. CSS via TCSS (branding plug-and-play). Maturo o suficiente pra produção.
CLI	Click 8	Standard. Bem documentado.
Storage	SQLite local	Zero infra. Cabe num arquivo.
Passthrough	pexpect (PTY subprocess)	Permite "Claude Code dentro de Contabilizei.CLI" sem reinventar.
Modelos	Opus default; Haiku pra tools mecânicas; Sonar (Perplexity) pra sondas web	Roteamento por custo.

Roadmap (publicado)

• Fase 1 (maio/2026): CLI interna, 3 agentes, observatório como piloto.
• Fase 2 (junho/2026): widget React embedado na plataforma do cliente,

consumindo a mesma engine via gateway HTTP.

• Fase 3 (jul-ago/2026): cada agente vira MCP server independente,

consumível por Claude Code, Cursor, o widget, ou hosts terceiros.

• Fase 4 (set+/2026): SDK público pra parceiros plugarem agentes

próprios. Marketplace de agentes contábeis.

Por que eu publico isto

Três motivos.

Primeiro: a discussão de escopo é o trabalho mais valioso. O código vai ser reescrito; a decisão de pular MCP no MVP, de não fazer Go quando Python serve, de não tentar widget cliente em dia 1, essas decisões ficam. Documentar agora vale mais que documentar depois.

Segundo: isto é uma aposta sobre o futuro de produtos contábeis. Acredito que daqui a 18 meses todo SaaS contábil sério vai oferecer orquestração de agentes pro cliente. Quem chega primeiro define o formato. Esse post é parte da minha aposta de chegar primeiro.

Terceiro: eu erro melhor em público. Se alguém ler isso e me apontar um furo na argumentação, eu prefiro descobrir antes de ter empurrado o projeto por dois meses. O fórum é o melhor revisor que eu tenho.

Próximo post nesta linha: discussão técnica da arquitetura do agente de observatório, com os 20 prompts curados, a metodologia de scoring, e os custos reais por sweep. Quando o MVP fechar (31/05), publico também o asciinema da demo.