Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
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
The distribution is named openviking-ms-agent-framework and imports as
openviking_agent_framework.
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 a released version from PyPI:
pip install openviking-ms-agent-framework
For an unreleased version, or to run the repository example, install from an OpenViking checkout with the optional model client:
pip install './integrations/frameworks/microsoft-agent-framework[example]'
Set OPENVIKING_URL, OPENVIKING_API_KEY (a normal user key), OPENAI_API_KEY,
OPENAI_BASE_URL, and OPENAI_MODEL, then run:
python integrations/frameworks/microsoft-agent-framework/examples/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:
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
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 withAgentSession.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
AgentLoopMiddlewareiteration, 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=Truerolls 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 bysource_message_idsbefore 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
pip install -e './integrations/frameworks/microsoft-agent-framework[test,dev]'
cd integrations/frameworks/microsoft-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.
See the framework adapter guide for adding other integrations. The adapter is licensed under MIT; see LICENSE. The runnable example retains Apache-2.0.