2.1 — RAG e Embeddings como Infraestrutura do Harness, não Feature de Aplicação

Objetivo da Aula

Situar RAG e embeddings dentro do harness como camada de infraestrutura consultada pelo agent loop, não como endpoint isolado de uma aplicação

Explicar por que tratar RAG como "feature de chatbot" produz sistemas frágeis quando o número de agentes e fontes de conhecimento cresce

Distinguir as três responsabilidades arquiteturais que a camada de grounding precisa cumprir: indexação, recuperação e governança de acesso ao conhecimento

Desenhar o contrato entre harness e camada de grounding — o que o agent loop pede, o que a infraestrutura de RAG devolve, e quem decide o quê

Identificar os sintomas arquiteturais de RAG implementado como feature isolada: duplicação de índices, ausência de controle de acesso, inconsistência entre agentes

Por que isso importa

Você já sabe montar um pipeline RAG: dividir documentos, gerar embeddings, indexar em um vector store, recuperar por similaridade, injetar no prompt. Esse conhecimento é pré-requisito aqui — não vamos reexplicar como um embedding é calculado ou como funciona um índice vetorial.

O problema que a Parte 1 já expôs é outro: um agente sem harness é um script com sorte. O mesmo vale para RAG. Um pipeline RAG amarrado a uma aplicação específica — "o chatbot de suporte consulta o índice X" — funciona até você precisar de um segundo agente que também precisa consultar conhecimento da empresa. Nesse momento, ou você duplica o pipeline (dois índices, duas políticas de chunking, duas formas de decidir o que é relevante), ou descobre que RAG nunca deveria ter sido acoplado a uma única aplicação.

Impacto direto no seu trabalho: toda vez que você decide "esse agente vai ter acesso a busca semântica na base de contratos", você está tomando uma decisão de arquitetura de plataforma, não de feature de produto. Se o harness é o plano de controle central (como estabelecido na Parte 1), a camada de grounding é um dos serviços que esse plano de controle governa — no mesmo nível de permissões, estado e resolução de tools. Tratá-la como "só mais uma chamada de API dentro do prompt" é o erro que te obriga a reescrever a integração de conhecimento a cada novo agente que a empresa cria.

Conceitos Fundamentais

Onde o grounding vive na arquitetura do harness

Revisando o modelo da Parte 1: o harness intermedeia tudo entre o LLM (motor de inferência intercambiável) e o mundo externo — permissões, estado, tools disponíveis, e o loop que decide a próxima ação. RAG entra nesse modelo como um serviço de grounding que o harness consulta antes ou durante a decisão do agente, não como uma chamada de tool qualquer entre outras.

Arquitetura em camadas (revisão da Parte 1 + grounding):

A diferença não é cosmética. Quando o grounding é infraestrutura do harness, ele herda as mesmas regras que qualquer outro recurso governado: um agente só consulta os índices para os quais tem permissão (RBAC — Parte 1.3), o resultado da consulta pode virar estado persistente (Parte 1.4), e a decisão de quando consultar é resolvida dinamicamente pelo motor de resolução condicional (Parte 1.5), não hardcoded na aplicação.

As três responsabilidades da camada de grounding

Separar RAG do harness em três responsabilidades distintas evita o erro mais comum: tratar "RAG" como uma coisa só, quando na verdade são três decisões arquiteturais independentes.

Note que a responsabilidade 3 é a que mais frequentemente falta em implementações "feature de chatbot". Um pipeline RAG amador confia que, se o índice existe, qualquer consulta pode trazer qualquer chunk. Em produção corporativa, isso é uma falha de segurança: um agente de RH não deveria recuperar chunks de um documento de folha de pagamento só porque a similaridade semântica foi alta.

O contrato entre agent loop e serviço de grounding

Pensando em contrato de API — não em implementação — o harness expõe ao agent loop uma operação de grounding com uma assinatura estável, independente de qual vector store ou qual modelo de embedding está por trás:

função consultar_grounding(query, contexto_agente) → resultado_grounding

entrada:
  query: string                  // pergunta ou trecho a ser embeddado
  contexto_agente: {
    agente_id: string,
    escopos_permitidos: [string], // quais índices/coleções este agente pode ler
    top_k: int,                   // quantos chunks recuperar
    filtros: { ... }              // metadados obrigatórios (data, tipo, dono)
  }

saída:
  resultado_grounding: {
    chunks: [
      { texto: string, score: float, fonte: string, metadados: {...} }
    ],
    cobertura: "alta" | "media" | "baixa" | "nenhuma",
    índices_consultados: [string]
  }

O ponto arquitetural central: o agent loop nunca fala diretamente com o vector store. Ele fala com o harness, que resolve escopos_permitidos a partir do RBAC do agente (não do que o agente pediu), aplica os filtros, e só então delega ao serviço de recuperação. Isso é o mesmo padrão de resolução de tools da Parte 1.5 — o agente não escolhe livremente quais tools existem; o harness resolve quais estão disponíveis dado o contexto.

Aprofundamento Técnico

Por que acoplar RAG à aplicação quebra em escala

O sintoma mais visível de RAG-como-feature é a duplicação silenciosa. Considere uma empresa que começa com um agente de suporte ao cliente com RAG sobre a base de conhecimento pública. Seis meses depois, times diferentes pedem: um agente jurídico que consulta contratos, um agente de engenharia que consulta documentação de código, um agente de vendas que consulta histórico de propostas.

Cenário sem grounding como infraestrutura (RAG por aplicação):

Agente Suporte  → pipeline próprio → índice A (chunking: 500 tokens, overlap 50)
Agente Jurídico → pipeline próprio → índice B (chunking: 1000 tokens, overlap 100)
Agente Eng.     → pipeline próprio → índice C (chunking: por função de código)
Agente Vendas   → pipeline próprio → índice D (chunking: 300 tokens, overlap 0)

Problemas emergentes:
- 4 políticas de chunking diferentes, nenhuma documentada centralmente
- 4 processos de reindexação, com 4 SLAs de atualização diferentes
- Nenhum controle centralizado: se um documento tem dado sensível,
  cada pipeline decide isoladamente se filtra ou não
- Um agente investigativo (Parte 4.3) que precisa cruzar informação de
  contratos E de suporte não tem como fazer uma única consulta federada

Comparado com grounding como infraestrutura do harness:

Cenário com grounding como serviço de plataforma: os quatro agentes (Suporte, Jurídico, Eng. e Vendas) deixam de ter pipelines próprios e convergem para o mesmo caminho — Agente Suporte, Agente Jurídico, Agente Eng. e Agente Vendas → Harness (RBAC resolve o escopo de cada um) → Serviço de Grounding (política de chunking centralizada, versionada, auditável) → Índices (organizados por domínio, mas expostos por um contrato único).

Ganhos:

• Uma política de chunking (com exceções documentadas por domínio, não reinventada por time)
• Auditoria central: "quem consultou o quê" vira log do harness, não espalhado em 4 aplicações
• Agente novo não implementa RAG do zero — declara escopos e consome o contrato de grounding já existente

Isso não significa um índice único para toda a empresa — isso seria trocar um problema (duplicação) por outro (relevância degradada, misturando domínios muito diferentes no mesmo espaço vetorial). Significa que a decisão de como particionar índices, como versionar política de chunking e como aplicar RBAC é centralizada no harness, mesmo que a implementação física use múltiplos índices por domínio.

Cobertura como sinal de decisão, não só resultado de busca

No contrato de grounding acima, o campo cobertura merece atenção especial porque conecta diretamente com o capítulo 2.4: o harness precisa decidir o que sabe antes de decidir o que faz. Um serviço de grounding maduro não devolve só chunks — devolve um sinal de confiança sobre se a pergunta tem resposta na base de conhecimento disponível.

Heurística simples de cobertura (exemplo):

score_top1 = maior score de similaridade entre os chunks recuperados
gap = score_top1 - score_top_k        // distância entre o melhor e o pior do top-k

se score_top1 < limiar_minimo:
    cobertura = "nenhuma"      // não force resposta; sinalize desconhecimento
senão se score_top1 >= limiar_alto e gap < limiar_gap:
    cobertura = "alta"          // vários chunks convergem, resposta consistente
senão:
    cobertura = "media" | "baixa"

Sem esse sinal, o agent loop trata toda recuperação como igualmente confiável — e é exatamente isso que produz alucinação por excesso de confiança: o LLM recebe três chunks fracamente relacionados e ainda assim constrói uma resposta afirmativa. Tratar cobertura como parte do contrato de grounding, resolvida pelo harness antes de chegar ao LLM, é uma decisão de arquitetura, não um ajuste de prompt.

Trade-off: latência de governança vs. simplicidade de acesso direto

Roteirizar toda consulta de grounding pelo harness (em vez de o agente chamar o vector store diretamente) adiciona uma camada de indireção — e, com ela, latência e complexidade operacional. Vale a pena nomear esse custo em vez de escondê-lo:

Para agentes internos de baixo risco (protótipo, uso pessoal, sem dado sensível), acesso direto pode ser aceitável temporariamente. Para qualquer agente que toca dado corporativo real — contrato, código proprietário, dado de cliente — a indireção via harness não é opcional: é a diferença entre um sistema auditável e um sistema que depende de ninguém cometer erro.

Consequência para os próximos três capítulos

Estabelecido que grounding é infraestrutura do harness, os próximos capítulos desta parte detalham cada uma das três responsabilidades vistas acima: 2.2 aprofunda como a indexação decide granularidade e metadados; 2.3 detalha como a recuperação resolve similaridade, filtros e ranking dentro desse contrato; 2.4 fecha o ciclo mostrando como o sinal de cobertura entra na decisão do agent loop antes de qualquer ação ser tomada.