Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(integrations): add Microsoft Agent Framework context provider (#5578)

z1gon7f69dd24c19d
diff --git a/.github/workflows/python-agent-framework.yml b/.github/workflows/python-agent-framework.yml
new file mode 100644
index 000000000..a69bc6333
--- /dev/null
+++ b/.github/workflows/python-agent-framework.yml
@@ -0,0 +1,44 @@
+name: Microsoft Agent Framework Integration
+
+on:
+ pull_request:
+ paths:
+ - 'examples/agent-framework/**'
+ - '.github/workflows/python-agent-framework.yml'
+ push:
+ branches: [main]
+ paths:
+ - 'examples/agent-framework/**'
+ - '.github/workflows/python-agent-framework.yml'
+
+permissions:
+ contents: read
+
+jobs:
+ contracts:
+ runs-on: ubuntu-24.04
+ strategy:
+ matrix:
+ include:
+ - maf: 'agent-framework-core==1.20.0'
+ sdk: 'openviking-sdk==0.1.13'
+ - maf: 'agent-framework-core>=1.20,<2'
+ sdk: 'openviking-sdk>=0.1.13,<0.2'
+ defaults:
+ run:
+ working-directory: examples/agent-framework
+ steps:
+ - uses: actions/checkout@v6
+ - uses: actions/setup-python@v6
+ with:
+ python-version: '3.12'
+ - name: Install supported dependencies
+ run: python -m pip install '.[test,dev]' '${{ matrix.maf }}' '${{ matrix.sdk }}'
+ - name: Check package and offline contracts
+ run: |
+ ruff check .
+ ruff format --check .
+ mypy src
+ pytest -q --confcutdir=tests tests
+ python -m build
+ python -m twine check dist/*
diff --git a/examples/agent-framework/README.md b/examples/agent-framework/README.md
new file mode 100644
index 000000000..e113ce3f2
--- /dev/null
+++ b/examples/agent-framework/README.md
@@ -0,0 +1,118 @@
+# OpenViking for Microsoft Agent Framework
+
+An optional Python package for MAF agents. It recalls OpenViking context before a
+run and captures completed agent runs, including tool calls and results.
+The application controls when memory extraction is requested.
+
+## Install and try
+
+Requires Python 3.10+, MAF core 1.20–1.x, OpenViking SDK 0.1.13–0.1.x, and a
+running OpenViking 0.4.23+ server. Install from an OpenViking checkout:
+
+```bash
+pip install './examples/agent-framework[example]'
+```
+
+Set `OPENVIKING_URL`, `OPENVIKING_API_KEY` (a normal user key), `OPENAI_API_KEY`,
+`OPENAI_BASE_URL`, and `OPENAI_MODEL`, then run:
+
+```bash
+python examples/agent-framework/example.py
+```
+
+The example records a preference, waits for extraction, and asks about it in a new
+conversation. Its OpenAI-compatible model client is optional; the provider works
+with other MAF chat clients that support chat middleware (including the built-in
+clients). The package installs neither the OpenViking server
+nor a model client unless the `example` extra is selected.
+
+## Attach to an existing agent
+
+With an initialized, application-owned `AsyncHTTPClient`:
+
+```python
+from agent_framework import Agent
+from openviking_agent_framework import OpenVikingContextProvider
+
+memory = OpenVikingContextProvider(client)
+agent = Agent(chat_client, context_providers=[memory])
+session = agent.create_session()
+response = await agent.run("Remember my preferred reply format: JSON.", session=session)
+job = await memory.commit(session)
+```
+
+`commit()` returns task acceptance. Poll `client.get_task(job["task_id"])` until
+completion before checking extracted memory. Close the client in the application.
+
+## Capture and commit policies
+
+```python
+memory = OpenVikingContextProvider(
+ client,
+ capture=True,
+ commit_policy="pending_tokens",
+ commit_token_threshold=20_000,
+)
+```
+
+| `commit_policy` | Behavior |
+| --- | --- |
+| `"never"` (default) | Capture automatically; the application calls `commit(session)` |
+| `"always"` | Request a commit after each completed, captured agent invocation |
+| `"pending_tokens"` | Request a commit when OV's post-capture pending tokens reach the threshold |
+
+The threshold defaults to 20,000 and must be a positive integer. It counts the
+session's captured, uncommitted tokens; `token_budget` controls recalled context.
+Policies run only after all message batches are acknowledged. A successful
+`flush()` of pending capture also applies the policy. Commit or metadata errors
+propagate, but acknowledged messages remain recorded and are not sent again;
+the next completed invocation or an explicit `commit()` can retry the commit.
+Automatic commits start background extraction and do not wait for completion.
+
+Set `capture=False` for automatic recall without conversation uploads or
+automatic commits. Explicit `flush()` and `commit()` remain available. Turning
+capture off does not discard existing pending messages. The application still
+calls `commit()` at its conversation/workflow boundary to extract a tail below
+the threshold. These policies do not change OV's server-side auto-commit settings.
+
+## State and failure handling
+
+- Use one client/provider per user and actor; serialize work for the same session.
+- Persist `session.to_dict()` and restore with `AgentSession.from_dict()` under the
+ same authenticated user. Preserve message IDs when replaying previous messages.
+- Recalled context is attributed reference data and is excluded from capture.
+ System instructions, hidden reasoning, and nontext media are also excluded.
+- Fully consume streaming responses. Capture happens after each completed agent
+ run, including each `AgentLoopMiddleware` iteration, for both streaming and
+ non-streaming runs. If a later iteration is interrupted, earlier completed
+ iterations remain captured; the interrupted iteration is excluded.
+- Middleware must preserve provider state. `fresh_context=True` rolls that state
+ back between loop iterations and is unsupported; detected state resets raise
+ before further capture or commit.
+- Errors propagate. Unconfirmed capture blocks another run and `commit()`.
+ `flush(session)` retries pending messages after a known failure before sending.
+ A lost response can mean the server already appended the messages: inspect
+ active records and archives by `source_message_ids` before retrying or updating
+ the saved provider state. Blind retries can duplicate capture.
+
+The application owns MAF session persistence; there is no exactly-once guarantee.
+Options are `source_id="openviking"`, `limit=5`, `token_budget=4000` (64–32000),
+and `peer_scope="all"`. Use `peer_scope="actor"` with the SDK client's actor ID.
+The server owns access control, retrieval, storage, and extraction; MAF owns agent
+execution and chat history. No framework modifications or MCP tools are required.
+
+## Validate
+
+```bash
+pip install -e './examples/agent-framework[test,dev]'
+cd examples/agent-framework
+pytest -q --confcutdir=tests tests
+ruff check .
+ruff format --check .
+mypy src
+python -m build
+```
+
+Offline tests use the real MAF agent lifecycle with deterministic model and SDK
+boundaries. They require no server, credentials, or model calls. Support belongs
+in [OpenViking issues](https://github.com/volcengine/OpenViking/issues/new/choose).
diff --git a/examples/agent-framework/example.py b/examples/agent-framework/example.py
new file mode 100644
index 000000000..a8cee0171
--- /dev/null
+++ b/examples/agent-framework/example.py
@@ -0,0 +1,57 @@
+"""Record a preference and recall it in a new MAF conversation."""
+
+import asyncio
+import os
+import time
+
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatCompletionClient
+from openai import AsyncOpenAI
+from openviking_sdk import AsyncHTTPClient
+
+from openviking_agent_framework import OpenVikingContextProvider
+
+
+async def main():
+ client = AsyncHTTPClient(
+ url=os.environ["OPENVIKING_URL"], api_key=os.environ["OPENVIKING_API_KEY"], timeout=60
+ )
+ await client.initialize()
+ try:
+ memory = OpenVikingContextProvider(client)
+ async with AsyncOpenAI(
+ api_key=os.environ["OPENAI_API_KEY"], base_url=os.environ["OPENAI_BASE_URL"]
+ ) as model:
+ agent = Agent(
+ OpenAIChatCompletionClient(model=os.environ["OPENAI_MODEL"], async_client=model),
+ instructions="Use retrieved reference data when relevant.",
+ context_providers=[memory],
+ )
+ session = agent.create_session()
+ print(
+ (await agent.run("Remember my preferred reply format: JSON.", session=session)).text
+ )
+ job = await memory.commit(session)
+ deadline = time.monotonic() + 180
+ while time.monotonic() < deadline:
+ task = await client.get_task(job["task_id"])
+ if task is None or task["status"] in {"failed", "cancelled"}:
+ raise RuntimeError(f"Extraction failed: {task}")
+ if task["status"] == "completed":
+ break
+ await asyncio.sleep(1)
+ else:
+ raise TimeoutError("Extraction did not complete within 180 seconds")
+ print(
+ (
+ await agent.run(
+ "What reply format do I prefer?", session=agent.create_session()
+ )
+ ).text
+ )
+ finally:
+ await client.close()
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/examples/agent-framework/pyproject.toml b/examples/agent-framework/pyproject.toml
new file mode 100644
index 000000000..4818dc7f8
--- /dev/null
+++ b/examples/agent-framework/pyproject.toml
@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openviking-agent-framework"
+version = "0.1.0"
+description = "OpenViking context provider for Microsoft Agent Framework"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "AGPL-3.0"
+dependencies = ["agent-framework-core>=1.20,<2", "openviking-sdk>=0.1.13,<0.2"]
+
+[project.optional-dependencies]
+example = ["agent-framework-openai>=1.15,<2"]
+test = ["pytest>=8", "pytest-asyncio>=0.24"]
+dev = ["ruff", "mypy", "build", "twine"]
+
+[project.urls]
+Repository = "https://github.com/volcengine/OpenViking"
+Documentation = "https://github.com/volcengine/OpenViking/tree/main/examples/agent-framework"
+Issues = "https://github.com/volcengine/OpenViking/issues/new/choose"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+openviking_agent_framework = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+check_untyped_defs = true
+ignore_missing_imports = true
diff --git a/examples/agent-framework/src/openviking_agent_framework/__init__.py b/examples/agent-framework/src/openviking_agent_framework/__init__.py
new file mode 100644
index 000000000..ff9046b4c
--- /dev/null
+++ b/examples/agent-framework/src/openviking_agent_framework/__init__.py
@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""OpenViking memory for Microsoft Agent Framework."""
+
+from .provider import OpenVikingContextProvider
+
+__all__ = ["OpenVikingContextProvider"]
diff --git a/examples/agent-framework/src/openviking_agent_framework/provider.py b/examples/agent-framework/src/openviking_agent_framework/provider.py
new file mode 100644
index 000000000..730540fc2
--- /dev/null
+++ b/examples/agent-framework/src/openviking_agent_framework/provider.py
@@ -0,0 +1,303 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Recall and conversation capture through MAF's public context provider interface."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from typing import Any, Literal
+from uuid import uuid4
+from weakref import WeakKeyDictionary
+
+from agent_framework import (
+ AgentSession,
+ ChatContext,
+ ChatMiddleware,
+ ChatResponseUpdate,
+ ContextProvider,
+ Message,
+ ResponseStream,
+ SessionContext,
+ SupportsAgentRun,
+)
+from openviking_sdk import AsyncHTTPClient
+
+
+class _CaptureCompletion(ChatMiddleware):
+ """Distinguish stream exhaustion from MAF's early-close finalization."""
+
+ def __init__(self, state: dict[str, Any]) -> None:
+ self.state = state
+
+ async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None:
+ self.state["capture_ready"] = False
+ await call_next()
+ if not isinstance(context.result, ResponseStream):
+ self.state["capture_ready"] = True
+ return
+ original = context.result
+
+ async def updates() -> AsyncIterator[ChatResponseUpdate]:
+ async with original:
+ async for update in original:
+ yield update
+ self.state["capture_ready"] = True
+
+ context.result = ResponseStream(
+ updates(), finalizer=lambda _: original.get_final_response()
+ )
+
+
+class OpenVikingContextProvider(ContextProvider):
+ """Attach OpenViking memory to an agent using an application-owned HTTP client.
+
+ Use one provider per authenticated user and actor. Serialize runs for each MAF
+ session. Different sessions may share a provider on the same asyncio event loop.
+ The caller initializes and closes the client and persists MAF session state.
+ Capture defaults to enabled; commits default to explicit application requests.
+ Automatic policies run after acknowledged capture and never wait for extraction.
+ """
+
+ # Capture each completed agent run: loop-level streamed responses only contain
+ # the final iteration in MAF, while per-run responses retain all tool evidence.
+ after_run_once_per_turn = False
+
+ def __init__(
+ self,
+ client: AsyncHTTPClient,
+ *,
+ source_id: str = "openviking",
+ peer_scope: Literal["all", "actor"] = "all",
+ limit: int = 5,
+ token_budget: int = 4000,
+ capture: bool = True,
+ commit_policy: Literal["never", "always", "pending_tokens"] = "never",
+ commit_token_threshold: int = 20_000,
+ ) -> None:
+ if not source_id or limit < 1 or not 64 <= token_budget <= 32000:
+ raise ValueError("source_id must be non-empty; limit > 0; token_budget in [64, 32000]")
+ if peer_scope not in ("all", "actor"):
+ raise ValueError("peer_scope must be 'all' or 'actor'")
+ if not isinstance(capture, bool):
+ raise ValueError("capture must be a boolean")
+ if commit_policy not in ("never", "always", "pending_tokens"):
+ raise ValueError("commit_policy must be 'never', 'always', or 'pending_tokens'")
+ if type(commit_token_threshold) is not int or commit_token_threshold < 1:
+ raise ValueError("commit_token_threshold must be a positive integer")
+ super().__init__(source_id)
+ self.client = client
+ self.peer_scope = peer_scope
+ self.limit = limit
+ self.token_budget = token_budget
+ self.capture = capture
+ self.commit_policy = commit_policy
+ self.commit_token_threshold = commit_token_threshold
+ self._write_lock = asyncio.Lock()
+ self._session_states: WeakKeyDictionary[AgentSession, dict[str, Any]] = WeakKeyDictionary()
+
+ def _state(self, session: AgentSession) -> dict[str, Any]:
+ state = session.state.setdefault(self.source_id, {})
+ # A loop's fresh_context mode rolls provider state back between iterations.
+ # External appends cannot be rolled back with it; fail before another write.
+ previous = self._session_states.get(session)
+ if previous is not None and previous != state:
+ raise RuntimeError(
+ "OpenViking provider state was reset during this session. "
+ "State-resetting middleware such as fresh_context=True is unsupported."
+ )
+ self._session_states[session] = state
+ return state
+
+ async def _ensure_session(self, session: AgentSession) -> str:
+ state = self._state(session)
+ if "session_id" not in state:
+ # Retain the proposed ID even if the create acknowledgement is lost.
+ state["session_id"] = f"maf-{uuid4().hex}"
+ session_id: str = state["session_id"]
+ await self.client.get_session(session_id, auto_create=True)
+ return session_id
+
+ async def before_run(
+ self,
+ *,
+ agent: SupportsAgentRun,
+ session: AgentSession,
+ context: SessionContext,
+ state: dict[str, Any],
+ ) -> None:
+ """Retrieve context before inference; never replay unconfirmed writes implicitly."""
+ self._state(session)
+ if state.get("pending_messages"):
+ raise RuntimeError(
+ "OpenViking capture is unconfirmed. Inspect server records and pending_messages "
+ "in provider state before explicitly calling flush(session); "
+ "a lost acknowledgement may mean the messages were already appended."
+ )
+ state["capture_ready"] = False
+ if self.capture:
+ context.extend_middleware(self.source_id, [_CaptureCompletion(state)])
+ for message in context.input_messages:
+ if message.message_id is None:
+ message.message_id = uuid4().hex
+ query = "\n".join(
+ message.text
+ for message in context.input_messages
+ if message.role == "user" and not message.additional_properties.get("_attribution")
+ )
+ if not query.strip():
+ return
+ session_id = await self._ensure_session(session)
+ result = await self.client.search_context(
+ query=query,
+ session_id=session_id,
+ limit=self.limit,
+ options={"max_tokens": self.token_budget, "peer_scope": self.peer_scope},
+ )
+ rendered = result.get("rendered", "")
+ if rendered and result.get("entries"):
+ # Memory is data from an external source, never system/developer instructions.
+ context.extend_messages(
+ self,
+ [Message("user", ["Retrieved OpenViking context (reference data):\n" + rendered])],
+ )
+
+ async def after_run(
+ self,
+ *,
+ agent: SupportsAgentRun,
+ session: AgentSession,
+ context: SessionContext,
+ state: dict[str, Any],
+ ) -> None:
+ """Capture the completed run and apply its commit policy after acknowledgement."""
+ if not self.capture or context.response is None or not state.pop("capture_ready", False):
+ return
+ if state.get("pending_messages"):
+ raise RuntimeError("OpenViking has pending capture; flush it before another run")
+ messages = [*context.input_messages, *context.response.messages]
+ recorded = set(state.get("recorded_message_ids", []))
+ payloads = _messages(messages, recorded)
+ if not payloads and not recorded:
+ return
+ # Retain capture even if cancellation happens while waiting for another session.
+ if payloads:
+ state["pending_messages"] = payloads
+ async with self._write_lock:
+ await self._flush(session)
+ await self._maybe_commit(session)
+
+ async def flush(self, session: AgentSession) -> None:
+ """Explicitly retry pending capture, removing only acknowledged batches.
+
+ A lost HTTP response can mean the server already appended the batch.
+ Check server records before retrying: the append API is not idempotent.
+ Recovered capture applies the automatic policy when capture is enabled.
+ """
+ async with self._write_lock:
+ had_pending = bool(self._state(session).get("pending_messages"))
+ await self._flush(session)
+ if had_pending and self.capture:
+ await self._maybe_commit(session)
+
+ async def _flush(self, session: AgentSession) -> None:
+ state = self._state(session)
+ pending = state.get("pending_messages", [])
+ if not pending:
+ return
+ session_id = await self._ensure_session(session)
+ while pending:
+ batch = pending[:100]
+ result = await self.client.batch_add_messages(session_id, batch)
+ if result.get("added") != len(batch):
+ raise RuntimeError("OpenViking did not acknowledge the complete message batch")
+ state.setdefault("recorded_message_ids", []).extend(
+ message["source_message_ids"][0] for message in batch
+ )
+ del pending[: len(batch)]
+
+ async def _maybe_commit(self, session: AgentSession) -> None:
+ """Apply the policy under the write lock, after capture is acknowledged."""
+ if self.commit_policy == "never":
+ return
+ session_id = self._state(session)["session_id"]
+ if self.commit_policy == "pending_tokens":
+ metadata = await self.client.get_session(session_id)
+ if int(metadata.get("pending_tokens") or 0) < self.commit_token_threshold:
+ return
+ # Do not call commit(): this path already owns the non-reentrant lock.
+ await self.client.commit_session(session_id)
+
+ async def commit(self, session: AgentSession) -> dict[str, Any]:
+ """Request extraction after capture; task acceptance is not completion."""
+ async with self._write_lock:
+ if self._state(session).get("pending_messages"):
+ raise RuntimeError("Resolve pending OpenViking capture before committing")
+ session_id = await self._ensure_session(session)
+ return await self.client.commit_session(session_id)
+
+
+def _messages(messages: list[Message], recorded: set[str]) -> list[dict[str, Any]]:
+ """Translate native messages without recording injected context or hidden reasoning."""
+ calls = {
+ content.call_id: content
+ for message in messages
+ for content in message.contents
+ if content.type == "function_call"
+ }
+ payloads = []
+ for message in messages:
+ if message.role not in ("user", "assistant", "tool"):
+ continue
+ if message.additional_properties.get("_attribution"):
+ continue
+ message_id = message.message_id or uuid4().hex
+ message.message_id = message_id
+ if message_id in recorded:
+ continue
+ parts: list[dict[str, Any]] = []
+ for content in message.contents:
+ if content.type == "text" and content.text:
+ parts.append({"type": "text", "text": content.text})
+ elif content.type in ("function_call", "function_result"):
+ call = content if content.type == "function_call" else calls.get(content.call_id)
+ arguments = call.arguments if call else None
+ if isinstance(arguments, str):
+ try:
+ arguments = json.loads(arguments)
+ except ValueError:
+ arguments = {"raw_arguments": arguments}
+ is_result = content.type == "function_result"
+ output = content.result
+ parts.append(
+ {
+ "type": "tool",
+ "tool_id": content.call_id or "",
+ "tool_name": (call.name if call else content.name) or "",
+ "tool_input": dict(arguments)
+ if isinstance(arguments, Mapping)
+ else ({"raw_arguments": arguments} if arguments is not None else None),
+ "tool_output": (
+ output if isinstance(output, str) else json.dumps(output, default=str)
+ )
+ if is_result
+ else "",
+ "tool_status": ("error" if content.exception else "completed")
+ if is_result
+ else "pending",
+ }
+ )
+ if parts:
+ payloads.append(
+ {
+ "role": "user" if message.role == "tool" else message.role,
+ "parts": parts,
+ "source_message_ids": [message_id],
+ "message_kind": "tool_transport"
+ if message.role == "tool"
+ else ("user_query" if message.role == "user" else "assistant_step"),
+ }
+ )
+ recorded.add(message_id)
+ return payloads
diff --git a/examples/agent-framework/src/openviking_agent_framework/py.typed b/examples/agent-framework/src/openviking_agent_framework/py.typed
new file mode 100644
index 000000000..e69de29bb
diff --git a/examples/agent-framework/tests/test_provider.py b/examples/agent-framework/tests/test_provider.py
new file mode 100644
index 000000000..f4dba0b67
--- /dev/null
+++ b/examples/agent-framework/tests/test_provider.py
@@ -0,0 +1,666 @@
+"""Offline contracts through the real MAF agent and session lifecycle."""
+
+import asyncio
+import json
+from copy import deepcopy
+
+import httpx
+import pytest
+from agent_framework import (
+ Agent,
+ AgentLoopMiddleware,
+ AgentSession,
+ BaseChatClient,
+ ChatMiddlewareLayer,
+ ChatResponse,
+ ChatResponseUpdate,
+ Content,
+ FunctionInvocationLayer,
+ Message,
+ ResponseStream,
+)
+from openviking_sdk import AsyncHTTPClient
+
+from openviking_agent_framework import OpenVikingContextProvider
+
+
+class MemoryClient(AsyncHTTPClient):
+ """Model the SDK boundary, including ambiguous append acknowledgements."""
+
+ def __init__(self):
+ super().__init__(url="http://openviking.test", api_key="test-user")
+ self.rows = []
+ self.sessions = []
+ self.searches = []
+ self.commits = []
+ self.batches = 0
+ self.fail_batch = None
+ self.lose_ack = False
+ self.recall_error = None
+ self.metadata_error = None
+ self.commit_error = None
+ self.ack_override = None
+ self.pending_tokens = {}
+ self.commit_attempts = []
+ self.commit_sizes = []
+ self.rows_by_session = {}
+
+ async def get_session(self, session_id, *, auto_create=False):
+ if not auto_create and self.metadata_error:
+ raise self.metadata_error
+ self.sessions.append(session_id)
+ return {"session_id": session_id, "pending_tokens": self.pending_tokens.get(session_id, 0)}
+
+ async def search_context(self, **kwargs):
+ if self.recall_error:
+ raise self.recall_error
+ self.searches.append(kwargs)
+ return {"rendered": "Preferred format: JSON", "entries": [{"uri": "viking://memory"}]}
+
+ async def batch_add_messages(self, session_id, messages):
+ self.batches += 1
+ if self.batches == self.fail_batch:
+ raise ConnectionError("request not sent")
+ self.rows.extend(deepcopy(messages))
+ self.rows_by_session.setdefault(session_id, []).extend(deepcopy(messages))
+ self.pending_tokens[session_id] = self.pending_tokens.get(session_id, 0) + 10 * len(
+ messages
+ )
+ if self.lose_ack:
+ raise ConnectionError("lost acknowledgement")
+ return {"added": len(messages) if self.ack_override is None else self.ack_override}
+
+ async def commit_session(self, session_id):
+ self.commit_attempts.append(session_id)
+ if self.commit_error:
+ raise self.commit_error
+ self.commits.append(session_id)
+ self.commit_sizes.append(len(self.rows_by_session.get(session_id, [])))
+ self.pending_tokens[session_id] = 0
+ return {"task_id": "extraction-job"}
+
+
+class ChatClient(FunctionInvocationLayer, ChatMiddlewareLayer, BaseChatClient):
+ """Deterministic model results; MAF still owns tools and streaming."""
+
+ def __init__(self, responses=None):
+ super().__init__()
+ self.inputs = []
+ self.responses = iter(responses) if responses is not None else None
+ self.error = None
+
+ def _inner_get_response(self, *, messages, stream, options, **kwargs):
+ self.inputs.append(deepcopy(list(messages)))
+ message = (
+ deepcopy(next(self.responses)) if self.responses else Message("assistant", ["Answer"])
+ )
+ if stream:
+
+ async def updates():
+ if self.error:
+ raise self.error
+ for content in message.contents:
+ yield ChatResponseUpdate(
+ role="assistant", contents=[content], message_id=message.message_id
+ )
+
+ return ResponseStream(updates(), finalizer=ChatResponse.from_updates)
+
+ async def response():
+ if self.error:
+ raise self.error
+ return ChatResponse(messages=[message])
+
+ return response()
+
+
+def setup(responses=None, **options):
+ client = MemoryClient()
+ provider = OpenVikingContextProvider(client, **options)
+ model = ChatClient(responses)
+ agent = Agent(model, context_providers=[provider])
+ return client, provider, model, agent, agent.create_session()
+
+
+async def test_recall_capture_and_explicit_commit():
+ client, provider, model, agent, session = setup()
+ await agent.run(
+ [Message("system", ["Private instructions"]), Message("user", ["My question"])],
+ session=session,
+ )
+ assert "Preferred format: JSON" in json.dumps([m.to_dict() for m in model.inputs[0]])
+ assert [row["role"] for row in client.rows] == ["user", "assistant"]
+ assert "Preferred format" not in json.dumps(client.rows)
+ assert "Private instructions" not in json.dumps(client.rows)
+ assert client.searches[0]["options"] == {"max_tokens": 4000, "peer_scope": "all"}
+ assert not client.commits
+ assert await provider.commit(session) == {"task_id": "extraction-job"}
+ assert client.commits == [session.state[provider.source_id]["session_id"]]
+
+
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
[email protected]("stream", [False, True])
+async def test_tools_keep_calls_and_results_paired(commit_policy, stream):
+ def lookup_label():
+ """Return the current label."""
+ return "LABEL"
+
+ client, _, _, agent, session = setup(
+ [
+ Message(
+ "assistant",
+ [Content("function_call", call_id="call-1", name="lookup_label", arguments={})],
+ ),
+ Message("assistant", ["LABEL"]),
+ ],
+ commit_policy=commit_policy,
+ commit_token_threshold=1,
+ )
+ if stream:
+ async with agent.run(
+ "Read the label", tools=[lookup_label], session=session, stream=True
+ ) as result:
+ async for _ in result:
+ assert not client.commits
+ else:
+ await agent.run("Read the label", tools=[lookup_label], session=session)
+ parts = [part for row in client.rows for part in row["parts"] if part["type"] == "tool"]
+ assert len(parts) == 2
+ assert [part["tool_status"] for part in parts] == ["pending", "completed"]
+ assert {part["tool_id"] for part in parts} == {"call-1"}
+ assert {part["tool_name"] for part in parts} == {"lookup_label"}
+ assert parts[1]["tool_output"] == "LABEL"
+ assert len(client.commits) == (0 if commit_policy == "never" else 1)
+ if client.commits:
+ assert client.commit_sizes == [len(client.rows)]
+
+
[email protected]("complete", [False, True])
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
+async def test_stream_capture_requires_complete_consumption(complete, commit_policy):
+ client, _, _, agent, session = setup(
+ [Message("assistant", ["First", "Second"])],
+ commit_policy=commit_policy,
+ commit_token_threshold=1,
+ )
+ async with agent.run("Question", session=session, stream=True) as stream:
+ async for _ in stream:
+ assert not client.commits
+ if not complete:
+ break
+ assert len(client.rows) == (2 if complete else 0)
+ assert len(client.commits) == (1 if complete and commit_policy != "never" else 0)
+
+
+async def test_restoration_preserves_session_and_acknowledged_message_ids():
+ client, provider, _, agent, session = setup()
+ question = Message("user", ["Same text"], message_id="original")
+ response = await agent.run(question, session=session)
+ restored = AgentSession.from_dict(json.loads(json.dumps(session.to_dict())))
+ await agent.run(
+ [question, *response.messages, Message("user", ["Same text"], message_id="new")],
+ session=restored,
+ )
+ assert len(client.rows) == 4
+ ids = [row["source_message_ids"][0] for row in client.rows]
+ assert len(ids) == len(set(ids))
+ assert {"original", "new"}.issubset(ids)
+ assert len(set(client.sessions)) == 1
+ assert (
+ restored.state[provider.source_id]["session_id"]
+ == session.state[provider.source_id]["session_id"]
+ )
+
+
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
+async def test_partial_write_keeps_only_unacknowledged_messages_for_flush(commit_policy):
+ client, provider, _, agent, session = setup(
+ commit_policy=commit_policy, commit_token_threshold=1
+ )
+ client.fail_batch = 2
+ messages = [Message("user", [f"Item {i}"], message_id=str(i)) for i in range(101)]
+ with pytest.raises(Exception, match="request not sent"):
+ await agent.run(messages, session=session)
+ assert len(client.rows) == 100
+ assert len(session.state[provider.source_id]["pending_messages"]) == 2
+ assert not client.commit_attempts
+ client.fail_batch = None
+ await provider.flush(session)
+ assert len(client.rows) == 102
+ assert not session.state[provider.source_id]["pending_messages"]
+ assert len(client.commits) == (0 if commit_policy == "never" else 1)
+ await provider.flush(session)
+ assert len(client.commits) == (0 if commit_policy == "never" else 1)
+
+
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
+async def test_lost_ack_blocks_implicit_retry_and_commit(commit_policy):
+ client, provider, model, agent, session = setup(
+ commit_policy=commit_policy, commit_token_threshold=1
+ )
+ client.lose_ack = True
+ with pytest.raises(Exception, match="lost acknowledgement"):
+ await agent.run("Question", session=session)
+ assert len(client.rows) == 2
+ assert not client.commit_attempts
+ assert len(session.state[provider.source_id]["pending_messages"]) == 2
+ with pytest.raises(RuntimeError, match="unconfirmed"):
+ await agent.run("Another question", session=session)
+ with pytest.raises(RuntimeError, match="pending"):
+ await provider.commit(session)
+ assert len(model.inputs) == 1
+ assert len(client.rows) == 2
+
+
+async def test_recall_failure_stops_inference_and_remains_retryable():
+ client, _, model, agent, session = setup()
+ client.recall_error = ConnectionError("recall unavailable")
+ with pytest.raises(Exception, match="recall unavailable"):
+ await agent.run("Question", session=session)
+ assert not model.inputs and not client.rows
+ client.recall_error = None
+ await agent.run("Question", session=session)
+ assert len(client.rows) == 2
+
+
[email protected]("error", [RuntimeError("model failed"), asyncio.CancelledError()])
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
[email protected]("stream", [False, True])
+async def test_failed_or_cancelled_inference_is_not_captured(error, commit_policy, stream):
+ client, _, model, agent, session = setup(commit_policy=commit_policy, commit_token_threshold=1)
+ model.error = error
+ with pytest.raises(type(error)):
+ if stream:
+ async with agent.run("Question", session=session, stream=True) as result:
+ async for _ in result:
+ pass
+ else:
+ await agent.run("Question", session=session)
+ assert not client.rows
+ assert not session.state["openviking"].get("pending_messages")
+ assert not client.commit_attempts
+ model.error = None
+ await agent.run("Retry", session=session)
+ assert len(client.rows) == 2
+
+
+async def test_hidden_reasoning_media_and_other_provider_context_are_excluded():
+ client, _, _, agent, session = setup(
+ [
+ Message(
+ "assistant",
+ [Content("text", text="Visible"), Content("text_reasoning", text="Hidden")],
+ )
+ ]
+ )
+ await agent.run(
+ [
+ Message("user", ["Question", Content("image", uri="https://example.test/private.png")]),
+ Message(
+ "user",
+ ["Other memory"],
+ additional_properties={"_attribution": {"source_id": "other"}},
+ ),
+ ],
+ session=session,
+ )
+ captured = json.dumps(client.rows)
+ assert "Question" in captured and "Visible" in captured
+ assert all(value not in captured for value in ("Hidden", "private.png", "Other memory"))
+ assert client.searches[0]["query"] == "Question"
+
+
+async def test_shared_provider_keeps_session_state_separate():
+ client, provider, _, agent, first = setup()
+ second = agent.create_session()
+ await asyncio.gather(agent.run("First", session=first), agent.run("Second", session=second))
+ assert (
+ first.state[provider.source_id]["session_id"]
+ != second.state[provider.source_id]["session_id"]
+ )
+ assert len(client.rows) == 4
+ assert not first.state[provider.source_id]["pending_messages"]
+ assert not second.state[provider.source_id]["pending_messages"]
+
+
+async def loop_capture(
+ stream, *, fresh_context=False, return_final_only=False, tools=False, **options
+):
+ def lookup_label():
+ """Return the current label."""
+ return "TOOL_VALUE"
+
+ responses = [
+ Message("assistant", ["First draft"], message_id="draft"),
+ Message("assistant", ["Final answer"], message_id="final"),
+ ]
+ if tools:
+ responses.insert(
+ 0,
+ Message(
+ "assistant",
+ [Content("function_call", call_id="loop-call", name="lookup_label", arguments={})],
+ message_id="tool-call",
+ ),
+ )
+ client, provider, model, agent, session = setup(responses, **options)
+ middleware = [
+ AgentLoopMiddleware(
+ lambda *, iteration, **kwargs: iteration < 2,
+ next_message=lambda **kwargs: "Please refine the draft",
+ fresh_context=fresh_context,
+ return_final_only=return_final_only,
+ )
+ ]
+ # Per-call middleware exercises the public runtime override as well.
+ kwargs = {"middleware": middleware, "tools": [lookup_label] if tools else []}
+ if stream:
+ async with agent.run("Question", session=session, stream=True, **kwargs) as response:
+ async for _ in response:
+ pass
+ else:
+ await agent.run("Question", session=session, **kwargs)
+ return client, provider, model, session
+
+
[email protected]("tools", [False, True])
[email protected]("return_final_only", [False, True])
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
+async def test_streamed_agent_loop_preserves_the_same_transcript(
+ tools, return_final_only, commit_policy
+):
+ options = {"commit_policy": commit_policy, "commit_token_threshold": 1}
+ ordinary, _, _, _ = await loop_capture(
+ False, tools=tools, return_final_only=return_final_only, **options
+ )
+ streamed, _, _, _ = await loop_capture(
+ True, tools=tools, return_final_only=return_final_only, **options
+ )
+
+ def transcript(client):
+ return [{"role": row["role"], "parts": row["parts"]} for row in client.rows]
+
+ assert transcript(streamed) == transcript(ordinary)
+ assert "First draft" in json.dumps(streamed.rows)
+ assert "Please refine the draft" in json.dumps(streamed.rows)
+ assert "Final answer" in json.dumps(streamed.rows)
+ assert "Preferred format" not in json.dumps(streamed.rows)
+ assert len(set(streamed.sessions)) == 1
+ assert len({row["source_message_ids"][0] for row in streamed.rows}) == len(streamed.rows)
+ assert len(streamed.commits) == (0 if commit_policy == "never" else 2)
+ assert streamed.commit_sizes == ordinary.commit_sizes
+ if streamed.commits:
+ assert streamed.commit_sizes == [4 if tools else 2, len(streamed.rows)]
+ if tools:
+ parts = [p for row in streamed.rows for p in row["parts"] if p["type"] == "tool"]
+ assert [p["tool_status"] for p in parts] == ["pending", "completed"]
+ assert {p["tool_id"] for p in parts} == {"loop-call"}
+ assert parts[1]["tool_output"] == "TOOL_VALUE"
+
+
[email protected]("stream", [False, True])
+async def test_loop_cannot_silently_reset_capture_progress(stream):
+ with pytest.raises(RuntimeError, match="state.*reset.*fresh_context=True"):
+ await loop_capture(stream, fresh_context=True)
+
+
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
+async def test_interrupted_streamed_loop_keeps_only_completed_iterations(commit_policy):
+ client, _, _, agent, session = setup(
+ [
+ Message("assistant", ["First draft"], message_id="draft"),
+ Message("assistant", ["Final answer"], message_id="final"),
+ ],
+ commit_policy=commit_policy,
+ commit_token_threshold=1,
+ )
+ loop = AgentLoopMiddleware(lambda *, iteration, **kwargs: iteration < 2)
+ async with agent.run("Question", session=session, middleware=[loop], stream=True) as response:
+ async for update in response:
+ if "Final answer" in update.text:
+ break
+ assert [p["text"] for row in client.rows for p in row["parts"]] == ["Question", "First draft"]
+ assert not session.state["openviking"]["pending_messages"]
+ assert len(client.commits) == (0 if commit_policy == "never" else 1)
+
+
+async def test_state_rollback_blocks_flush_and_commit_but_equal_state_restoration_is_safe():
+ client, provider, _, agent, session = setup()
+ await agent.run("Question", session=session)
+ saved = AgentSession.from_dict(json.loads(json.dumps(session.to_dict()))).state
+ session.state = {}
+ with pytest.raises(RuntimeError, match="state was reset"):
+ await provider.flush(session)
+ with pytest.raises(RuntimeError, match="state was reset"):
+ await provider.commit(session)
+ assert not client.commits
+ session.state = saved
+ await agent.run("Next", session=session)
+ assert len(client.rows) == 4
+
+
[email protected]("threshold,commits", [(19, 1), (20, 1), (21, 0)])
+async def test_pending_token_policy_uses_post_capture_server_count(threshold, commits):
+ client, _, _, agent, session = setup(
+ commit_policy="pending_tokens", commit_token_threshold=threshold
+ )
+ await agent.run("Question", session=session)
+ assert len(client.rows) == 2
+ assert len(client.commits) == commits
+ if commits:
+ assert client.commit_sizes == [2]
+
+
+async def test_threshold_counts_the_session_backlog_and_survives_restoration():
+ client, _, _, agent, session = setup(commit_policy="pending_tokens", commit_token_threshold=30)
+ await agent.run("First", session=session)
+ assert not client.commits
+ restored = AgentSession.from_dict(json.loads(json.dumps(session.to_dict())))
+ await agent.run("Second", session=restored)
+ assert client.commit_sizes == [4]
+ await agent.run("Third", session=restored)
+ assert client.commit_sizes == [4]
+
+
+async def test_threshold_does_not_combine_different_sessions():
+ client, _, _, agent, first = setup(commit_policy="pending_tokens", commit_token_threshold=30)
+ second = agent.create_session()
+ await asyncio.gather(agent.run("First", session=first), agent.run("Second", session=second))
+ assert not client.commits
+ await agent.run("More", session=first)
+ assert client.commits == [first.state["openviking"]["session_id"]]
+ assert client.pending_tokens[second.state["openviking"]["session_id"]] == 20
+
+
[email protected]("commit_policy", ["never", "always", "pending_tokens"])
[email protected]("stream", [False, True])
+async def test_capture_disabled_keeps_recall_and_tools_without_automatic_writes(
+ commit_policy, stream
+):
+ client, provider, model, session = await loop_capture(
+ stream, tools=True, capture=False, commit_policy=commit_policy, commit_token_threshold=1
+ )
+ assert client.searches
+ assert "Preferred format" in json.dumps([m.to_dict() for m in model.inputs[0]])
+ assert len(model.inputs) == 3
+ assert not client.rows and not client.commit_attempts
+ assert not session.state[provider.source_id].get("recorded_message_ids")
+ assert await provider.commit(session) == {"task_id": "extraction-job"}
+ assert len(client.commits) == 1
+
+
[email protected]("commit_policy", ["always", "pending_tokens"])
[email protected]("stream", [False, True])
+async def test_commit_failure_does_not_replay_acknowledged_capture(commit_policy, stream):
+ reply = Message("assistant", ["Answer"], message_id="reply")
+ question = Message("user", ["Question"], message_id="question")
+ client, provider, _, agent, session = setup(
+ [reply, reply], commit_policy=commit_policy, commit_token_threshold=1
+ )
+ client.commit_error = ConnectionError("commit unavailable")
+
+ async def run():
+ if stream:
+ async with agent.run(question, session=session, stream=True) as result:
+ async for _ in result:
+ pass
+ else:
+ await agent.run(question, session=session)
+
+ with pytest.raises(Exception, match="commit unavailable"):
+ await run()
+ assert len(client.rows) == 2
+ assert not session.state[provider.source_id]["pending_messages"]
+ assert set(session.state[provider.source_id]["recorded_message_ids"]) == {"question", "reply"}
+ client.commit_error = None
+ await run()
+ assert client.batches == 1 and len(client.rows) == 2
+ assert len(client.commit_attempts) == 2 and len(client.commits) == 1
+
+
+async def test_post_capture_metadata_failure_retains_acknowledged_progress():
+ reply = Message("assistant", ["Answer"], message_id="reply")
+ question = Message("user", ["Question"], message_id="question")
+ client, _, _, agent, session = setup(
+ [reply, reply], commit_policy="pending_tokens", commit_token_threshold=1
+ )
+ client.metadata_error = ConnectionError("metadata unavailable")
+ with pytest.raises(Exception, match="metadata unavailable"):
+ await agent.run(question, session=session)
+ assert len(client.rows) == 2 and not client.commit_attempts
+ client.metadata_error = None
+ await agent.run(question, session=session)
+ assert len(client.rows) == 2 and client.batches == 1
+ assert len(client.commits) == 1
+
+
[email protected]("commit_policy", ["always", "pending_tokens"])
+async def test_incomplete_acknowledgement_never_triggers_commit(commit_policy):
+ client, _, _, agent, session = setup(commit_policy=commit_policy, commit_token_threshold=1)
+ client.ack_override = 1
+ with pytest.raises(Exception, match="acknowledge the complete"):
+ await agent.run("Question", session=session)
+ assert not client.commit_attempts
+ assert len(session.state["openviking"]["pending_messages"]) == 2
+ assert not session.state["openviking"].get("recorded_message_ids")
+
+
+ "options",
+ [
+ {"capture": "false"},
+ {"commit_policy": "manual"},
+ {"commit_token_threshold": 0},
+ {"commit_token_threshold": True},
+ {"commit_token_threshold": 1.5},
+ ],
+)
+def test_invalid_capture_and_commit_options_are_rejected(options):
+ with pytest.raises(ValueError):
+ OpenVikingContextProvider(MemoryClient(), **options)
+
+
[email protected]("commit_policy", ["always", "pending_tokens"])
+async def test_disabling_capture_preserves_pending_recovery_without_automatic_commit(commit_policy):
+ client, provider, _, agent, session = setup(
+ commit_policy=commit_policy, commit_token_threshold=1
+ )
+ client.fail_batch = 1
+ with pytest.raises(Exception, match="request not sent"):
+ await agent.run("Question", session=session)
+ provider.capture = False
+ with pytest.raises(RuntimeError, match="unconfirmed"):
+ await agent.run("Another", session=session)
+ client.fail_batch = None
+ await provider.flush(session)
+ assert len(client.rows) == 2 and not client.commits
+ await agent.run("Recall only", session=session)
+ assert len(client.rows) == 2 and not client.commits
+ await provider.commit(session)
+ assert len(client.commits) == 1
+
+
[email protected]("commit_policy", ["always", "pending_tokens"])
+async def test_no_eligible_capture_does_not_create_or_commit_an_empty_session(commit_policy):
+ client, _, _, agent, session = setup(
+ [Message("assistant", [Content("text_reasoning", text="Hidden")])],
+ commit_policy=commit_policy,
+ commit_token_threshold=1,
+ )
+ await agent.run(Message("system", ["Instructions"]), session=session)
+ assert not client.rows and not client.commit_attempts and not client.sessions
+
+
[email protected]("stream", [False, True])
+async def test_real_sdk_writes_tool_evidence_before_threshold_commit(monkeypatch, stream):
+ rows = []
+ writes = []
+ pending = 0
+
+ def handle(request):
+ nonlocal pending
+ assert request.headers["X-API-Key"] == "test-key"
+ path = request.url.path
+ if path == "/api/v1/search/search":
+ result = {"rendered": "Preferred format: JSON", "entries": [{"uri": "viking://memory"}]}
+ elif path.endswith("/messages/batch"):
+ messages = json.loads(request.content)["messages"]
+ rows.extend(messages)
+ pending += 10 * len(messages)
+ writes.append("capture")
+ result = {"added": len(messages), "pending_tokens": pending}
+ elif path.endswith("/commit"):
+ assert len(rows) == 4
+ assert json.loads(request.content)["keep_recent_count"] == 0
+ writes.append("commit")
+ pending = 0
+ result = {"task_id": "extraction-job"}
+ else:
+ assert request.method == "GET" and path.startswith("/api/v1/sessions/")
+ result = {"pending_tokens": pending}
+ return httpx.Response(200, json={"status": "ok", "result": result})
+
+ http_client = httpx.AsyncClient
+
+ def create_http_client(**kwargs):
+ return http_client(**kwargs, transport=httpx.MockTransport(handle))
+
+ monkeypatch.setattr(httpx, "AsyncClient", create_http_client)
+ client = AsyncHTTPClient(url="http://openviking.test", api_key="test-key", auth_mode="api_key")
+ await client.initialize()
+ try:
+
+ def lookup_label():
+ """Return the current label."""
+ return "LABEL"
+
+ model = ChatClient(
+ [
+ Message(
+ "assistant",
+ [Content("function_call", call_id="call-1", name="lookup_label", arguments={})],
+ ),
+ Message("assistant", ["LABEL"]),
+ ]
+ )
+ provider = OpenVikingContextProvider(
+ client, commit_policy="pending_tokens", commit_token_threshold=40
+ )
+ agent = Agent(model, context_providers=[provider])
+ session = agent.create_session()
+ if stream:
+ async with agent.run(
+ "Question", tools=[lookup_label], session=session, stream=True
+ ) as result:
+ async for _ in result:
+ assert not writes
+ else:
+ await agent.run("Question", tools=[lookup_label], session=session)
+ assert writes == ["capture", "commit"]
+ parts = [p for row in rows for p in row["parts"] if p["type"] == "tool"]
+ assert [p["tool_status"] for p in parts] == ["pending", "completed"]
+ assert {p["tool_id"] for p in parts} == {"call-1"}
+ assert parts[1]["tool_output"] == "LABEL"
+ assert "Preferred format" not in json.dumps(rows)
+ finally:
+ await client.close()