Arquitetura no SPEC
Agentes, responsabilidades, ferramentas e fluxos de dados documentados antes de qualquer codigo ser escrito.
ENGENHARIA DE IA
Como produtos de IA sao
construidos em producao.
Agentes, sistemas multi-agente, pipelines, gestao de custo de tokens e observabilidade. A arquitetura real por tras de sistemas de IA que funcionam.
// 01 — Agentes de IA
O que e um agente de IA — e o que nao e.
Um agente de IA e um componente de software com responsabilidade definida, que usa um modelo de linguagem para tomar decisoes dentro de um escopo limitado. Ele nao e um chatbot generico. Ele nao improvisa fora do seu dominio. Ele executa tarefas complexas com entrada e saida estruturadas.
A confusao mais comum e tratar o agente como um executor livre. Na pratica, agentes bem projetados sao orquestradores — eles decidem qual ferramenta acionar, qual sub-agente chamar e quando parar. A execucao real e feita pelas skills e ferramentas acopladas ao agente.
- Responsabilidade unica e escopo documentado no SPEC
- Ferramentas acopladas com contratos de entrada e saida
- Limites de atuacao definidos — nao ha decisao fora do dominio
- Rastreabilidade completa de cada decisao tomada
- Fallback explicito para casos nao cobertos pelo escopo
// Anatomia de um agente
Entrada estruturada (context + task)
↓
Agente orquestrador
↓
Skill A
Skill B
Tool C
↓
Saida validada
Trace log
Fallback handler
// 02 — Sistemas Multi-agente
Times de agentes com responsabilidades claras.
Sistemas complexos exigem mais de um agente. A questao nao e quantos agentes usar — e como definir as responsabilidades de cada um para que o sistema seja previsivel, testavel e governavel.
Em arquiteturas multi-agente bem projetadas, cada agente tem um papel unico. Um agente de planejamento nao executa tarefas. Um agente de execucao nao avalia qualidade. A separacao de responsabilidades e o que torna o sistema manutentavel em producao.
- Agente coordenador (planner) responsavel por decompor a tarefa
- Agentes especialistas com dominio e contexto especifico
- Agente de controle de qualidade revisa saidas antes da entrega
- Comunicacao entre agentes via contratos definidos no SPEC
- Nenhum agente acessa diretamente o banco — tudo via tools
// Sistema multi-agente
Requisicao do usuario
↓
Agente coordenador (Planner)
↓
Agente A
Pesquisa
Pesquisa
Agente B
Analise
Analise
Agente C
Escrita
Escrita
↓
Agente de QA
↓
Saida final entregue
// 03 — AI Pipelines
Fluxos deterministicos com IA no caminho critico.
Nem toda automacao precisa de um agente. Pipelines de IA sao fluxos de dados onde etapas de processamento com LLMs estao encadeadas de forma deterministica. Sao mais previsivos, mais baratos e mais faceis de monitorar do que sistemas totalmente agentivos.
A escolha entre pipeline e agente e uma decisao de arquitetura — nao de tendencia. Usamos pipelines quando o fluxo e conhecido antecipadamente e agentes quando a sequencia de passos precisa ser decidida em tempo de execucao.
- Etapas encadeadas com saida de uma sendo entrada da proxima
- Cada etapa e testavel de forma independente
- Validacao de schema entre etapas evita propagacao de erros
- Retry e fallback configurados por etapa
- Logs estruturados em cada ponto de transicao
// Pipeline de geracao de conteudo
INPUT — brief + parametros
↓
Etapa 1 — Pesquisa (RAG)
↓
Etapa 2 — Geracao (LLM)
↓
Etapa 3 — Validacao de schema
↓
Etapa 4 — Formatacao de saida
↓
OUTPUT — conteudo validado
// 04 — Gestao de Custo de Tokens
Token sem controle e prejuizo em escala.
O custo operacional de um sistema de IA e diretamente proporcional ao volume de tokens processados. Times que nao instrumentam custo desde o inicio descobrem o problema quando a fatura chega — nao quando o sistema e projetado.
Gestao de custo de tokens nao e cortar qualidade — e projetar o sistema para usar o modelo certo, no contexto certo, com o tamanho de janela adequado para cada tarefa.
- Modelo certo para cada tarefa — GPT-4o nao para tudo
- Contexto minimo necessario — sem lixo no prompt
- Cache de respostas para queries repetidas
- Truncamento inteligente de historico de conversacao
- Alertas de threshold antes de estourar orcamento
- Custo por usuario e por feature rastreados separadamente
// Roteamento por complexidade
Tarefa simples (classificacao)
→ Haiku / GPT-4o-mini — ~$0.001 / 1k tokens
Tarefa media (sumarizacao)
→ Sonnet / GPT-4o — ~$0.003 / 1k tokens
Tarefa complexa (raciocinio)
→ Opus / o1 — ~$0.015 / 1k tokens
70%
reducao media de custo com roteamento por complexidade
3x
mais chamadas possiveis com o mesmo orcamento mensal
// 05 — Observabilidade
Voce nao pode controlar o que nao consegue ver.
Sistemas de IA em producao sem observabilidade sao caixas pretas. Quando algo falha — e vai falhar — voce nao sabe em qual etapa, com qual input, com qual modelo, em qual versao de prompt. Observabilidade e a fundacao de qualquer sistema de IA operacionalmente saudavel.
Instrumentamos rastreabilidade desde o inicio do projeto, nao como corretivo. Cada decisao do agente, cada chamada de LLM, cada saida de pipeline deve ter um trace associado com contexto suficiente para reproducao.
- Trace ID em todas as requisicoes — do usuario ate o LLM
- Log estruturado com input, output, modelo e versao de prompt
- Latencia por etapa — nao so tempo total da requisicao
- Taxa de fallback e taxa de erro separadas por agente
- Dashboard de custo real vs. projetado em tempo real
- Alertas configurados antes do limite — nao depois
// Stack de observabilidade
Requisicao entra no sistema
↓ trace_id gerado
Agente / Pipeline processa
↓ cada etapa emite span
LLM call
latencia + tokens
latencia + tokens
Tool call
resultado + erro
resultado + erro
↓ spans coletados
Trace completo armazenado
Langfuse
OpenTelemetry
Datadog
Como o Sagaz aplica
Arquitetura nao e opcional. E o produto.
Cada projeto do Sagaz Lab comeca com o design da arquitetura antes do primeiro commit. Agentes, pipelines, estrategia de tokens e observabilidade sao definidos no SPEC — o artefato tecnico do nosso metodo SDD.
Custo projetado
Estimativa de custo de tokens por feature documentada no PLAN. Nenhum componente vai para producao sem estrategia de custo.
Observabilidade do dia 1
Traces, logs e dashboards configurados na primeira sprint. Nao e corretivo — e parte da arquitetura base.
Proximo passo
Pronto para construir com arquitetura real?
Faca o diagnostico
Mapeie os principais gaps de arquitetura do seu produto de IA atual em menos de 5 minutos.
Receba o plano
Entregamos um plano tecnico com arquitetura, stack recomendada e priorizacao de implementacao.
Execute com suporte
Construimos junto — agentes, pipelines, observabilidade e controle de custo desde o inicio.