feat(knowledgebase): add knowledgebase adk capability

Change-Id: I40733b161d8ab1333cc83cfdbb5f32e6e2ff2638
Co-developed-by: Aone Copilot <[email protected]>
Signed-off-by: Sodawyx <[email protected]>

Author: Sodawyx

agentrun/integration/agentscope/__init__.py

@@ -3,10 +3,11 @@
 提供 AgentRun 模型与沙箱工具的 AgentScope 适配入口。 / 提供 AgentRun 模型with沙箱工具的 AgentScope 适配入口。
 """
 
-from .builtin import model, sandbox_toolset, toolset
+from .builtin import knowledgebase_toolset, model, sandbox_toolset, toolset
 
 __all__ = [
     "model",
     "toolset",
     "sandbox_toolset",
+    "knowledgebase_toolset",
 ]

agentrun/integration/agentscope/builtin.py

@@ -8,6 +8,9 @@
 
 from typing_extensions import Unpack
 
+from agentrun.integration.builtin import (
+    knowledgebase_toolset as _knowledgebase_toolset,
+)
 from agentrun.integration.builtin import model as _model
 from agentrun.integration.builtin import ModelArgs
 from agentrun.integration.builtin import sandbox_toolset as _sandbox_toolset
@@ -63,3 +66,23 @@ def sandbox_toolset(
         config=config,
         sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
     ).to_agentscope(prefix=prefix)
+
+
+def knowledgebase_toolset(
+    knowledge_base_names: List[str],
+    *,
+    prefix: Optional[str] = None,
+    modify_tool_name: Optional[Callable[[Tool], Tool]] = None,
+    filter_tools_by_name: Optional[Callable[[str], bool]] = None,
+    config: Optional[Config] = None,
+) -> List[Any]:
+    """将知识库检索封装为 AgentScope 工具列表。 / AgentScope Built-in Integration Functions"""
+
+    return _knowledgebase_toolset(
+        knowledge_base_names=knowledge_base_names,
+        config=config,
+    ).to_agentscope(
+        prefix=prefix,
+        modify_tool_name=modify_tool_name,
+        filter_tools_by_name=filter_tools_by_name,
+    )

agentrun/integration/builtin/__init__.py

@@ -4,6 +4,7 @@
 This module provides built-in integration functions for quickly creating models and tools.
 """
 
+from .knowledgebase import knowledgebase_toolset
 from .model import model, ModelArgs
 from .sandbox import sandbox_toolset
 from .toolset import toolset
@@ -13,4 +14,5 @@
     "ModelArgs",
     "toolset",
     "sandbox_toolset",
+    "knowledgebase_toolset",
 ]

agentrun/integration/builtin/knowledgebase.py

@@ -0,0 +1,137 @@
+"""知识库工具集 / KnowledgeBase ToolSet
+
+提供知识库检索功能的工具集，支持多知识库联合检索。
+Provides toolset for knowledge base retrieval, supporting multi-knowledge-base search.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from agentrun.integration.utils.tool import CommonToolSet, tool
+from agentrun.knowledgebase import KnowledgeBase
+from agentrun.utils.config import Config
+
+
+class KnowledgeBaseToolSet(CommonToolSet):
+    """知识库工具集 / KnowledgeBase ToolSet
+
+    提供知识库检索功能，支持对多个知识库进行联合检索。
+    Provides knowledge base retrieval capabilities, supporting joint retrieval
+    across multiple knowledge bases.
+
+    使用指南 / Usage Guide:
+    ============================================================
+
+    ## 基本用法 / Basic Usage
+
+    1. **创建工具集 / Create ToolSet**:
+       - 使用 `knowledgebase_toolset` 函数创建工具集实例
+       - Use `knowledgebase_toolset` function to create a toolset instance
+       - 指定要检索的知识库名称列表
+       - Specify the list of knowledge base names to search
+
+    2. **执行检索 / Execute Search**:
+       - 调用 `search_document` 工具进行检索
+       - Call `search_document` tool to perform retrieval
+       - 返回所有指定知识库的检索结果
+       - Returns retrieval results from all specified knowledge bases
+
+    ## 示例 / Examples
+
+    ```python
+    from agentrun.integration.langchain import knowledgebase_toolset
+
+    # 创建工具集 / Create toolset
+    tools = knowledgebase_toolset(
+        knowledge_base_names=["kb-product-docs", "kb-faq"],
+    )
+
+    # 在 Agent 中使用 / Use in Agent
+    agent = create_react_agent(llm, tools)
+    ```
+    """
+
+    def __init__(
+        self,
+        knowledge_base_names: List[str],
+        config: Optional[Config] = None,
+    ) -> None:
+        """初始化知识库工具集 / Initialize KnowledgeBase ToolSet
+
+        Args:
+            knowledge_base_names: 知识库名称列表 / List of knowledge base names
+            config: 配置 / Configuration
+        """
+        super().__init__()
+
+        self.knowledge_base_names = knowledge_base_names
+        self.config = config
+
+    @tool(
+        name="search_document",
+        description=(
+            "Search and retrieve relevant documents from configured knowledge"
+            " bases. Use this tool when you need to find information from the"
+            " knowledge base to answer user questions. Returns relevant"
+            " document chunks with their content and metadata. The search is"
+            " performed across all configured knowledge bases and results are"
+            " grouped by knowledge base name."
+        ),
+    )
+    def search_document(self, query: str) -> Dict[str, Any]:
+        """检索文档 / Search documents
+
+        根据查询文本从配置的知识库中检索相关文档。
+        Retrieves relevant documents from configured knowledge bases based on query text.
+
+        Args:
+            query: 查询文本 / Query text
+
+        Returns:
+            Dict[str, Any]: 检索结果，包含各知识库的检索结果 /
+                           Retrieval results containing results from each knowledge base
+        """
+        return KnowledgeBase.multi_retrieve(
+            query=query,
+            knowledge_base_names=self.knowledge_base_names,
+            config=self.config,
+        )
+
+
+def knowledgebase_toolset(
+    knowledge_base_names: List[str],
+    *,
+    config: Optional[Config] = None,
+) -> KnowledgeBaseToolSet:
+    """创建知识库工具集 / Create KnowledgeBase ToolSet
+
+    将知识库检索功能封装为通用工具集，可转换为各框架支持的格式。
+    Wraps knowledge base retrieval functionality into a common toolset that can be
+    converted to formats supported by various frameworks.
+
+    Args:
+        knowledge_base_names: 知识库名称列表 / List of knowledge base names
+        config: 配置 / Configuration
+
+    Returns:
+        KnowledgeBaseToolSet: 知识库工具集实例 / KnowledgeBase toolset instance
+
+    Example:
+        >>> from agentrun.integration.builtin import knowledgebase_toolset
+        >>>
+        >>> # 创建工具集 / Create toolset
+        >>> kb_tools = knowledgebase_toolset(
+        ...     knowledge_base_names=["kb-docs", "kb-faq"],
+        ... )
+        >>>
+        >>> # 转换为 LangChain 格式 / Convert to LangChain format
+        >>> langchain_tools = kb_tools.to_langchain()
+        >>>
+        >>> # 转换为 Google ADK 格式 / Convert to Google ADK format
+        >>> adk_tools = kb_tools.to_google_adk()
+    """
+    return KnowledgeBaseToolSet(
+        knowledge_base_names=knowledge_base_names,
+        config=config,
+    )

agentrun/integration/crewai/__init__.py

@@ -4,9 +4,10 @@
 CrewAI 与 LangChain 兼容，因此直接复用 LangChain 的转换逻辑。 / CrewAI with LangChain 兼容，因此直接复用 LangChain 的转换逻辑。
 """
 
-from .builtin import model, sandbox_toolset
+from .builtin import knowledgebase_toolset, model, sandbox_toolset
 
 __all__ = [
     "model",
     "sandbox_toolset",
+    "knowledgebase_toolset",
 ]

agentrun/integration/crewai/builtin.py

@@ -8,6 +8,9 @@
 
 from typing_extensions import Unpack
 
+from agentrun.integration.builtin import (
+    knowledgebase_toolset as _knowledgebase_toolset,
+)
 from agentrun.integration.builtin import model as _model
 from agentrun.integration.builtin import ModelArgs
 from agentrun.integration.builtin import sandbox_toolset as _sandbox_toolset
@@ -63,3 +66,23 @@ def sandbox_toolset(
         config=config,
         sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
     ).to_crewai(prefix=prefix)
+
+
+def knowledgebase_toolset(
+    knowledge_base_names: List[str],
+    *,
+    prefix: Optional[str] = None,
+    modify_tool_name: Optional[Callable[[Tool], Tool]] = None,
+    filter_tools_by_name: Optional[Callable[[str], bool]] = None,
+    config: Optional[Config] = None,
+) -> List[Any]:
+    """将知识库检索封装为 CrewAI 工具列表。 / CrewAI Built-in Integration Functions"""
+
+    return _knowledgebase_toolset(
+        knowledge_base_names=knowledge_base_names,
+        config=config,
+    ).to_crewai(
+        prefix=prefix,
+        modify_tool_name=modify_tool_name,
+        filter_tools_by_name=filter_tools_by_name,
+    )

agentrun/integration/google_adk/__init__.py

@@ -3,10 +3,11 @@
 提供与 Google Agent Development Kit 的模型与沙箱工具集成。 / 提供with Google Agent Development Kit 的模型with沙箱工具集成。
 """
 
-from .builtin import model, sandbox_toolset, toolset
+from .builtin import knowledgebase_toolset, model, sandbox_toolset, toolset
 
 __all__ = [
     "model",
     "toolset",
     "sandbox_toolset",
+    "knowledgebase_toolset",
 ]

agentrun/integration/google_adk/builtin.py

@@ -8,6 +8,9 @@
 
 from typing_extensions import Unpack
 
+from agentrun.integration.builtin import (
+    knowledgebase_toolset as _knowledgebase_toolset,
+)
 from agentrun.integration.builtin import model as _model
 from agentrun.integration.builtin import ModelArgs
 from agentrun.integration.builtin import sandbox_toolset as _sandbox_toolset
@@ -63,3 +66,23 @@ def sandbox_toolset(
         config=config,
         sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
     ).to_google_adk(prefix=prefix)
+
+
+def knowledgebase_toolset(
+    knowledge_base_names: List[str],
+    *,
+    prefix: Optional[str] = None,
+    modify_tool_name: Optional[Callable[[Tool], Tool]] = None,
+    filter_tools_by_name: Optional[Callable[[str], bool]] = None,
+    config: Optional[Config] = None,
+) -> List[Any]:
+    """将知识库检索封装为 Google ADK 工具列表。 / Google ADK Built-in Integration Functions"""
+
+    return _knowledgebase_toolset(
+        knowledge_base_names=knowledge_base_names,
+        config=config,
+    ).to_google_adk(
+        prefix=prefix,
+        modify_tool_name=modify_tool_name,
+        filter_tools_by_name=filter_tools_by_name,
+    )

agentrun/integration/langchain/__init__.py

@@ -20,11 +20,12 @@
     AgentRunConverter,
 )  # 向后兼容
 
-from .builtin import model, sandbox_toolset, toolset
+from .builtin import knowledgebase_toolset, model, sandbox_toolset, toolset
 
 __all__ = [
     "AgentRunConverter",
     "model",
     "toolset",
     "sandbox_toolset",
+    "knowledgebase_toolset",
 ]

agentrun/integration/langchain/builtin.py

@@ -8,6 +8,9 @@
 
 from typing_extensions import Unpack
 
+from agentrun.integration.builtin import (
+    knowledgebase_toolset as _knowledgebase_toolset,
+)
 from agentrun.integration.builtin import model as _model
 from agentrun.integration.builtin import ModelArgs
 from agentrun.integration.builtin import sandbox_toolset as _sandbox_toolset
@@ -69,3 +72,23 @@ def sandbox_toolset(
         modify_tool_name=modify_tool_name,
         filter_tools_by_name=filter_tools_by_name,
     )
+
+
+def knowledgebase_toolset(
+    knowledge_base_names: List[str],
+    *,
+    prefix: Optional[str] = None,
+    modify_tool_name: Optional[Callable[[Tool], Tool]] = None,
+    filter_tools_by_name: Optional[Callable[[str], bool]] = None,
+    config: Optional[Config] = None,
+) -> List[Any]:
+    """将知识库检索封装为 LangChain ``StructuredTool`` 列表。 / LangChain Built-in Integration Functions"""
+
+    return _knowledgebase_toolset(
+        knowledge_base_names=knowledge_base_names,
+        config=config,
+    ).to_langchain(
+        prefix=prefix,
+        modify_tool_name=modify_tool_name,
+        filter_tools_by_name=filter_tools_by_name,
+    )