RAG alternativo: Standard x KBDB Enterprise

O framework passa a suportar dois backends de retrieval pelo mesmo contrato RagService, sem alterar os agentes nem _retrieve_rag_context().

Seleção

RAG_PROVIDER=standard  # default: comportamento anterior
# ou
RAG_PROVIDER=kbdb      # KBDB enterprise

A seleção é exclusiva por processo. Os dois RAGs não executam juntos e não compartilham vector store, graph store ou ingestão.

`standard`

Mantém integralmente o RAG já existente no agent_framework_oci: VECTOR_STORE_PROVIDER, GRAPH_STORE_PROVIDER, embedding, query rewrite, compression, retrieval guardrails e geração continuam válidos.

`kbdb`

O framework integra somente a porta estável de serving do projeto KBDB:

PKG_KB_SERVING.SEARCH_KNOWLEDGE_BASE

O pipeline enterprise continua externo ao runtime do agente e preserva sua própria arquitetura RAW → SILVER → GOLD, HVI/hybrid search, property graph, publicação, lifecycle, auditoria e observabilidade.

O envelope KBDB é adaptado para RagResult/VectorDocument; portanto os agentes existentes continuam chamando _retrieve_rag_context() e os retrieval guardrails do framework continuam depois do retrieval.

Configuração

RAG_PROVIDER=kbdb
RAG_TOP_K=5
KBDB_DB_USER=KB_USER
KBDB_DB_PASSWORD=...
KBDB_DB_DSN=...
KBDB_DB_WALLET_LOCATION=...
KBDB_DB_WALLET_PASSWORD=...
KBDB_SEARCH_TYPE=hybrid
KBDB_NODE_EXPANSION=true
KBDB_NODE_MAX_RELATED=8
KBDB_GRAPH_CROSS_REF=false
KBDB_MAX_CROSS_REF_HOPS=1
KBDB_DOCUMENT_TYPE=customer_safe
KBDB_METADATA_JSON=
KBDB_MIN_SCORE=

Quando RAG_PROVIDER=kbdb, KBDB_DB_USER, KBDB_DB_PASSWORD e KBDB_DB_DSN são obrigatórios. O KBDB usa conexão isolada porque pode residir em outro Autonomous. KBDB_DB_DSN segue a mesma semântica de ADB_DSN: use o alias TNS existente no tnsnames.ora da wallet indicada por KBDB_DB_WALLET_LOCATION, e não uma URL tcps://....

Isolamento e compatibilidade

RAG_PROVIDER=standard não importa nem conecta ao KBDB.
RAG_PROVIDER=kbdb não instancia vector/graph stores do RAG padrão.
Ingestão por RagService.add_documents() não é permitida no modo KBDB: deve passar pelo pipeline/publicação KBDB.
Query rewrite e context compression continuam opcionais e são aplicados pela camada comum do framework.
AgentRuntimeMixin._retrieve_rag_context() e os agentes permanecem inalterados.
Falhas do KBDB seguem a semântica existente do framework: retrieval é evidência auxiliar e a exceção é convertida em metadata técnica sem derrubar a jornada.

Resposta direta de tool e RAG

O framework não considera mais que um resultado MCP estruturado é, por si só, uma resposta suficiente ao usuário.

Uma política response.renderer define somente como apresentar o resultado. Ela não encerra o fluxo antes de RAG/LLM. Para uma tool deliberadamente produzir uma resposta final direta, a aplicação deve declarar explicitamente:

response:
  mode: renderer
  renderer: meu.renderer
  direct: true

Sem direct: true, o resultado da tool permanece como evidência MCP e o fluxo segue para _retrieve_rag_context() e composição LLM. Isso permite, por exemplo, que uma consulta operacional de plano seja combinada com conhecimento documental do KBDB quando a pergunta pedir regras, políticas ou explicações.

O core do framework não possui fallback por nome de tool (consultar_plano, consultar_pedido, etc.). Regras de apresentação pertencem à aplicação/domínio.

Suficiência MCP e grounding

Um resultado MCP bem-sucedido não faz o framework pular RAG automaticamente. O domínio só pode declarar suficiência documental explicitamente no payload com rag_sufficient=true ou knowledge_sufficient=true. Essa decisão é genérica e não depende do nome da tool nem de palavras-chave de telecom/retail.

No provider kbdb, KBDB_GROUNDED_ONLY=true é o padrão. Quando a busca KBDB retorna vazia, bloqueada ou com erro, a composição LLM pode usar fatos comprovados por MCP/business context, mas não pode completar a parte documental com conhecimento paramétrico do modelo. Deve informar que não há evidência suficiente na base.

Eventos do ProductAgent registram IC.PRODUCT_RAG_CONTEXT_EVALUATED em toda tentativa/decisão e IC.PRODUCT_RAG_CONTEXT_RETRIEVED somente quando há contexto recuperado. Os metadados incluem provider, status, document_count, reason, error, query, namespace e latency_ms.

4.4 KiB Raw Blame History