Merge branch 'main' into feat/skills

BhAem · BhAem · commit d64574879564 · 2026-01-04T16:47:33.000+08:00
diff --git a/docs/docs/memory/long-term-memory.md b/docs/docs/memory/long-term-memory.md
@@ -417,3 +417,25 @@ Session archived to Long-Term Memory
 Runner2 Question: favorite project
 Runner2 Answer: Your favorite project is Project Alpha.
 ```
+
+## 自动保存 session 到长期记忆
+
+为简化操作流程，VeADK 的 Agent 模块支持将对话 Session 自动保存至长期记忆。只需在初始化 Agent 时，开启 auto_save_session 属性并完成长期记忆组件的初始化配置即可，具体示例如下：
+
+```python
+from veadk import Agent
+from veadk.memory import LongTermMemory
+
+# 初始化长期记忆组件
+long_term_memory = LongTermMemory(
+    backend="viking", app_name=APP_NAME, user_id=USER_ID
+)
+
+# 初始化 Agent 并开启 Session 自动保存
+agent = Agent(
+    auto_save_session=True,
+    long_term_memory=long_term_memory
+)
+```
+
+为避免索引被频繁初始化，VeADK 提供 MIN_MESSAGES_THRESHOLD 和 MIN_TIME_THRESHOLD 两个环境变量，支持自定义 Session 保存周期。其中，默认触发保存的条件为累计 10 条 event 或间隔 60 秒；此外，当切换 Session 并发起新的问答请求时，VeADK 会自动将旧 Session 的会话内容保存至长期记忆中。
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "veadk-python"
-version = "0.5.2"
+version = "0.5.3"
 description = "Volcengine agent development kit, integrations with Volcengine cloud services."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,7 +13,7 @@ authors = [
 ]
 dependencies = [
     "pydantic-settings==2.10.1", # Config management
-    "a2a-sdk==0.3.7", # For Google Agent2Agent protocol
+    "a2a-sdk>=0.3.7", # For Google Agent2Agent protocol
     "deprecated==1.2.18",
     "google-adk>=1.19.0", # For basic agent architecture
     "litellm>=1.74.3", # For model inference
diff --git a/veadk/cli/cli_web.py b/veadk/cli/cli_web.py
@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import logging
 from functools import wraps
 
 import click
@@ -139,5 +140,14 @@ async def wrapper(*args, **kwargs) -> ADKRunner:
     # from Google ADK and Litellm
     if "--log_level" not in extra_args:
         extra_args.extend(["--log_level", "ERROR"])
+        logging.basicConfig(level=logging.ERROR, force=True)
+
+    if "--log_level" in extra_args:
+        logging.basicConfig(
+            level=getattr(
+                logging, extra_args[extra_args.index("--log_level") + 1].upper()
+            ),
+            force=True,
+        )
 
     cli_web.main(args=extra_args, standalone_mode=False)
diff --git a/veadk/community/langchain_ai/checkpoint/__init__.py b/veadk/community/langchain_ai/checkpoint/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
diff --git a/veadk/community/langchain_ai/checkpoint/memory/__init__.py b/veadk/community/langchain_ai/checkpoint/memory/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
diff --git a/veadk/community/langchain_ai/middlewares/__init__.py b/veadk/community/langchain_ai/middlewares/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
diff --git a/veadk/community/langchain_ai/middlewares/save_session.py b/veadk/community/langchain_ai/middlewares/save_session.py
@@ -0,0 +1,60 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from langchain.agents import AgentState
+from langchain.agents.middleware import after_agent
+from langchain_core.messages.ai import AIMessage
+from langchain_core.messages.human import HumanMessage
+from langgraph.runtime import Runtime
+
+from veadk.community.langchain_ai.store.memory.viking_memory import (
+    VikingMemoryStore,
+)
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@after_agent
+def save_session(state: AgentState, runtime: Runtime) -> None:
+    """Save the session to the memory store."""
+    store: VikingMemoryStore | None = runtime.store
+    if not store:
+        return
+
+    app_name = store.index
+    user_id = runtime.context.user_id
+    session_id = runtime.context.session_id
+
+    messages = state.get("messages", [])
+    logger.debug(
+        f"Save session {session_id} for user {user_id} with {len(messages)} messages. messages={messages}"
+    )
+
+    events = {}
+    for message in messages:
+        print(type(message))
+        if isinstance(message, HumanMessage):
+            event = {"role": "user", "parts": [{"text": message.content}]}
+
+        elif isinstance(message, AIMessage):
+            event = {"role": "assistant", "parts": [{"text": message.content}]}
+        else:
+            ...
+
+        events[message.id] = event
+
+    store.put(namespace=(app_name, user_id), key=session_id, value=events)
diff --git a/veadk/community/langchain_ai/models/__init__.py b/veadk/community/langchain_ai/models/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
diff --git a/veadk/community/langchain_ai/models/ark_model.py b/veadk/community/langchain_ai/models/ark_model.py
@@ -0,0 +1,34 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from langchain_core.utils.utils import (
+    from_env,
+    secret_from_env,
+)
+from langchain_openai import ChatOpenAI
+
+
+class ArkChatModel(ChatOpenAI):
+    def __init__(self, model: str, **kwargs):
+        super().__init__(
+            model=model,
+            api_key=secret_from_env("MODEL_AGENT_API_KEY")(),
+            base_url=from_env(
+                "MODEL_AGENT_API_BASE",
+                default="https://ark.cn-beijing.volces.com/api/v3",
+            )(),
+            **kwargs,
+        )
diff --git a/veadk/community/langchain_ai/store/__init__.py b/veadk/community/langchain_ai/store/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
diff --git a/veadk/community/langchain_ai/store/memory/__init__.py b/veadk/community/langchain_ai/store/memory/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
diff --git a/veadk/community/langchain_ai/store/memory/viking_memory.py b/veadk/community/langchain_ai/store/memory/viking_memory.py
@@ -0,0 +1,102 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+from langgraph.store.base import (
+    BaseStore,
+    GetOp,
+    ListNamespacesOp,
+    Op,
+    PutOp,
+    Result,
+    SearchOp,
+)
+
+from veadk.memory.long_term_memory_backends.vikingdb_memory_backend import (
+    VikingDBLTMBackend,
+)
+
+
+# mem0
+# viking db
+class VikingMemoryStore(BaseStore):
+    def __init__(self, index: str):
+        # index = (index, user_id)
+        # key = session_id
+        self.index = index
+        self._backend = VikingDBLTMBackend(index=index)
+
+    def batch(self, ops: Iterable[Op]) -> list[Result]:
+        # The batch/abatch methods are treated as internal.
+        # Users should access via put/search/get/list_namespaces/etc.
+        results = []
+        for op in ops:
+            if isinstance(op, PutOp):
+                self._apply_put_op(op)
+            elif isinstance(op, GetOp):
+                self._apply_get_op(op)
+            elif isinstance(op, SearchOp):
+                results.extend(self._apply_search_op(op))
+            # elif isinstance(op, ListNamespacesOp):
+            #     self._apply_list_namespaces_op(op)
+            else:
+                raise ValueError(f"Unknown op type: {type(op)}")
+
+        return results
+
+    def abatch(
+        self, ops: Iterable[GetOp | SearchOp | PutOp | ListNamespacesOp]
+    ) -> list[Result]: ...
+
+    def _apply_put_op(self, op: PutOp) -> None:
+        index, user_id = op.namespace
+        session_id = op.key
+
+        assert index == self._backend.index, (
+            "index must be the same as the backend index"
+        )
+
+        value = op.value
+
+        event_strings = []
+
+        for _, event in value.items():
+            event_strings.append(json.dumps(event))
+
+        if self._backend.save_memory(
+            user_id=user_id,
+            session_id=session_id,
+            event_strings=event_strings,
+        ):
+            return None
+
+    def _apply_get_op(self, op: GetOp):
+        return ["Not implemented"]
+
+    def _apply_search_op(self, op: SearchOp):
+        index, user_id = op.namespace_prefix
+        assert index == self._backend.index, (
+            "index must be the same as the backend index"
+        )
+
+        query = op.query
+        if not query:
+            return []
+
+        value = self._backend.search_memory(user_id=user_id, query=query, top_k=1)
+        return value
diff --git a/veadk/community/langchain_ai/tools/__init__.py b/veadk/community/langchain_ai/tools/__init__.py
@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
diff --git a/veadk/community/langchain_ai/tools/load_knowledgebase.py b/veadk/community/langchain_ai/tools/load_knowledgebase.py
@@ -0,0 +1,34 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from langchain.tools import ToolRuntime, tool
+
+from veadk.knowledgebase import KnowledgeBase
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@tool
+def load_knowledgebase(query: str, runtime: ToolRuntime) -> list[str]:
+    """Load knowledge base for the current user.
+
+    Args:
+        query: The query to search for in the knowledge base.
+    """
+    knowledgeabse: KnowledgeBase = runtime.context.knowledgebase  # type: ignore
+
+    results = knowledgeabse.search(query)
+
+    return [result.content for result in results]
diff --git a/veadk/community/langchain_ai/tools/load_memory.py b/veadk/community/langchain_ai/tools/load_memory.py
diff --git a/veadk/memory/long_term_memory_backends/vikingdb_memory_backend.py b/veadk/memory/long_term_memory_backends/vikingdb_memory_backend.py
diff --git a/veadk/tools/builtin_tools/llm_shield.py b/veadk/tools/builtin_tools/llm_shield.py
diff --git a/veadk/version.py b/veadk/version.py
