new feature: Integration with kbdb Autonomous

agent_framework_oci/.env.example

@@ -212,3 +212,25 @@ LONG_TERM_MEMORY_INJECT_CONTEXT=true
 # Keep disabled in the generic framework; agents may enable their own YAML mapping.
 OBSERVABILITY_CODE_MAPPING_ENABLED=false
 OBSERVABILITY_CODE_MAPPING_PATH=
+
+###############################################################################
+# RAG provider selection (mutually exclusive at runtime)
+###############################################################################
+# standard = RAG original do agent_framework_oci (default, backward compatible)
+# kbdb     = KBDB enterprise via PKG_KB_SERVING.SEARCH_KNOWLEDGE_BASE
+RAG_PROVIDER=standard
+
+# Somente usados quando RAG_PROVIDER=kbdb. Se vazios, credenciais caem para ADB_*.
+KBDB_DB_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=

agent_framework_oci/.idea/workspace.xml

@@ -50,21 +50,102 @@
     "ASKED_SHARE_PROJECT_CONFIGURATION_FILES": "true",
     "ModuleVcsDetector.initialDetectionPerformed": "true",
     "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager": "true",
     "RunOnceActivity.git.unshallow": "true",
     "RunOnceActivity.typescript.service.memoryLimit.init": "true",
     "SHARE_PROJECT_CONFIGURATION_FILES": "true",
+    "Shell Script.agent_frontend.executor": "Run",
+    "Shell Script.agent_template_backend.executor": "Run",
+    "Shell Script.mcp_gateway.executor": "Run",
+    "Shell Script.mcp_server.executor": "Run",
     "git-widget-placeholder": "master",
     "kotlin-language-version-configured": "true",
-    "last_opened_file_path": "D:/Dropbox/ORACLE/TIM/FY27/Wave_2/Ajuste para manter o agente atual ou voltar ao roteamento/agent_framework_oci",
+    "last_opened_file_path": "C:/Asus_Projects/kbdb/agent_framework_oci/templates/agent_template_backend",
     "node.js.detected.package.eslint": "true",
     "node.js.detected.package.tslint": "true",
     "node.js.selected.package.eslint": "(autodetect)",
     "node.js.selected.package.tslint": "(autodetect)",
     "nodejs_package_manager_path": "npm",
-    "settings.editor.selected.configurable": "configurable.group.appearance",
+    "project.structure.last.edited": "Project",
+    "project.structure.proportion": "0.15",
+    "project.structure.side.proportion": "0.2",
+    "settings.editor.selected.configurable": "advanced.settings",
     "vue.rearranger.settings.migration": "true"
   }
 }]]></component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="C:\Asus_Projects\kbdb\agent_framework_oci\templates\agent_template_backend" />
+    </key>
+  </component>
+  <component name="RunManager" selected="Shell Script.agent_template_backend">
+    <configuration name="agent_frontend" type="ShConfigurationType">
+      <option name="SCRIPT_TEXT" value="wsl bash -lc &quot;source .venv/bin/activate &amp;&amp; cd apps/agent_frontend &amp;&amp; python -m http.server 5173&quot;" />
+      <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
+      <option name="SCRIPT_PATH" value="" />
+      <option name="SCRIPT_OPTIONS" value="" />
+      <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
+      <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+      <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
+      <option name="INTERPRETER_PATH" value="powershell.exe" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="EXECUTE_IN_TERMINAL" value="true" />
+      <option name="EXECUTE_SCRIPT_FILE" value="false" />
+      <envs />
+      <method v="2" />
+    </configuration>
+    <configuration name="agent_template_backend" type="ShConfigurationType">
+      <option name="SCRIPT_TEXT" value="wsl bash -lc &quot;source .venv/bin/activate &amp;&amp; cd templates/agent_template_backend &amp;&amp; python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload&quot;" />
+      <option name="INDEPENDENT_SCRIPT_PATH" value="false" />
+      <option name="SCRIPT_PATH" value="$PROJECT_DIR$/templates/agent_template_backend/app" />
+      <option name="SCRIPT_OPTIONS" value="" />
+      <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="false" />
+      <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+      <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
+      <option name="INTERPRETER_PATH" value="powershell.exe" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="EXECUTE_IN_TERMINAL" value="true" />
+      <option name="EXECUTE_SCRIPT_FILE" value="false" />
+      <envs />
+      <method v="2" />
+    </configuration>
+    <configuration name="mcp_gateway" type="ShConfigurationType">
+      <option name="SCRIPT_TEXT" value="wsl bash -lc &quot;source .venv/bin/activate &amp;&amp; cd scripts &amp;&amp; bash run_mcp_gateway.sh&quot;" />
+      <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
+      <option name="SCRIPT_PATH" value="" />
+      <option name="SCRIPT_OPTIONS" value="" />
+      <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
+      <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+      <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
+      <option name="INTERPRETER_PATH" value="powershell.exe" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="EXECUTE_IN_TERMINAL" value="true" />
+      <option name="EXECUTE_SCRIPT_FILE" value="false" />
+      <envs />
+      <method v="2" />
+    </configuration>
+    <configuration name="mcp_server" type="ShConfigurationType">
+      <option name="SCRIPT_TEXT" value="wsl bash -lc &quot;source .venv/bin/activate &amp;&amp; cd scripts &amp;&amp; bash run_mcp_servers.sh&quot;" />
+      <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
+      <option name="SCRIPT_PATH" value="" />
+      <option name="SCRIPT_OPTIONS" value="" />
+      <option name="INDEPENDENT_SCRIPT_WORKING_DIRECTORY" value="true" />
+      <option name="SCRIPT_WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+      <option name="INDEPENDENT_INTERPRETER_PATH" value="true" />
+      <option name="INTERPRETER_PATH" value="powershell.exe" />
+      <option name="INTERPRETER_OPTIONS" value="" />
+      <option name="EXECUTE_IN_TERMINAL" value="true" />
+      <option name="EXECUTE_SCRIPT_FILE" value="false" />
+      <envs />
+      <method v="2" />
+    </configuration>
+    <list>
+      <item itemvalue="Shell Script.agent_template_backend" />
+      <item itemvalue="Shell Script.mcp_gateway" />
+      <item itemvalue="Shell Script.mcp_server" />
+      <item itemvalue="Shell Script.agent_frontend" />
+    </list>
+  </component>
   <component name="SharedIndexes">
     <attachedChunks>
       <set>
@@ -89,9 +170,10 @@
       <workItem from="1785245181314" duration="79000" />
       <workItem from="1785245608367" duration="670000" />
       <workItem from="1785326458404" duration="86000" />
-      <workItem from="1785414225783" duration="148000" />
-      <workItem from="1785414447653" duration="704000" />
-      <workItem from="1785630146329" duration="316000" />
+      <workItem from="1785405876905" duration="1300000" />
+      <workItem from="1785409583147" duration="1561000" />
+      <workItem from="1785452072692" duration="784000" />
+      <workItem from="1785453511270" duration="1006000" />
     </task>
     <task id="LOCAL-00001" summary="Ajustes na documentação e remanejamento dos folders">
       <option name="closed" value="true" />

agent_framework_oci/README.md

@@ -11176,3 +11176,7 @@ A adoção das funcionalidades do `Tuning-Performance` pode proporcionar:
 * comportamento consistente entre diferentes agentes e projetos.
 
 O conteúdo desta pasta deve ser tratado como uma extensão adicional do framework. Sua utilização requer implementação, configuração, testes funcionais e validação das regras de negócio antes da implantação em produção.
+
+### RAG provider alternativo (KBDB Enterprise)
+
+O RAG original continua sendo o default (`RAG_PROVIDER=standard`). Para usar a arquitetura KBDB enterprise como alternativa de serving, configure `RAG_PROVIDER=kbdb`. Os agentes continuam usando o mesmo `RagService`/`_retrieve_rag_context()` e os dois backends não são executados simultaneamente. Consulte `docs/RAG_PROVIDER_KBDB.md`.

agent_framework_oci/docs/RAG_PROVIDER_KBDB.md

@@ -0,0 +1,94 @@
+# 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
+
+```env
+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
+
+```env
+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:
+
+```yaml
+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`.

agent_framework_oci/libs/agent_framework/src/agent_framework.egg-info/SOURCES.txt

@@ -190,6 +190,7 @@ src/agent_framework/rag/__init__.py
 src/agent_framework/rag/embedding_provider.py
 src/agent_framework/rag/graph_store.py
 src/agent_framework/rag/ingest.py
+src/agent_framework/rag/kbdb_service.py
 src/agent_framework/rag/rag_service.py
 src/agent_framework/rag/vector_store.py
 src/agent_framework/repositories/__init__.py
@@ -215,6 +216,7 @@ src/agent_framework/supervisor/router_supervisor.py
 src/agent_framework/supervisor/supervisor.py
 src/agent_framework/workflows/__init__.py
 src/agent_framework/workflows/graph.py
+src/agent_framework/workflows/input_contract.py
 src/agent_framework/workflows/models.py
 src/agent_framework/workflows/registry.py
 src/agent_framework/workflows/repository.py

agent_framework_oci/libs/agent_framework/src/agent_framework/checkpoints/langgraph_saver.py

@@ -18,6 +18,7 @@ returned using CheckpointTuple; otherwise a simple dict is returned for tests.
 """
 
 import asyncio
+import base64
 import json
 import uuid
 from typing import Any, AsyncIterator, Iterator
@@ -94,6 +95,200 @@ def _strict_json_value(value: Any, *, path: str = "$") -> Any:
     )
 
 
+
+_TYPED_SERDE_MARKER = "__agent_framework_langgraph_typed__"
+
+
+def _is_langgraph_interrupt(value: Any) -> bool:
+    """Return True only for LangGraph's native Interrupt primitive.
+
+    Keep this deliberately narrow.  The repository contract remains strict JSON
+    everywhere else so an unrelated future runtime object cannot silently change
+    the durable checkpoint format.
+    """
+    cls = type(value)
+    return cls.__module__ == "langgraph.types" and cls.__qualname__ == "Interrupt"
+
+
+def _typed_serde_envelope(serializer: Any, value: Any, *, path: str) -> dict[str, Any]:
+    dumps_typed = getattr(serializer, "dumps_typed", None)
+    if not callable(dumps_typed):
+        raise TypeError(f"Serializer LangGraph não suporta dumps_typed em {path}")
+    type_name, payload = dumps_typed(value)
+    if not isinstance(payload, (bytes, bytearray)):
+        raise TypeError(
+            f"Serializer LangGraph retornou payload inválido em {path}: "
+            f"{type(payload).__module__}.{type(payload).__qualname__}"
+        )
+    return {
+        _TYPED_SERDE_MARKER: True,
+        "type": str(type_name),
+        "data": base64.b64encode(bytes(payload)).decode("ascii"),
+    }
+
+
+
+
+def _encode_checkpoint_value(
+    serializer: Any,
+    value: Any,
+    *,
+    path: str = "$.checkpoint",
+    in_channel_values: bool = False,
+    in_interrupt_channel: bool = False,
+) -> Any:
+    """Serialize the checkpoint without widening its historical JSON contract.
+
+    The only typed exception is LangGraph's native ``Interrupt`` and only while
+    traversing the special ``__interrupt__`` channel under ``channel_values``.
+    Every other checkpoint value keeps the strict-JSON behavior, so future
+    runtime/business objects cannot silently start using typed serde.
+    """
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        for key, item in value.items():
+            skey = str(key)
+            child_in_channel_values = in_channel_values or (
+                path == "$.checkpoint" and skey == "channel_values"
+            )
+            child_in_interrupt_channel = in_interrupt_channel or (
+                child_in_channel_values and skey == "__interrupt__"
+            )
+            out[skey] = _encode_checkpoint_value(
+                serializer,
+                item,
+                path=f"{path}.{skey}",
+                in_channel_values=child_in_channel_values,
+                in_interrupt_channel=child_in_interrupt_channel,
+            )
+        return out
+    if isinstance(value, (list, tuple)):
+        return [
+            _encode_checkpoint_value(
+                serializer,
+                item,
+                path=f"{path}[{idx}]",
+                in_channel_values=in_channel_values,
+                in_interrupt_channel=in_interrupt_channel,
+            )
+            for idx, item in enumerate(value)
+        ]
+    if in_channel_values and in_interrupt_channel and _is_langgraph_interrupt(value):
+        return _typed_serde_envelope(serializer, value, path=path)
+    return _strict_json_value(value, path=path)
+
+
+def _decode_checkpoint_value(
+    serializer: Any,
+    value: Any,
+    *,
+    path: str = "$.checkpoint",
+    in_channel_values: bool = False,
+    in_interrupt_channel: bool = False,
+) -> Any:
+    """Inverse of :func:`_encode_checkpoint_value`, with the same narrow scope."""
+    if isinstance(value, dict):
+        if in_channel_values and in_interrupt_channel and value.get(_TYPED_SERDE_MARKER) is True:
+            loads_typed = getattr(serializer, "loads_typed", None)
+            if not callable(loads_typed):
+                raise TypeError("Serializer LangGraph não suporta loads_typed")
+            type_name = value.get("type")
+            raw = value.get("data")
+            if not isinstance(type_name, str) or not isinstance(raw, str):
+                raise TypeError(f"Envelope de serialização LangGraph inválido em {path}")
+            return loads_typed((type_name, base64.b64decode(raw.encode("ascii"))))
+        out: dict[str, Any] = {}
+        for key, item in value.items():
+            skey = str(key)
+            child_in_channel_values = in_channel_values or (
+                path == "$.checkpoint" and skey == "channel_values"
+            )
+            child_in_interrupt_channel = in_interrupt_channel or (
+                child_in_channel_values and skey == "__interrupt__"
+            )
+            out[skey] = _decode_checkpoint_value(
+                serializer,
+                item,
+                path=f"{path}.{skey}",
+                in_channel_values=child_in_channel_values,
+                in_interrupt_channel=child_in_interrupt_channel,
+            )
+        return out
+    if isinstance(value, list):
+        return [
+            _decode_checkpoint_value(
+                serializer,
+                item,
+                path=f"{path}[{idx}]",
+                in_channel_values=in_channel_values,
+                in_interrupt_channel=in_interrupt_channel,
+            )
+            for idx, item in enumerate(value)
+        ]
+    return value
+
+def _encode_pending_write_value(
+    serializer: Any,
+    value: Any,
+    *,
+    path: str,
+    in_interrupt_channel: bool = False,
+) -> Any:
+    """Serialize pending writes with a narrowly-scoped Interrupt exception.
+
+    ``Interrupt`` is accepted only in LangGraph's special ``__interrupt__``
+    branch (either the write channel itself or a nested ``__interrupt__`` key).
+    Other non-JSON objects still fail loudly.
+    """
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        for key, item in value.items():
+            skey = str(key)
+            child_interrupt = in_interrupt_channel or skey == "__interrupt__"
+            out[skey] = _encode_pending_write_value(
+                serializer,
+                item,
+                path=f"{path}.{skey}",
+                in_interrupt_channel=child_interrupt,
+            )
+        return out
+    if isinstance(value, (list, tuple)):
+        return [
+            _encode_pending_write_value(
+                serializer,
+                item,
+                path=f"{path}[{idx}]",
+                in_interrupt_channel=in_interrupt_channel,
+            )
+            for idx, item in enumerate(value)
+        ]
+    if in_interrupt_channel and _is_langgraph_interrupt(value):
+        return _typed_serde_envelope(serializer, value, path=path)
+    return _strict_json_value(value, path=path)
+
+
+def _serde_decode(serializer: Any, value: Any) -> Any:
+    """Restore values encoded by :func:`_serde_encode` recursively."""
+    if isinstance(value, dict):
+        if value.get(_TYPED_SERDE_MARKER) is True:
+            loads_typed = getattr(serializer, "loads_typed", None)
+            if not callable(loads_typed):
+                raise TypeError("Serializer LangGraph não suporta loads_typed")
+            type_name = value.get("type")
+            raw = value.get("data")
+            if not isinstance(type_name, str) or not isinstance(raw, str):
+                raise TypeError("Envelope de serialização LangGraph inválido")
+            return loads_typed((type_name, base64.b64decode(raw.encode("ascii"))))
+        return {key: _serde_decode(serializer, item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_serde_decode(serializer, item) for item in value]
+    return value
+
+
 def _normalize_checkpoint(checkpoint: Any) -> dict[str, Any]:
     checkpoint = _parse_legacy_json_container(checkpoint, dict)
     if not isinstance(checkpoint, dict):
@@ -277,6 +472,7 @@ class RepositoryCheckpointSaver(BaseCheckpointSaver):
 
     def __init__(self, settings, repository=None):
         super().__init__()
+        self.serde = getattr(self, "serde", None)
         self.settings = settings
         self.repository = repository or create_checkpoint_repository(settings)
         self._loop: asyncio.AbstractEventLoop | None = None
@@ -302,8 +498,10 @@ class RepositoryCheckpointSaver(BaseCheckpointSaver):
         # Second-stage protection: never re-bind the full persisted RunnableConfig.
         # Rebuild only the durable identifiers, as official LangGraph savers do.
         config = _canonical_checkpoint_config(payload, request_config)
-        checkpoint = _strip_runtime_refs(_normalize_checkpoint(payload.get("checkpoint") or {}))
-        metadata = _strip_runtime_refs(_normalize_metadata(payload.get("metadata") or {}))
+        checkpoint_value = _decode_checkpoint_value(self.serde, payload.get("checkpoint") or {})
+        metadata_value = payload.get("metadata") or {}
+        checkpoint = _strip_runtime_refs(_normalize_checkpoint(checkpoint_value))
+        metadata = _strip_runtime_refs(_normalize_metadata(metadata_value))
         raw_parent_config = payload.get("parent_config")
         if isinstance(raw_parent_config, dict):
             parent_payload = {
@@ -317,8 +515,9 @@ class RepositoryCheckpointSaver(BaseCheckpointSaver):
             parent_config = _canonical_checkpoint_config(parent_payload)
         else:
             parent_config = None
+        pending_value = _serde_decode(self.serde, payload.get("pending_writes") or [])
         pending_writes = _normalize_pending_writes(
-            _strip_runtime_refs(payload.get("pending_writes") or [])
+            _strip_runtime_refs(pending_value)
         )
         try:
             from langgraph.checkpoint.base import CheckpointTuple
@@ -359,7 +558,7 @@ class RepositoryCheckpointSaver(BaseCheckpointSaver):
         await self.repository.put(thread_id, {
             "thread_id": thread_id,
             "config": _strict_json_value(next_config, path="$.config"),
-            "checkpoint": _strict_json_value(_strip_runtime_refs(_normalize_checkpoint(checkpoint)), path="$.checkpoint"),
+            "checkpoint": _encode_checkpoint_value(self.serde, _strip_runtime_refs(_normalize_checkpoint(checkpoint)), path="$.checkpoint"),
             "metadata": _strict_json_value(_strip_runtime_refs(_normalize_metadata(metadata or {})), path="$.metadata"),
             "new_versions": _strict_json_value(_strip_runtime_refs(new_versions or {}), path="$.new_versions"),
             "checkpoint_id": checkpoint_id,
@@ -410,7 +609,12 @@ class RepositoryCheckpointSaver(BaseCheckpointSaver):
                 "task_id": task_id,
                 "task_path": task_path,
                 "channel": channel,
-                "value": _strict_json_value(durable_value, path=f"$.pending_writes[{task_id}].{channel}"),
+                "value": _encode_pending_write_value(
+                    self.serde,
+                    durable_value,
+                    path=f"$.pending_writes[{task_id}].{channel}",
+                    in_interrupt_channel=(str(channel) == "__interrupt__"),
+                ),
             })
         latest["pending_writes"] = pending
         await self.repository.put(thread_id, latest)

agent_framework_oci/libs/agent_framework/src/agent_framework/config/settings.py

@@ -103,12 +103,32 @@ class Settings(BaseSettings):
     ENABLE_REDIS_CACHE: bool = False
     CACHE_KEY_PREFIX: str = 'agentfw'
 
+    # RAG backend selector. 'standard' preserves the existing framework RAG;
+    # 'kbdb' consumes the enterprise KBDB stable serving facade without changing agents.
+    RAG_PROVIDER: Literal['standard','kbdb'] = 'standard'
     VECTOR_STORE_PROVIDER: Literal['memory','sqlite','autonomous','oracle','mongodb'] = 'memory'
     GRAPH_STORE_PROVIDER: Literal['memory','autonomous','oracle'] = 'memory'
     ORACLE_GRAPH_NAME: str = 'AGENTFW_GRAPH'
     ORACLE_GRAPH_AUTO_CREATE: bool = False
     RAG_TOP_K: int = 5
+    KBDB_DB_USER: str | None = None
+    KBDB_DB_PASSWORD: str | None = None
+    KBDB_DB_DSN: str | None = None
+    KBDB_DB_WALLET_LOCATION: str | None = None
+    KBDB_DB_WALLET_PASSWORD: str | None = None
+    KBDB_SEARCH_TYPE: Literal['hybrid','vector','keyword'] = 'hybrid'
+    KBDB_NODE_EXPANSION: bool = True
+    KBDB_NODE_MAX_RELATED: int = 8
+    KBDB_GRAPH_CROSS_REF: bool = False
+    KBDB_MAX_CROSS_REF_HOPS: int = 1
+    KBDB_DOCUMENT_TYPE: str | None = 'customer_safe'
+    KBDB_METADATA_JSON: str | None = None
+    KBDB_MIN_SCORE: float | None = None
+    # MCP só pula retrieval quando declarar explicitamente rag_sufficient/knowledge_sufficient.
     SKIP_RAG_WHEN_MCP_SUFFICIENT: bool = True
+    # Preserva comportamento legado do RAG standard; KBDB enterprise é grounded-only por padrão.
+    RAG_GROUNDED_ONLY: bool = False
+    KBDB_GROUNDED_ONLY: bool = True
     ENABLE_RAG_QUERY_REWRITE: bool = False
     ENABLE_RAG_CONTEXT_COMPRESSION: bool = False
     ENABLE_RAG_GENERATION: bool = False