Skip to content

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

feat(langchain): support request-scoped actor peers (#3626)

Hao Zhec1d38eb47ff2
diff --git a/docs/en/agent-integrations/07-langchain-langgraph.md b/docs/en/agent-integrations/07-langchain-langgraph.md
index 9a8d3f5c3..9f0e1d051 100644
--- a/docs/en/agent-integrations/07-langchain-langgraph.md
+++ b/docs/en/agent-integrations/07-langchain-langgraph.md
@@ -158,6 +158,47 @@ chain.invoke(
)
```
+### Runtime actor peers for concurrent agents
+
+`OpenVikingContextMiddleware` can resolve the active actor peer from each
+LangGraph run while reusing its credential-bound HTTP clients:
+
+```python
+from openviking.integrations.langchain import OpenVikingContextMiddleware
+
+
+def resolve_actor_peer(_state, runtime):
+ context = runtime.context or {}
+ return context.get("actor_peer_id")
+
+
+middleware = OpenVikingContextMiddleware(
+ url="http://localhost:1933",
+ api_key="user-api-key",
+ actor_peer_resolver=resolve_actor_peer,
+)
+```
+
+The resolved actor peer scopes OpenViking HTTP calls made during recall and
+capture. Concurrent runs are isolated, and middleware capture progress is keyed
+by actor peer as well as session and message peer. OpenViking session endpoints
+remain user-scoped and do not use the actor-peer header for message attribution;
+set `peer_id_resolver` as well when captured messages must be attributed to the
+same logical peer. Distinct peers with independent histories should also resolve
+distinct session IDs. When `actor_peer_resolver` is omitted, the existing fixed
+client behavior is unchanged.
+
+The resolver cannot change the OpenViking account or user. Those identities
+remain bound to the API key or OAuth credential, so multi-user applications
+must select a credential-bound client before invoking the middleware. Resolve
+the actor peer only from authenticated, server-owned runtime fields; do not
+trust model state or client-controlled configurable values. Runtime actor-peer
+resolution is available only for HTTP-backed middleware, not embedded `path=`
+clients. An injected custom client must set
+`supports_request_actor_peer = True` and honor the `openviking_sdk` actor-peer
+scope. Upgrade `openviking-sdk` together with `openviking` before enabling this
+feature in an existing environment.
+
## Which adapter should I use?
| I want to… | Use this |
diff --git a/docs/zh/agent-integrations/07-langchain-langgraph.md b/docs/zh/agent-integrations/07-langchain-langgraph.md
index 2269b8f45..182551ad0 100644
--- a/docs/zh/agent-integrations/07-langchain-langgraph.md
+++ b/docs/zh/agent-integrations/07-langchain-langgraph.md
@@ -148,6 +148,42 @@ chain.invoke(
)
```
+### 并发 Agent 的运行时 Actor Peer
+
+`OpenVikingContextMiddleware` 可以在复用绑定凭证的 HTTP client 时,从每次
+LangGraph 运行中解析当前 actor peer:
+
+```python
+from openviking.integrations.langchain import OpenVikingContextMiddleware
+
+
+def resolve_actor_peer(_state, runtime):
+ context = runtime.context or {}
+ return context.get("actor_peer_id")
+
+
+middleware = OpenVikingContextMiddleware(
+ url="http://localhost:1933",
+ api_key="user-api-key",
+ actor_peer_resolver=resolve_actor_peer,
+)
+```
+
+解析出的 actor peer 会作用于召回和捕获期间发出的 OpenViking HTTP 请求。并发运行
+互相隔离,middleware 的捕获进度也会按 actor peer、session 和 message peer 共同
+隔离。OpenViking 的 Session 接口仍然以 user 为作用域,不会使用 actor-peer header
+标记消息归属;如果捕获的消息也需要归属于同一个逻辑 peer,应同时设置
+`peer_id_resolver`。拥有独立历史的不同 peer 也应解析为不同的 session ID。未传入
+`actor_peer_resolver` 时,现有固定 client 行为保持不变。
+
+该 resolver 不能改变 OpenViking account 或 user;这些身份继续由 API Key 或 OAuth
+凭证决定。因此,多用户应用必须先选择绑定对应用户凭证的 client,再调用 middleware。
+Actor peer 只能从已经认证、由服务端控制的 runtime 字段中解析;不要信任 model state
+或客户端可控的 configurable 值。运行时 actor-peer 解析仅支持 HTTP-backed
+middleware,不支持 embedded `path=` client。注入的自定义 client 必须设置
+`supports_request_actor_peer = True`,并遵循 `openviking_sdk` 的 actor-peer
+作用域。在已有环境中启用该能力前,应同时升级 `openviking-sdk` 和 `openviking`。
+
## 选哪个适配器?
| 我想… | 用这个 |
diff --git a/openviking/integrations/langchain/__init__.py b/openviking/integrations/langchain/__init__.py
index 5f9d97217..dde70bfa9 100644
--- a/openviking/integrations/langchain/__init__.py
+++ b/openviking/integrations/langchain/__init__.py
@@ -10,6 +10,10 @@ from __future__ import annotations
from typing import Any
+from openviking.integrations.langchain.actor_peer import (
+ has_request_actor_peer_support,
+)
+
__all__ = [
"InMemoryOpenVikingClient",
"OpenVikingChatMessageHistory",
@@ -25,6 +29,7 @@ __all__ = [
"OpenVikingStore",
"create_openviking_tools",
"get_openviking_cancellation_progress",
+ "has_request_actor_peer_support",
"with_openviking_context",
]
diff --git a/openviking/integrations/langchain/actor_peer.py b/openviking/integrations/langchain/actor_peer.py
new file mode 100644
index 000000000..dd6bdd81f
--- /dev/null
+++ b/openviking/integrations/langchain/actor_peer.py
@@ -0,0 +1,49 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Compatibility bridge for request-scoped actor peers in openviking-sdk."""
+
+from __future__ import annotations
+
+from contextlib import AbstractContextManager
+from typing import Callable, cast
+
+from openviking._sdk_import import import_openviking_sdk
+
+_openviking_sdk = import_openviking_sdk()
+_actor_peer_getter = getattr(_openviking_sdk, "get_actor_peer_id", None)
+_actor_peer_scope = getattr(_openviking_sdk, "use_actor_peer", None)
+
+
+def has_request_actor_peer_support() -> bool:
+ """Return whether the installed SDK supports request-scoped actor peers."""
+
+ return _actor_peer_getter is not None and _actor_peer_scope is not None
+
+
+def require_request_actor_peer_support() -> None:
+ """Raise an actionable error when request-scoped actor peers are unavailable."""
+
+ if not has_request_actor_peer_support():
+ raise ImportError(
+ "Runtime actor peers require an openviking-sdk release with "
+ "request-scoped actor-peer support. Upgrade openviking-sdk and retry."
+ )
+
+
+def get_actor_peer_id() -> str | None:
+ """Return the active SDK actor peer, tolerating older SDKs when unused."""
+
+ if _actor_peer_getter is None:
+ return None
+ return cast(Callable[[], str | None], _actor_peer_getter)()
+
+
+def use_actor_peer(actor_peer_id: str | None) -> AbstractContextManager[None]:
+ """Apply an SDK actor-peer scope after confirming SDK support."""
+
+ require_request_actor_peer_support()
+ scope_factory = cast(
+ Callable[[str | None], AbstractContextManager[None]],
+ _actor_peer_scope,
+ )
+ return scope_factory(actor_peer_id)
diff --git a/openviking/integrations/langchain/client.py b/openviking/integrations/langchain/client.py
index 6ddb8bc6b..35be0442a 100644
--- a/openviking/integrations/langchain/client.py
+++ b/openviking/integrations/langchain/client.py
@@ -113,6 +113,12 @@ class OpenVikingClientHandle:
self._client: Any = None
self._client_lock = threading.Lock()
+ @property
+ def supports_request_actor_peer(self) -> bool:
+ """Return whether this handle supports request-scoped actor peers."""
+
+ return _uses_http_client(self._connection)
+
@property
def _initialized(self) -> bool:
client = self._client
@@ -209,6 +215,12 @@ class OpenVikingAsyncClientHandle:
except RuntimeError:
self._loop = None
+ @property
+ def supports_request_actor_peer(self) -> bool:
+ """Return whether this handle supports request-scoped actor peers."""
+
+ return _uses_http_client(self._connection)
+
@property
def _initialized(self) -> bool:
client = self._client
diff --git a/openviking/integrations/langchain/middleware.py b/openviking/integrations/langchain/middleware.py
index 75c6e93ea..794f88262 100644
--- a/openviking/integrations/langchain/middleware.py
+++ b/openviking/integrations/langchain/middleware.py
@@ -6,6 +6,7 @@ from __future__ import annotations
import asyncio
import json
+from contextlib import AbstractContextManager, nullcontext
from dataclasses import dataclass
from typing import Any, Callable
@@ -24,6 +25,11 @@ except ImportError as exc: # pragma: no cover - exercised by optional import pa
raise missing_dependency("langgraph", "langchain/langgraph") from exc
+from openviking.integrations.langchain.actor_peer import (
+ get_actor_peer_id,
+ require_request_actor_peer_support,
+ use_actor_peer,
+)
from openviking.integrations.langchain.client import (
OpenVikingCommitPolicy,
extract_message_text,
@@ -46,13 +52,19 @@ _SESSION_ID_ERROR = (
'config={"configurable": {"thread_id": "..."}}, set state["session_id"], '
"or provide session_id_resolver."
)
+_CaptureKey = tuple[str, str] | tuple[str, str, str]
+_ActorPeerResolver = Callable[
+ [dict[str, Any], Any],
+ str | None,
+]
@dataclass(slots=True)
class _CapturePlan:
session_id: str
peer_id: str | None
- key: tuple[str, str]
+ actor_peer_id: str | None
+ key: _CaptureKey
messages: list[Any]
signatures: tuple[str, ...]
start: int
@@ -88,6 +100,7 @@ class OpenVikingContextMiddleware(AgentMiddleware):
token_budget: int = 128_000,
session_id_resolver: Callable[[dict[str, Any], Any], str] | None = None,
peer_id_resolver: Callable[[dict[str, Any], Any], str | None] | None = None,
+ actor_peer_resolver: _ActorPeerResolver | None = None,
capture_on_after_agent: bool = True,
commit_on_after_agent: bool = False,
commit_policy: OpenVikingCommitPolicy | None = None,
@@ -95,6 +108,13 @@ class OpenVikingContextMiddleware(AgentMiddleware):
include_active_messages: bool = False,
):
super().__init__()
+ _validate_actor_peer_transport(
+ actor_peer_resolver=actor_peer_resolver,
+ client=client,
+ async_client=async_client,
+ retriever=retriever,
+ path=path,
+ )
self.recorder = OpenVikingSessionRecorder(
client=client,
async_client=async_client,
@@ -146,13 +166,14 @@ class OpenVikingContextMiddleware(AgentMiddleware):
self.session_id_resolver = session_id_resolver
self.peer_id = peer_id
self.peer_id_resolver = peer_id_resolver
+ self.actor_peer_resolver = actor_peer_resolver
self.capture_on_after_agent = capture_on_after_agent
self.commit_policy = commit_policy
if commit_on_after_agent and self.commit_policy is None:
self.commit_policy = OpenVikingCommitPolicy(mode="always")
self.recall_header = recall_header
- self._captured_signatures: dict[tuple[str, str], tuple[str, ...]] = {}
- self._pending_context_parts: dict[tuple[str, str], list[dict[str, Any]]] = {}
+ self._captured_signatures: dict[_CaptureKey, tuple[str, ...]] = {}
+ self._pending_context_parts: dict[_CaptureKey, list[dict[str, Any]]] = {}
async def aclose(self) -> None:
"""Release all clients internally owned by this middleware."""
@@ -174,11 +195,12 @@ class OpenVikingContextMiddleware(AgentMiddleware):
plan = self._model_context_plan(request)
if plan is None:
return handler(request)
- session_id, pending_key, query = plan
- assembled = self.assembler.assemble(
- session_id=session_id,
- query=query,
- )
+ session_id, pending_key, query, actor_peer_id = plan
+ with self._actor_peer_scope(actor_peer_id):
+ assembled = self.assembler.assemble(
+ session_id=session_id,
+ query=query,
+ )
updated_request = self._request_with_context(request, pending_key, assembled)
if updated_request is None:
return handler(request)
@@ -198,11 +220,12 @@ class OpenVikingContextMiddleware(AgentMiddleware):
plan = self._model_context_plan(request)
if plan is None:
return await handler(request)
- session_id, pending_key, query = plan
- assembled = await self.assembler.aassemble(
- session_id=session_id,
- query=query,
- )
+ session_id, pending_key, query, actor_peer_id = plan
+ with self._actor_peer_scope(actor_peer_id):
+ assembled = await self.assembler.aassemble(
+ session_id=session_id,
+ query=query,
+ )
updated_request = self._request_with_context(request, pending_key, assembled)
if updated_request is None:
return await handler(request)
@@ -217,7 +240,7 @@ class OpenVikingContextMiddleware(AgentMiddleware):
def _model_context_plan(
self,
request: ModelRequest,
- ) -> tuple[str, tuple[str, str], str] | None:
+ ) -> tuple[str, _CaptureKey, str, str | None] | None:
query = get_latest_user_text(request.messages)
if not query:
return None
@@ -225,14 +248,15 @@ class OpenVikingContextMiddleware(AgentMiddleware):
runtime = getattr(request, "runtime", None)
session_id = self._resolve_session_id(state, runtime)
peer_id = self._resolve_peer_id(state, runtime)
- pending_key = _capture_key(session_id, peer_id)
+ actor_peer_id = self._resolve_actor_peer_id(state, runtime)
+ pending_key = _capture_key(session_id, peer_id, actor_peer_id)
self._pending_context_parts.pop(pending_key, None)
- return session_id, pending_key, query
+ return session_id, pending_key, query, actor_peer_id
def _request_with_context(
self,
request: ModelRequest,
- pending_key: tuple[str, str],
+ pending_key: _CaptureKey,
assembled: OpenVikingAssembledContext,
) -> ModelRequest | None:
context_block = assembled.block
@@ -255,16 +279,18 @@ class OpenVikingContextMiddleware(AgentMiddleware):
return None
self.recorder.commit_policy = self.commit_policy
if plan.unchanged:
- self.recorder.record(plan.session_id, ())
+ with self._actor_peer_scope(plan.actor_peer_id):
+ self.recorder.record(plan.session_id, ())
self._pending_context_parts.pop(plan.key, None)
return None
try:
- result = self.recorder.record(
- plan.session_id,
- plan.messages[plan.start :],
- peer_id=plan.peer_id,
- context_parts=plan.context_parts,
- )
+ with self._actor_peer_scope(plan.actor_peer_id):
+ result = self.recorder.record(
+ plan.session_id,
+ plan.messages[plan.start :],
+ peer_id=plan.peer_id,
+ context_parts=plan.context_parts,
+ )
except OpenVikingPartialWriteError as exc:
self._handle_partial_capture(plan, exc)
raise
@@ -284,16 +310,18 @@ class OpenVikingContextMiddleware(AgentMiddleware):
return None
self.recorder.commit_policy = self.commit_policy
if plan.unchanged:
- await self.recorder.arecord(plan.session_id, ())
+ with self._actor_peer_scope(plan.actor_peer_id):
+ await self.recorder.arecord(plan.session_id, ())
self._pending_context_parts.pop(plan.key, None)
return None
try:
- result = await self.recorder.arecord(
- plan.session_id,
- plan.messages[plan.start :],
- peer_id=plan.peer_id,
- context_parts=plan.context_parts,
- )
+ with self._actor_peer_scope(plan.actor_peer_id):
+ result = await self.recorder.arecord(
+ plan.session_id,
+ plan.messages[plan.start :],
+ peer_id=plan.peer_id,
+ context_parts=plan.context_parts,
+ )
except OpenVikingPartialWriteError as exc:
self._handle_partial_capture(plan, exc)
raise
@@ -318,7 +346,8 @@ class OpenVikingContextMiddleware(AgentMiddleware):
return None
session_id = self._resolve_session_id(state, runtime)
peer_id = self._resolve_peer_id(state, runtime)
- key = _capture_key(session_id, peer_id)
+ actor_peer_id = self._resolve_actor_peer_id(state, runtime)
+ key = _capture_key(session_id, peer_id, actor_peer_id)
previous_signatures = self._captured_signatures.get(key, ())
signatures = tuple(_message_signature(message) for message in messages)
unchanged = signatures == previous_signatures
@@ -333,6 +362,7 @@ class OpenVikingContextMiddleware(AgentMiddleware):
return _CapturePlan(
session_id=session_id,
peer_id=peer_id,
+ actor_peer_id=actor_peer_id,
key=key,
messages=messages,
signatures=signatures,
@@ -399,6 +429,31 @@ class OpenVikingContextMiddleware(AgentMiddleware):
return resolved
return None
+ def _resolve_actor_peer_id(
+ self,
+ state: Any,
+ runtime: Any,
+ ) -> str | None:
+ if self.actor_peer_resolver is None:
+ return get_actor_peer_id()
+ actor_peer_id = self.actor_peer_resolver(state, runtime)
+ if actor_peer_id is None:
+ return None
+ if not isinstance(actor_peer_id, str):
+ raise TypeError("OpenViking actor_peer_resolver must return a string or None")
+ normalized = actor_peer_id.strip()
+ if not normalized:
+ raise ValueError("OpenViking actor_peer_resolver must not return an empty string")
+ return normalized
+
+ def _actor_peer_scope(
+ self,
+ actor_peer_id: str | None,
+ ) -> AbstractContextManager[None]:
+ if self.actor_peer_resolver is None:
+ return nullcontext()
+ return use_actor_peer(actor_peer_id)
+
def _nested_get(value: Any, *keys: str) -> Any:
current = value
@@ -426,8 +481,42 @@ def _normalize_peer_id(value: Any) -> str | None:
return text or None
-def _capture_key(session_id: str, peer_id: str | None) -> tuple[str, str]:
- return (session_id, peer_id or "")
+def _capture_key(
+ session_id: str,
+ peer_id: str | None,
+ actor_peer_id: str | None,
+) -> _CaptureKey:
+ if actor_peer_id is None:
+ return (session_id, peer_id or "")
+ return (actor_peer_id, session_id, peer_id or "")
+
+
+def _validate_actor_peer_transport(
+ *,
+ actor_peer_resolver: _ActorPeerResolver | None,
+ client: Any,
+ async_client: Any,
+ retriever: OpenVikingRetriever | None,
+ path: str | None,
+) -> None:
+ if actor_peer_resolver is None:
+ return
+ require_request_actor_peer_support()
+ if path is not None or (retriever is not None and retriever.path is not None):
+ raise ValueError("actor_peer_resolver requires an OpenViking HTTP connection")
+ transports = [client, async_client]
+ if retriever is not None:
+ transports.extend([retriever.client, retriever.async_client])
+ for transport in transports:
+ if transport is not None and not getattr(
+ transport,
+ "supports_request_actor_peer",
+ False,
+ ):
+ raise ValueError(
+ "actor_peer_resolver requires OpenViking HTTP clients that support "
+ "request-scoped actor peers"
+ )
def _message_role(message: Any) -> str:
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 5ebd617c1..e34c866e3 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -78,6 +78,38 @@ client = SyncHTTPClient(
)
```
+## Request-Scoped Actor Peer
+
+Applications can reuse one initialized, credential-bound client while selecting
+the active actor peer for each request:
+
+```python
+from openviking_sdk import (
+ SyncHTTPClient,
+ use_actor_peer,
+)
+
+client = SyncHTTPClient(
+ url="http://127.0.0.1:1933",
+ api_key="your-user-key",
+)
+client.initialize()
+
+with use_actor_peer("assistant-a"):
+ memories = client.find("deployment preference")
+```
+
+The scope is isolated with Python `ContextVar`, so concurrent async tasks and
+sync calls dispatched through the SDK worker loop do not overwrite each
+other. Nested scopes restore the previous actor peer automatically.
+
+This scope does not change authentication or tenant ownership. Account and user
+identity remain bound to the API key or OAuth credential. Use a separate
+credential-bound client for each OpenViking user, and derive actor peer values
+only from authenticated application state. The server applies the actor peer
+only to endpoints that accept an actor-peer view; session APIs remain
+user-scoped.
+
## Quick Start: Sync Client
```python
diff --git a/sdk/python/README_CN.md b/sdk/python/README_CN.md
index b1b334018..4f972179b 100644
--- a/sdk/python/README_CN.md
+++ b/sdk/python/README_CN.md
@@ -78,6 +78,35 @@ client = SyncHTTPClient(
)
```
+## 请求级 Actor Peer
+
+应用可以复用一个已经绑定凭证并完成初始化的 client,同时为每个请求选择当前的
+actor peer:
+
+```python
+from openviking_sdk import (
+ SyncHTTPClient,
+ use_actor_peer,
+)
+
+client = SyncHTTPClient(
+ url="http://127.0.0.1:1933",
+ api_key="your-user-key",
+)
+client.initialize()
+
+with use_actor_peer("assistant-a"):
+ memories = client.find("部署偏好")
+```
+
+该作用域通过 Python `ContextVar` 隔离,因此并发 async task 以及由 SDK worker loop
+执行的同步调用不会互相覆盖。嵌套作用域会自动恢复之前的 actor peer。
+
+该作用域不会改变认证或租户归属。Account 和 user 身份仍然由 API Key 或 OAuth
+凭证决定。每个 OpenViking user 应使用各自绑定凭证的 client,actor peer 只能从应用
+已经认证的状态中解析。服务端只会在支持 actor-peer view 的接口上应用该值;Session
+接口仍然以 user 为作用域。
+
## 快速开始:同步客户端
```python
diff --git a/sdk/python/openviking_sdk/__init__.py b/sdk/python/openviking_sdk/__init__.py
index a91100d05..eba322f35 100644
--- a/sdk/python/openviking_sdk/__init__.py
+++ b/sdk/python/openviking_sdk/__init__.py
@@ -1,3 +1,4 @@
+from .actor_peer import get_actor_peer_id, use_actor_peer
from .client import AsyncHTTPClient, SyncHTTPClient
from .errors import (
AbortedError,
@@ -11,8 +12,10 @@ __all__ = [
"AbortedError",
"AsyncHTTPClient",
"ConflictError",
+ "get_actor_peer_id",
"OpenVikingError",
"ResourceExhaustedError",
"SyncHTTPClient",
"UnimplementedError",
+ "use_actor_peer",
]
diff --git a/sdk/python/openviking_sdk/actor_peer.py b/sdk/python/openviking_sdk/actor_peer.py
new file mode 100644
index 000000000..6e8c10e50
--- /dev/null
+++ b/sdk/python/openviking_sdk/actor_peer.py
@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Iterator
+
+_actor_peer_id: ContextVar[str | None] = ContextVar(
+ "openviking_actor_peer_id",
+ default=None,
+)
+
+
+def _normalize_actor_peer_id(actor_peer_id: str | None) -> str | None:
+ if actor_peer_id is None:
+ return None
+ if not isinstance(actor_peer_id, str):
+ raise TypeError("actor_peer_id must be a string or None")
+ normalized = actor_peer_id.strip()
+ if not normalized:
+ raise ValueError("actor_peer_id must not be empty")
+ return normalized
+
+
+@contextmanager
+def use_actor_peer(actor_peer_id: str | None) -> Iterator[None]:
+ """Select an actor peer for HTTP calls in the current execution context."""
+
+ token = _actor_peer_id.set(_normalize_actor_peer_id(actor_peer_id))
+ try:
+ yield
+ finally:
+ _actor_peer_id.reset(token)
+
+
+def get_actor_peer_id() -> str | None:
+ """Return the actor peer active in the current execution context, if any."""
+
+ return _actor_peer_id.get()
+
+
+def _request_actor_peer_headers() -> dict[str, str]:
+ actor_peer_id = get_actor_peer_id()
+ if actor_peer_id is None:
+ return {}
+ return {"X-OpenViking-Actor-Peer": actor_peer_id}
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 2773889f3..77db3ddd5 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -15,6 +15,7 @@ from urllib.parse import quote
import httpx
from ._utils import run_async
+from .actor_peer import _request_actor_peer_headers
from .config import resolve_client_config
from .errors import (
AbortedError,
@@ -334,6 +335,8 @@ class _HTTPObserver:
class AsyncHTTPClient:
+ supports_request_actor_peer = True
+
def __init__(
self,
url: Optional[str] = None,
@@ -446,7 +449,8 @@ class AsyncHTTPClient:
raise RuntimeError("Client is not initialized")
request_kwargs = dict(kwargs)
- headers = dict(request_kwargs.pop("headers", {}) or {})
+ headers = _request_actor_peer_headers()
+ headers.update(dict(request_kwargs.pop("headers", {}) or {}))
has_explicit_gateway_header = self._has_explicit_gateway_header(headers)
# Multipart streams cannot be replayed safely after the first request. Probe the
@@ -1819,6 +1823,8 @@ class AsyncHTTPClient:
class SyncHTTPClient:
+ supports_request_actor_peer = True
+
def __init__(self, *args, **kwargs):
self._async_client = AsyncHTTPClient(*args, **kwargs)
self._initialized = False
diff --git a/sdk/python/tests/test_actor_peer.py b/sdk/python/tests/test_actor_peer.py
new file mode 100644
index 000000000..6cd7a0e5e
--- /dev/null
+++ b/sdk/python/tests/test_actor_peer.py
@@ -0,0 +1,144 @@
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+
+import httpx
+import pytest
+from openviking_sdk import (
+ AsyncHTTPClient,
+ SyncHTTPClient,
+ get_actor_peer_id,
+ use_actor_peer,
+)
+
+
+class _HeaderRecordingTransport:
+ def __init__(self):
+ self.requests: list[dict[str, str]] = []
+
+ async def handle(self, request: httpx.Request) -> httpx.Response:
+ await asyncio.sleep(0)
+ headers = {
+ name: request.headers[name]
+ for name in (
+ "X-OpenViking-Account",
+ "X-OpenViking-User",
+ "X-OpenViking-Actor-Peer",
+ )
+ if name in request.headers
+ }
+ self.requests.append(headers)
+ return httpx.Response(
+ status_code=200,
+ json={"status": "ok", "result": {}},
+ request=request,
+ )
+
+
+async def test_async_http_client_scopes_actor_peer_without_overriding_tenant():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ transport = _HeaderRecordingTransport()
+ client._http = httpx.AsyncClient(
+ base_url="http://localhost:1933",
+ headers={
+ "X-OpenViking-Account": "credential-account",
+ "X-OpenViking-User": "credential-user",
+ "X-OpenViking-Actor-Peer": "configured-assistant",
+ },
+ transport=httpx.MockTransport(transport.handle),
+ )
+
+ async def find_as(actor_peer_id: str) -> None:
+ with use_actor_peer(actor_peer_id):
+ await client.find(query=f"memory for {actor_peer_id}")
+
+ await asyncio.gather(find_as("assistant-a"), find_as("assistant-b"))
+ await client.find(query="no actor peer")
+ await client.close()
+
+ runtime_requests = {
+ request["X-OpenViking-Actor-Peer"]: request for request in transport.requests[:2]
+ }
+ assert runtime_requests == {
+ "assistant-a": {
+ "X-OpenViking-Account": "credential-account",
+ "X-OpenViking-User": "credential-user",
+ "X-OpenViking-Actor-Peer": "assistant-a",
+ },
+ "assistant-b": {
+ "X-OpenViking-Account": "credential-account",
+ "X-OpenViking-User": "credential-user",
+ "X-OpenViking-Actor-Peer": "assistant-b",
+ },
+ }
+ assert transport.requests[2] == {
+ "X-OpenViking-Account": "credential-account",
+ "X-OpenViking-User": "credential-user",
+ "X-OpenViking-Actor-Peer": "configured-assistant",
+ }
+
+
+def test_sync_http_client_isolates_actor_peers_across_worker_loop_calls():
+ client = SyncHTTPClient(url="http://localhost:1933")
+ transport = _HeaderRecordingTransport()
+ client._async_client._http = httpx.AsyncClient(
+ base_url="http://localhost:1933",
+ headers={
+ "X-OpenViking-Account": "credential-account",
+ "X-OpenViking-User": "credential-user",
+ },
+ transport=httpx.MockTransport(transport.handle),
+ )
+
+ def find_as(actor_peer_id: str) -> None:
+ with use_actor_peer(actor_peer_id):
+ client.find(query=f"memory for {actor_peer_id}")
+
+ with ThreadPoolExecutor(max_workers=2) as executor:
+ list(executor.map(find_as, ("assistant-a", "assistant-b")))
+ client.close()
+
+ assert {request["X-OpenViking-Actor-Peer"]: request for request in transport.requests} == {
+ "assistant-a": {
+ "X-OpenViking-Account": "credential-account",
+ "X-OpenViking-User": "credential-user",
+ "X-OpenViking-Actor-Peer": "assistant-a",
+ },
+ "assistant-b": {
+ "X-OpenViking-Account": "credential-account",
+ "X-OpenViking-User": "credential-user",
+ "X-OpenViking-Actor-Peer": "assistant-b",
+ },
+ }
+
+
+def test_actor_peer_scope_is_nested_cleared_and_restored():
+ assert get_actor_peer_id() is None
+ with use_actor_peer(" outer "):
+ assert get_actor_peer_id() == "outer"
+ with use_actor_peer("inner"):
+ assert get_actor_peer_id() == "inner"
+ assert get_actor_peer_id() == "outer"
+ with use_actor_peer(None):
+ assert get_actor_peer_id() is None
+ assert get_actor_peer_id() == "outer"
+ assert get_actor_peer_id() is None
+
+ with pytest.raises(RuntimeError, match="scope failed"):
+ with use_actor_peer("actor"):
+ raise RuntimeError("scope failed")
+ assert get_actor_peer_id() is None
+
+
+ ("actor_peer_id", "error", "message"),
+ [
+ (123, TypeError, "actor_peer_id must be a string or None"),
+ (" ", ValueError, "actor_peer_id must not be empty"),
+ ],
+)
+def test_actor_peer_scope_validates_input(actor_peer_id, error, message):
+ with pytest.raises(error, match=message):
+ with use_actor_peer(actor_peer_id):
+ pass
+ assert get_actor_peer_id() is None
diff --git a/tests/integration/langchain_langgraph/test_runtime_actor_peer.py b/tests/integration/langchain_langgraph/test_runtime_actor_peer.py
new file mode 100644
index 000000000..1c8afa997
--- /dev/null
+++ b/tests/integration/langchain_langgraph/test_runtime_actor_peer.py
@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+import pytest
+
+pytest.importorskip("langchain")
+pytest.importorskip("langchain_core")
+pytest.importorskip("langgraph")
+
+from langchain.agents import create_agent
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+from langchain_core.messages import AIMessage, HumanMessage
+
+from openviking_cli._sdk_import import import_openviking_sdk
+
+# Load the workspace SDK before the integration package so this cross-package
+# feature is tested even when an older released SDK is installed.
+_openviking_sdk = import_openviking_sdk()
+get_actor_peer_id = _openviking_sdk.get_actor_peer_id
+use_actor_peer = _openviking_sdk.use_actor_peer
+
+_langchain_integration = import_module("openviking.integrations.langchain")
+InMemoryOpenVikingClient = _langchain_integration.InMemoryOpenVikingClient
+OpenVikingContextMiddleware = _langchain_integration.OpenVikingContextMiddleware
+
+
+class RuntimeActorPeerTrackingClient:
+ """Async client facade that observes the active SDK actor peer."""
+
+ supports_request_actor_peer = True
+
+ def __init__(self, records: dict[str, str] | None = None):
+ self.backing = InMemoryOpenVikingClient(records)
+ self.actor_peer_calls: list[tuple[str, str | None]] = []
+
+ def __getattr__(self, name: str) -> Any:
+ method = getattr(self.backing, name)
+ if not callable(method):
+ return method
+
+ async def call(*args: Any, **kwargs: Any) -> Any:
+ self.actor_peer_calls.append((name, get_actor_peer_id()))
+ return method(*args, **kwargs)
+
+ return call
+
+
+async def test_real_create_agent_resolves_actor_peer_from_runtime_context():
+ client = RuntimeActorPeerTrackingClient(
+ {"viking://user/memories/profile.md": "Runtime-scoped memory."}
+ )
+
+ def resolve_actor_peer(_state: dict[str, Any], runtime: Any) -> str:
+ return runtime.context["actor_peer_id"]
+
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ actor_peer_resolver=resolve_actor_peer,
+ session_id_resolver=lambda _state, _runtime: "shared-thread-id",
+ )
+ agent = create_agent(
+ model=FakeListChatModel(responses=["Stored with runtime actor peer."]),
+ tools=[],
+ middleware=[middleware],
+ context_schema=dict,
+ )
+
+ result = await agent.ainvoke(
+ {"messages": [HumanMessage(content="Remember this agent-specific turn.")]},
+ config={"configurable": {"thread_id": "shared-thread-id"}},
+ context={"user_id": "alice", "actor_peer_id": "lead-agent"},
+ )
+
+ assert result["messages"][-1].content == "Stored with runtime actor peer."
+ relevant_calls = [
+ (name, actor_peer_id)
+ for name, actor_peer_id in client.actor_peer_calls
+ if name in {"search", "batch_add_messages"}
+ ]
+ assert relevant_calls
+ assert {actor_peer_id for _, actor_peer_id in relevant_calls} == {"lead-agent"}
+
+
+async def test_middleware_capture_progress_is_isolated_by_actor_peer():
+ client = RuntimeActorPeerTrackingClient()
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ actor_peer_resolver=lambda _state, runtime: runtime.context["actor_peer_id"],
+ session_id_resolver=lambda _state, _runtime: "shared-thread-id",
+ )
+ state = {
+ "messages": [
+ HumanMessage(content="Identical input."),
+ AIMessage(content="Identical output."),
+ ]
+ }
+
+ class Runtime:
+ def __init__(self, actor_peer_id: str):
+ self.context = {"actor_peer_id": actor_peer_id}
+
+ await middleware.aafter_agent(state, Runtime("assistant-a"))
+ await middleware.aafter_agent(state, Runtime("assistant-b"))
+
+ write_actor_peers = [
+ actor_peer_id
+ for name, actor_peer_id in client.actor_peer_calls
+ if name == "batch_add_messages"
+ ]
+ assert write_actor_peers == ["assistant-a", "assistant-b"]
+
+
+async def test_middleware_without_resolver_preserves_ambient_actor_peer():
+ client = RuntimeActorPeerTrackingClient()
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ session_id_resolver=lambda _state, _runtime: "ambient-actor-session",
+ )
+ state = {
+ "messages": [
+ HumanMessage(content="Identical ambient input."),
+ AIMessage(content="Identical ambient output."),
+ ]
+ }
+
+ for actor_peer_id in ("assistant-a", "assistant-b"):
+ with use_actor_peer(actor_peer_id):
+ await middleware.aafter_agent(state, runtime=None)
+
+ write_actor_peers = [
+ observed_actor_peer
+ for name, observed_actor_peer in client.actor_peer_calls
+ if name == "batch_add_messages"
+ ]
+ assert write_actor_peers == ["assistant-a", "assistant-b"]
+
+
+async def test_middleware_resolver_none_clears_ambient_actor_peer():
+ client = RuntimeActorPeerTrackingClient()
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ actor_peer_resolver=lambda _state, _runtime: None,
+ session_id_resolver=lambda _state, _runtime: "fixed-actor-session",
+ )
+
+ with use_actor_peer("ambient-agent"):
+ await middleware.aafter_agent(
+ {
+ "messages": [
+ HumanMessage(content="Use no actor peer."),
+ AIMessage(content="Stored without an actor peer."),
+ ]
+ },
+ runtime=None,
+ )
+
+ write_actor_peers = [
+ observed_actor_peer
+ for name, observed_actor_peer in client.actor_peer_calls
+ if name == "batch_add_messages"
+ ]
+ assert write_actor_peers == [None]
diff --git a/tests/unit/test_langchain_runtime_actor_peer.py b/tests/unit/test_langchain_runtime_actor_peer.py
new file mode 100644
index 000000000..59114a412
--- /dev/null
+++ b/tests/unit/test_langchain_runtime_actor_peer.py
@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from importlib import import_module
+from typing import Any, Iterator
+
+import pytest
+
+pytest.importorskip("langchain_core")
+pytest.importorskip("langgraph")
+
+from langchain_core.messages import AIMessage, HumanMessage
+
+from openviking_cli._sdk_import import import_openviking_sdk
+
+# Load the workspace SDK before the integration package so this cross-package
+# feature is tested even when an older released SDK is installed.
+_openviking_sdk = import_openviking_sdk()
+actor_peer_module = import_module("openviking.integrations.langchain.actor_peer")
+_langchain_integration = import_module("openviking.integrations.langchain")
+_langchain_client = import_module("openviking.integrations.langchain.client")
+InMemoryOpenVikingClient = _langchain_integration.InMemoryOpenVikingClient
+OpenVikingContextMiddleware = _langchain_integration.OpenVikingContextMiddleware
+OpenVikingClientHandle = _langchain_client.OpenVikingClientHandle
+OpenVikingConnection = _langchain_client.OpenVikingConnection
+
+
+@contextmanager
+def _older_sdk_actor_peer_support(
+ monkeypatch: pytest.MonkeyPatch,
+) -> Iterator[None]:
+ with monkeypatch.context() as older_sdk:
+ older_sdk.setattr(actor_peer_module, "_actor_peer_getter", None)
+ older_sdk.setattr(actor_peer_module, "_actor_peer_scope", None)
+ yield
+
+
+def test_langchain_exports_actor_peer_capability_helper():
+ integration = import_module("openviking.integrations.langchain")
+ assert integration.has_request_actor_peer_support()
+ assert "has_request_actor_peer_support" in integration.__all__
+
+ namespace: dict[str, Any] = {}
+ exec("from openviking.integrations.langchain import *", namespace)
+
+ assert namespace["has_request_actor_peer_support"] is (
+ integration.has_request_actor_peer_support
+ )
+ assert "OpenVikingRequestIdentity" not in namespace
+
+
+def test_langchain_star_import_remains_usable_with_older_sdk(
+ monkeypatch: pytest.MonkeyPatch,
+):
+ integration = import_module("openviking.integrations.langchain")
+ with _older_sdk_actor_peer_support(monkeypatch):
+ assert not integration.has_request_actor_peer_support()
+
+ namespace: dict[str, Any] = {}
+ exec("from openviking.integrations.langchain import *", namespace)
+
+ assert namespace["OpenVikingContextMiddleware"] is (integration.OpenVikingContextMiddleware)
+ assert not namespace["has_request_actor_peer_support"]()
+
+
+def test_middleware_rejects_actor_peer_resolver_for_embedded_client(tmp_path):
+ with pytest.raises(
+ ValueError,
+ match="actor_peer_resolver requires an OpenViking HTTP connection",
+ ):
+ OpenVikingContextMiddleware(
+ path=str(tmp_path),
+ actor_peer_resolver=lambda _state, _runtime: "runtime-agent",
+ )
+
+
+def test_middleware_remains_usable_with_older_sdk_when_actor_peer_is_unused(
+ monkeypatch: pytest.MonkeyPatch,
+):
+ with _older_sdk_actor_peer_support(monkeypatch):
+ middleware = OpenVikingContextMiddleware(
+ client=InMemoryOpenVikingClient(),
+ session_id_resolver=lambda _state, _runtime: "legacy-sdk-session",
+ )
+ middleware.after_agent(
+ {
+ "messages": [
+ HumanMessage(content="Existing middleware remains usable."),
+ AIMessage(content="Stored."),
+ ]
+ },
+ runtime=None,
+ )
+
+ with pytest.raises(ImportError, match="Upgrade openviking-sdk"):
+ OpenVikingContextMiddleware(
+ actor_peer_resolver=lambda _state, _runtime: None,
+ )
+
+
+def test_middleware_rejects_custom_client_without_actor_peer_support():
+ with pytest.raises(
+ ValueError,
+ match="clients that support request-scoped actor peers",
+ ):
+ OpenVikingContextMiddleware(
+ client=InMemoryOpenVikingClient(),
+ actor_peer_resolver=lambda _state, _runtime: "runtime-agent",
+ )
+
+
+def test_middleware_rejects_embedded_client_handle_with_actor_peer_resolver(
+ tmp_path,
+):
+ client = OpenVikingClientHandle(OpenVikingConnection(path=str(tmp_path)))
+
+ with pytest.raises(
+ ValueError,
+ match="clients that support request-scoped actor peers",
+ ):
+ OpenVikingContextMiddleware(
+ client=client,
+ actor_peer_resolver=lambda _state, _runtime: "runtime-agent",
+ )
+
+
+def test_middleware_accepts_official_request_actor_peer_client():
+ client = _openviking_sdk.AsyncHTTPClient(url="http://openviking.test")
+
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ actor_peer_resolver=lambda _state, _runtime: "runtime-agent",
+ )
+
+ assert middleware.recorder._connection.async_client is client
+
+
+ ("resolved", "error", "message"),
+ [
+ (123, TypeError, "actor_peer_resolver must return a string or None"),
+ (" ", ValueError, "actor_peer_resolver must not return an empty string"),
+ ],
+)
+def test_middleware_validates_actor_peer_resolver_result(resolved, error, message):
+ middleware = OpenVikingContextMiddleware(
+ actor_peer_resolver=lambda _state, _runtime: resolved,
+ session_id_resolver=lambda _state, _runtime: "runtime-actor-session",
+ )
+
+ with pytest.raises(error, match=message):
+ middleware.after_agent(
+ {
+ "messages": [
+ HumanMessage(content="Remember this."),
+ AIMessage(content="Stored."),
+ ]
+ },
+ runtime=None,
+ )