Arquiteto de Sistemas Orientado a Resultados

Uso OpenRouter (OR) como camada de roteamento, porque é onde fallback e multi-provider ficam triviais.

1. Ingestão (offline). Chunking semântico com metadados (fonte, data, tenant/permissão). Embeddings: escolha um provider e fixe: não troque de modelo de embedding sem reembeddar tudo, vetores ficam incompatíveis. Cada modelo no OR tem tokenizer próprio: use o usage real retornado, não confie num tokenizer único pra todo o catálogo.

2. Retrieval (online). Híbrido (vetorial + BM25) com rerank. O rerank é onde se corta token: só os top-k de verdade entram no prompt. É a maior alavanca de custo: chunk irrelevante é input pago em toda chamada.

3. Orquestração multi-agente. Mapeie papel → modelo e force custo/throughput pelo provider: roteador → gemini-flash ou um :nitro barato com sort: "price"; workers de extração → sonnet/deepseek (custo-benefício); síntese → opus/gpt-4o com sort: "throughput". O OR não tem "subagente com cache compartilhado" da Anthropic; multi-agente aqui é orquestração do seu lado: chamadas paralelas, junção na aplicação.

4. Custo por token. Roteamento por preço (sort: "price"), teto por requisição (max_price), e prompt caching repassado pelo provider: system + docs estáveis no prefixo cacheável, pergunta volátil no fim. Peça usage: { include: true } pra ter custo real e fazer budget por tenant.

5. Fallback (onde o OR brilha). Dois níveis automáticos: entre modelos (models é lista ordenada, cai pro próximo na mesma requisição) e entre provedores do mesmo modelo (allow_fallbacks: true). No Claude direto você coda a cascata na mão e distingue refusal de 529.

Cuidado: ao cair pra outro modelo o cache se perde (é por modelo/provider) e o comportamento muda. Ordene a lista por similaridade de comportamento, não só por preço.

O que governa tudo: caching é prefix match. A chave vem dos bytes exatos do prompt renderizado até cada breakpoint cache_control. Qualquer byte que muda na posição N invalida tudo depois. A ordem de render é tools → system → messages, então um breakpoint no último bloco de system cacheia tools + system juntos.

Como projetar. Estável fisicamente antes do volátil: system congelado e documentos recuperados no prefixo; pergunta da vez, timestamps e IDs no fim. Num RAG isso é a diferença entre pagar 0,1× ou 1× pelos docs em cada chamada.

Economia real. Leitura ~0,1× o input; escrita 1,25× (TTL 5 min, padrão) ou 2× (1h). Break-even: com 5 min, duas requisições já pagam; com 1h, pelo menos três.

Pegadinhas. Máx 4 breakpoints. O prefixo mínimo cacheável depende do modelo: abaixo dele não cacheia, em silêncio (cache_creation_input_tokens: 0): ~4096 tokens em Opus/Haiku, ~1024 a 2048 em Sonnet. Invalidadores que eu caço: datetime.now() ou UUID no system, json.dumps sem sort_keys, tools variando por usuário, trocar de modelo no meio. Confiro com usage.cache_read_input_tokens: se vier zero em prefixos idênticos, tem invalidador escondido.

Ordem default: prompt engineering → RAG → fine-tuning, escalando só quando o anterior comprovadamente não resolve. Menor custo, menor acoplamento, maior reversibilidade.

• Prompt engineering: quando o conhecimento já está no modelo e o problema é de formato, tom ou raciocínio. Iteração em minutos. 70% dos casos morrem aqui.
• RAG: quando o problema é de conhecimento: dados privados, atuais ou grandes demais pro contexto, que mudam com frequência. A fonte da verdade vive fora do modelo: atualizar é reembeddar um documento, não retreinar nada.
• Fine-tuning: último recurso, e quase nunca pra "ensinar fatos" (RAG faz melhor e versionável). Vale pra comportamento consistente que prompt não estabiliza: formato muito específico em altíssimo volume, estilo, ou comprimir instrução longa no peso. Custo: dataset, pipeline e perda de reversibilidade.

Heurística: "é falta de conhecimento ou de comportamento?" Conhecimento → RAG; comportamento → prompt primeiro. O caso mais comum em produção é RAG + prompt bem-feito, sem fine-tuning nenhum.

Regra: não confie em "peça JSON no prompt e dê json.loads". Funciona no happy path e te acorda 3h da manhã quando o modelo abre com "Claro! Aqui está:". Confiabilidade vem de restringir a saída na API, não de pedir educadamente.

Camada 1: restrição nativa. output_config.format com JSON Schema, ou tool use com strict: true (additionalProperties: false + required), que garante que o tool_use.input valida exato. Pra classificação, tool com enum dos rótulos é mais robusto que pedir rótulo em texto. SDKs dão validação tipada (Pydantic, Zod).

Camada 2: parsing defensivo. Mesmo com schema, sempre json.loads()/JSON.parse(); nunca regex na string serializada. Modelos diferentes escapam Unicode e barras de formas diferentes.

Camada 3: modos de falha restantes. Se stop_reason é max_tokens o JSON vem truncado; se é refusal pode não bater com o schema. Então: schema estrito + parse defensivo + checagem de stop_reason antes de tratar como válido. Três camadas, porque cada uma cobre um modo de falha diferente.

Encadear é pipeline linear: saída de A vira entrada de B, fluxo fixo. StateGraph é máquina de estados: nós que leem/escrevem num estado compartilhado (AgentState, inspecionável em qualquer ponto), com arestas condicionais que decidem o próximo nó em runtime, incluindo ciclos. A diferença é a capacidade de loop, branch e retomada com estado explícito.

No meu lab (agentes-langchain-lab) o grafo é researcher → writer: o researcher é um agente ReAct com a tool search_docs fazendo RAG, e repete pensa→busca→observa até ter evidência; isso é um ciclo, não dá pra expressar limpo numa cadeia. O writer só entra quando o estado tem evidência.

Quando NÃO se paga: fluxo determinístico e linear (extrai → transforma → resume). StateGraph aí é over-engineering; três await são mais legíveis e baratos. Trazer o framework só porque "é multiagente" é o erro mais comum.

Quando SE paga: ciclos com parada decidida em runtime, branching real, estado compartilhado entre nós heterogêneos, ou checkpoint/retomada de execuções longas. Resumindo: encadeie quando o fluxo é fixo; use grafo quando o próprio fluxo é decisão do modelo.

Insight central: o gargalo de custo em assistência multi-repo não é o que o modelo gera, é o que fica sempre carregado no contexto (regras, comandos, skills, CLAUDE.md), multiplicado por toda interação. Numa tarefa representativa eram 377K tokens; caiu pra 28K (~68% num time de 6).

Estratégia "slim rule + skill sob demanda": separar o que precisa estar sempre presente do que só importa quando a tarefa pede. A regra slim carrega um índice magro (o que existe e quando puxar), e a orientação detalhada vive em skills lidas on-demand. Contexto fixo pequeno; profundidade paga sob demanda.

Por que não degrada: não removi informação, mudei quando ela entra. Tocou o auth, o skill detalhado do auth é carregado integralmente: orientação completa, na hora certa. O que cortei foi carregar a guideline dos 18 serviços pra editar um. É a mesma lógica do prefixo cacheável, levada pra arquitetura de contexto: minimize o fixo, pague o resto sob demanda.

Log de texto não responde as perguntas que importam: quanto custou, por que ficou lento, onde a qualidade caiu. Trato cada chamada de LLM como span de um trace distribuído (OpenTelemetry), com atributos próprios do domínio: modelo, versão do prompt, tokens de entrada/saída, cache hit/miss, TTFT, stop_reason e custo calculado na hora.

Correlação. O span da chamada vive dentro do trace da request: dá pra responder "por que essa tela demorou" apontando pro span exato. Payloads entram por amostragem, com redação de PII antes de persistir.

O que vira alerta. Só o acionável: custo por dia e por tenant, p95 de TTFT, taxa de fallback entre modelos, taxa de refusal. Alerta de "erro genérico" em LLM é ruído; alerta de custo dobrando em 24h é incidente.

É a tese do Projeto Atena, nossa IDE de IA: cada ação do agente rastreável, o que leu, o que decidiu e quanto custou, auditável de ponta a ponta.

Muda a unidade de análise: chatbot é request/response, agente é trajetória. O objeto que você observa é a árvore de passos: cada tool call com input e output, cada decisão intermediária, o contexto que o agente enxergava naquele momento.

Custo cumulativo e loops. Agente erra caro: monitoro custo acumulado por trajetória e corto quando passa do teto; detecção de laço (mesma tool com os mesmos argumentos repetidamente) dispara interrupção antes de queimar orçamento.

Replay determinístico. Guardar o contexto exato de cada decisão permite reproduzir a trajetória e auditar: por que o agente escolheu X no passo 4? Sem replay, debugging de agente é adivinhação com log.

Sem gabarito, qualidade vem de proxies em camadas, nunca de uma métrica só.

1. Feedback implícito. O usuário aceitou, editou pesado ou refez a pergunta? É o sinal mais barato e mais honesto que existe, e a maioria ignora.

2. Golden set como teste de regressão. Um conjunto pequeno e curado de casos roda a cada mudança de prompt ou de modelo, igual suíte de testes. Mudou prompt sem rodar golden set é deploy sem CI.

3. LLM-as-judge calibrado. Juiz automático só vale depois de calibrado contra avaliação humana numa amostra, e nunca o mesmo modelo julgando a si mesmo sem essa calibração.

4. Drift de distribuição. Tamanho médio de resposta, taxa de recusa e latência mudando sem deploy seu significam que o provider mexeu por baixo. Curva estável é tão informativa quanto teste passando.