Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

fix(agent): bind KnowledgeFS research tools to Agent spaces (#44629)

FFXNd989a5265018
diff --git a/api/core/app/apps/agent_app/runtime_request_builder.py b/api/core/app/apps/agent_app/runtime_request_builder.py
index dcec2b9742e..c2d8accae1f 100644
--- a/api/core/app/apps/agent_app/runtime_request_builder.py
+++ b/api/core/app/apps/agent_app/runtime_request_builder.py
@@ -56,7 +56,7 @@ from core.workflow.nodes.agent_v2.runtime_request_builder import (
)
from graphon.file import File, FileTransferMethod, FileType, file_manager
from graphon.model_runtime.entities.message_entities import ImagePromptMessageContent
-from models.agent_config_entities import AgentSoulConfig, AgentSoulToolsConfig
+from models.agent_config_entities import AgentKnowledgeSpaceConfig, AgentSoulConfig, AgentSoulToolsConfig
from models.provider_ids import ModelProviderID
from services.agent.knowledge_runtime_config import build_knowledge_fs_layer_config
from services.agent.prompt_mentions import expand_prompt_mentions
@@ -126,6 +126,7 @@ class AgentAppRuntimeRequestBuilder:
user_id=context.dify_context.user_id,
tools=agent_soul.tools,
invoke_from=context.dify_context.invoke_from,
+ knowledge_fs_spaces=tuple(agent_soul.knowledge.spaces),
)
except WorkflowAgentDifyToolsBuildError as error:
raise AgentAppRuntimeRequestBuildError(error.error_code, str(error)) from error
@@ -261,6 +262,7 @@ class AgentAppRuntimeRequestBuilder:
user_id: str | None,
tools: AgentSoulToolsConfig,
invoke_from: InvokeFrom,
+ knowledge_fs_spaces: tuple[AgentKnowledgeSpaceConfig, ...],
) -> WorkflowAgentToolLayers:
# Production Agent App runs intentionally keep existing plugin configs
# on the direct `dify.plugin.tools` route. This builder emits plugin
@@ -271,6 +273,7 @@ class AgentAppRuntimeRequestBuilder:
user_id=user_id,
tools=tools,
invoke_from=invoke_from,
+ knowledge_fs_spaces=knowledge_fs_spaces,
)
@staticmethod
diff --git a/api/core/workflow/nodes/agent_v2/dify_tools_builder.py b/api/core/workflow/nodes/agent_v2/dify_tools_builder.py
index e0e9008d661..f8481fb7942 100644
--- a/api/core/workflow/nodes/agent_v2/dify_tools_builder.py
+++ b/api/core/workflow/nodes/agent_v2/dify_tools_builder.py
@@ -26,7 +26,7 @@ from core.tools.plugin_tool.tool import PluginTool
from core.tools.tool_manager import ToolManager
from core.tools.workflow_as_tool.provider import WorkflowToolProviderController
from extensions.ext_database import db
-from models.agent_config_entities import AgentSoulDifyToolConfig, AgentSoulToolsConfig
+from models.agent_config_entities import AgentKnowledgeSpaceConfig, AgentSoulDifyToolConfig, AgentSoulToolsConfig
from models.provider_ids import ToolProviderID
from models.tools import WorkflowToolProvider
from services.tools.mcp_tools_manage_service import MCPToolManageService
@@ -98,6 +98,7 @@ class WorkflowAgentDifyToolLayersBuilder(Protocol):
user_id: str | None,
tools: AgentSoulToolsConfig,
invoke_from: InvokeFrom,
+ knowledge_fs_spaces: tuple[AgentKnowledgeSpaceConfig, ...] = (),
) -> WorkflowAgentToolLayers: ...
@@ -175,6 +176,7 @@ class WorkflowAgentDifyToolsBuilder:
user_id: str | None,
tools: AgentSoulToolsConfig,
invoke_from: InvokeFrom,
+ knowledge_fs_spaces: tuple[AgentKnowledgeSpaceConfig, ...] = (),
) -> WorkflowAgentToolLayers:
"""Resolve user-selected Dify tools into direct/core Agent backend DTOs.
@@ -194,33 +196,50 @@ class WorkflowAgentDifyToolsBuilder:
for tool_config in self._expand_provider_entries(tenant_id=tenant_id, enabled_tools=enabled_tools):
normalized_tool_config = self._normalized_tool_config(tenant_id=tenant_id, tool_config=tool_config)
destination = self._tool_layer_destination(normalized_tool_config)
- exposed_name = self._exposed_tool_name(normalized_tool_config)
- if exposed_name in seen_names:
- raise WorkflowAgentDifyToolsBuildError(
- "agent_tool_name_duplicated",
- f"Duplicate Dify Tool name {exposed_name!r}.",
- )
- seen_names.add(exposed_name)
-
- agent_tool = self._to_agent_tool_entity(normalized_tool_config)
- tool_runtime = self._fetch_tool_runtime(
- tenant_id=tenant_id,
- app_id=app_id,
- user_id=user_id,
- agent_tool=agent_tool,
- invoke_from=invoke_from,
- tool_config=normalized_tool_config,
- )
-
- if destination == "plugin":
- prepared_plugin.append(
- self._to_plugin_backend_tool_config(normalized_tool_config, tool_runtime, exposed_name)
+ choices = self._knowledge_fs_research_choices(normalized_tool_config, knowledge_fs_spaces)
+ for index, knowledge_space in enumerate(choices):
+ exposed_name = self._exposed_tool_name(normalized_tool_config)
+ if knowledge_space is not None and len(choices) > 1:
+ exposed_name = f"{exposed_name}_{index + 1}"
+ if exposed_name in seen_names:
+ raise WorkflowAgentDifyToolsBuildError(
+ "agent_tool_name_duplicated",
+ f"Duplicate Dify Tool name {exposed_name!r}.",
+ )
+ seen_names.add(exposed_name)
+
+ agent_tool = self._to_agent_tool_entity(
+ normalized_tool_config,
+ knowledge_fs_space_id=knowledge_space.control_space_id if knowledge_space else None,
)
- else:
- prepared_core.append(
- self._to_core_backend_tool_config(normalized_tool_config, tool_runtime, exposed_name)
+ tool_runtime = self._fetch_tool_runtime(
+ tenant_id=tenant_id,
+ app_id=app_id,
+ user_id=user_id,
+ agent_tool=agent_tool,
+ invoke_from=invoke_from,
+ tool_config=normalized_tool_config,
)
+ if destination == "plugin":
+ prepared_plugin.append(
+ self._to_plugin_backend_tool_config(normalized_tool_config, tool_runtime, exposed_name)
+ )
+ else:
+ description = self._description(normalized_tool_config, tool_runtime)
+ if knowledge_space is not None and len(choices) > 1:
+ description = (
+ f"{description or 'Create a research task.'} "
+ f"Agent Knowledge Base: {knowledge_space.name} (alias: {knowledge_space.id})."
+ )
+ if knowledge_space.description:
+ description += f" {knowledge_space.description}"
+ prepared_core.append(
+ self._to_core_backend_tool_config(
+ normalized_tool_config, tool_runtime, exposed_name, description=description
+ )
+ )
+
return WorkflowAgentToolLayers(
plugin_tools=DifyPluginToolsLayerConfig(tools=prepared_plugin) if prepared_plugin else None,
core_tools=DifyCoreToolsLayerConfig(tools=prepared_core) if prepared_core else None,
@@ -331,13 +350,42 @@ class WorkflowAgentDifyToolsBuilder:
) from exc
@staticmethod
- def _to_agent_tool_entity(tool_config: AgentSoulDifyToolConfig) -> AgentToolEntity:
+ def _knowledge_fs_research_choices(
+ tool_config: AgentSoulDifyToolConfig,
+ knowledge_fs_spaces: tuple[AgentKnowledgeSpaceConfig, ...],
+ ) -> tuple[AgentKnowledgeSpaceConfig | None, ...]:
+ if (
+ tool_config.provider_type is ToolProviderType.BUILT_IN
+ and WorkflowAgentDifyToolsBuilder._provider_id(tool_config) == "knowledge_fs"
+ and tool_config.tool_name == "create_research_task"
+ ):
+ spaces = tuple(space for space in knowledge_fs_spaces if not space.is_missing)
+ return spaces or (None,)
+ return (None,)
+
+ @staticmethod
+ def _to_agent_tool_entity(
+ tool_config: AgentSoulDifyToolConfig, *, knowledge_fs_space_id: str | None
+ ) -> AgentToolEntity:
assert tool_config.tool_name is not None
+ tool_parameters: dict[str, Any] = dict(tool_config.runtime_parameters)
+ if (
+ tool_config.provider_type is ToolProviderType.BUILT_IN
+ and WorkflowAgentDifyToolsBuilder._provider_id(tool_config) == "knowledge_fs"
+ and tool_config.tool_name == "create_research_task"
+ and knowledge_fs_space_id is not None
+ ):
+ # The selected Agent Knowledge Base supplies the hidden form
+ # parameter. The model still sees only query and mode.
+ tool_parameters["resource"] = {
+ "kind": "knowledge_fs",
+ "control_space_id": knowledge_fs_space_id,
+ }
return AgentToolEntity(
provider_type=tool_config.provider_type,
provider_id=WorkflowAgentDifyToolsBuilder._provider_id(tool_config),
tool_name=tool_config.tool_name,
- tool_parameters=dict(tool_config.runtime_parameters),
+ tool_parameters=tool_parameters,
credential_id=tool_config.credential_ref.id if tool_config.credential_ref else None,
)
@@ -420,6 +468,7 @@ class WorkflowAgentDifyToolsBuilder:
tool_config: AgentSoulDifyToolConfig,
tool_runtime: Tool,
exposed_name: str,
+ description: str | None = None,
) -> DifyCoreToolConfig:
parameters = self._prepared_parameters(tool_runtime)
return DifyCoreToolConfig(
@@ -428,7 +477,7 @@ class WorkflowAgentDifyToolsBuilder:
tool_name=tool_config.tool_name or exposed_name,
credential_id=tool_config.credential_ref.id if tool_config.credential_ref else None,
name=exposed_name,
- description=self._description(tool_config, tool_runtime),
+ description=description or self._description(tool_config, tool_runtime),
runtime_parameters=self._runtime_parameters(tool_runtime, parameters),
parameters=parameters,
parameters_json_schema=tool_runtime.get_llm_parameters_json_schema(),
diff --git a/api/core/workflow/nodes/agent_v2/runtime_request_builder.py b/api/core/workflow/nodes/agent_v2/runtime_request_builder.py
index 123ff230489..b94300f3cbb 100644
--- a/api/core/workflow/nodes/agent_v2/runtime_request_builder.py
+++ b/api/core/workflow/nodes/agent_v2/runtime_request_builder.py
@@ -60,6 +60,7 @@ from models.agent_config_entities import (
AgentKnowledgeMetadataFilteringConfig,
AgentKnowledgeModelConfig,
AgentKnowledgeRetrievalConfig,
+ AgentKnowledgeSpaceConfig,
AgentSoulConfig,
AgentSoulToolsConfig,
DeclaredArrayItem,
@@ -192,6 +193,7 @@ class WorkflowAgentRuntimeRequestBuilder:
user_id=context.dify_context.user_id,
tools=agent_soul.tools,
invoke_from=context.dify_context.invoke_from,
+ knowledge_fs_spaces=tuple(agent_soul.knowledge.spaces),
)
except WorkflowAgentDifyToolsBuildError as error:
raise WorkflowAgentRuntimeRequestBuildError(error.error_code, str(error)) from error
@@ -309,6 +311,7 @@ class WorkflowAgentRuntimeRequestBuilder:
user_id: str | None,
tools: AgentSoulToolsConfig,
invoke_from: InvokeFrom,
+ knowledge_fs_spaces: tuple[AgentKnowledgeSpaceConfig, ...],
) -> WorkflowAgentToolLayers:
# Production workflow runs intentionally keep existing plugin configs on
# the direct `dify.plugin.tools` route. This builder emits plugin tools
@@ -319,6 +322,7 @@ class WorkflowAgentRuntimeRequestBuilder:
user_id=user_id,
tools=tools,
invoke_from=invoke_from,
+ knowledge_fs_spaces=knowledge_fs_spaces,
)
@staticmethod
diff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py b/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
index d0116bb44a8..a9b01d9aca1 100644
--- a/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
@@ -171,8 +171,11 @@ def test_builder_carries_application_trace_context_but_redacts_it_from_request_l
class _NoToolsBuilder:
+ def __init__(self):
+ self.knowledge_fs_spaces = ()
+
def build_layers(self, **kwargs):
- del kwargs
+ self.knowledge_fs_spaces = kwargs["knowledge_fs_spaces"]
return SimpleNamespace(plugin_tools=None, core_tools=None, exposed_tool_names=lambda: [])
@@ -774,16 +777,23 @@ class TestAgentAppRuntimeRequestBuilder:
"id": "new",
"name": "New Docs",
"control_space_id": "00000000-0000-4000-8000-000000000001",
- }
+ },
+ {
+ "id": "other",
+ "name": "Other Docs",
+ "control_space_id": "00000000-0000-4000-8000-000000000002",
+ },
],
}
}
).knowledge
- result = AgentAppRuntimeRequestBuilder(dify_tools_builder=_NoToolsBuilder()).build(_ctx(soul)) # type: ignore[arg-type]
+ tool_builder = _NoToolsBuilder()
+ result = AgentAppRuntimeRequestBuilder(dify_tools_builder=tool_builder).build(_ctx(soul)) # type: ignore[arg-type]
layers = {layer.name: layer for layer in result.request.composition.layers}
assert layers["knowledge"].config["sets"][0]["id"] == "classic"
assert layers["knowledge_fs"].config["spaces"][0]["id"] == "new"
+ assert [space.id for space in tool_builder.knowledge_fs_spaces] == ["new", "other"]
def test_build_raises_when_model_missing(self):
builder = AgentAppRuntimeRequestBuilder(
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_dify_tools_builder.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_dify_tools_builder.py
index d4d9e8b6c1a..e85df517ef9 100644
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_dify_tools_builder.py
+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_dify_tools_builder.py
@@ -25,7 +25,8 @@ from core.workflow.nodes.agent_v2.dify_tools_builder import (
WorkflowAgentDifyToolsBuilder,
WorkflowAgentDifyToolsBuildError,
)
-from models.agent_config_entities import AgentSoulToolsConfig
+from models.agent_config_entities import AgentKnowledgeSpaceConfig, AgentSoulToolsConfig
+from services.knowledge_fs.builtin_tool.knowledge_fs.knowledge_fs import KnowledgeFSProvider
class FakeRuntimeProvider:
@@ -680,6 +681,149 @@ def test_rejects_missing_required_runtime_parameter():
assert exc_info.value.error_code == "agent_tool_runtime_parameter_missing"
[email protected]("tool_name", ["create_research_task", None])
+def test_research_tool_uses_sole_bound_agent_knowledge_space(tool_name: str | None) -> None:
+ tool = KnowledgeFSProvider().get_tool("create_research_task")
+ assert tool is not None
+ runtime_provider = FakeRuntimeProvider(tool)
+ builder = WorkflowAgentDifyToolsBuilder(
+ tool_runtime_provider=runtime_provider,
+ provider_tools_lister=lambda **_kwargs: ["create_research_task"],
+ )
+ tools = AgentSoulToolsConfig.model_validate(
+ {
+ "dify_tools": [
+ {
+ "provider_id": "knowledge_fs",
+ "provider_type": "builtin",
+ "tool_name": tool_name,
+ "credential_type": "unauthorized",
+ }
+ ]
+ }
+ )
+
+ result = builder.build_layers(
+ tenant_id="tenant-1",
+ app_id="app-1",
+ user_id="user-1",
+ tools=tools,
+ invoke_from=InvokeFrom.DEBUGGER,
+ knowledge_fs_spaces=(
+ AgentKnowledgeSpaceConfig(
+ id="docs",
+ control_space_id="00000000-0000-4000-8000-000000000001",
+ name="Docs",
+ ),
+ ),
+ )
+
+ assert result.core_tools is not None
+ assert len(result.core_tools.tools) == 1
+ prepared = result.core_tools.tools[0]
+ resource = {"kind": "knowledge_fs", "control_space_id": "00000000-0000-4000-8000-000000000001"}
+ assert runtime_provider.last_agent_tool is not None
+ assert runtime_provider.last_agent_tool.tool_parameters["resource"] == resource
+ assert prepared.runtime_parameters["resource"] == resource
+ assert prepared.name == "create_research_task"
+ assert prepared.tool_name == "create_research_task"
+ assert "resource" not in prepared.parameters_json_schema["properties"]
+
+
[email protected]("tool_name", ["create_research_task", None])
+def test_research_tool_exposes_one_choice_per_bound_agent_knowledge_space(tool_name: str | None) -> None:
+ tool = KnowledgeFSProvider().get_tool("create_research_task")
+ assert tool is not None
+ builder = WorkflowAgentDifyToolsBuilder(
+ tool_runtime_provider=FakeRuntimeProvider(tool),
+ provider_tools_lister=lambda **_kwargs: ["create_research_task"],
+ )
+ tools = AgentSoulToolsConfig.model_validate(
+ {
+ "dify_tools": [
+ {
+ "provider_id": "knowledge_fs",
+ "provider_type": "builtin",
+ "tool_name": tool_name,
+ "credential_type": "unauthorized",
+ "runtime_parameters": {"resource": "untrusted-selection"},
+ }
+ ]
+ }
+ )
+ spaces = (
+ AgentKnowledgeSpaceConfig(
+ id="product",
+ control_space_id="00000000-0000-4000-8000-000000000001",
+ name="Product Docs",
+ description="Product specifications and guides",
+ ),
+ AgentKnowledgeSpaceConfig(
+ id="support",
+ control_space_id="00000000-0000-4000-8000-000000000002",
+ name="Support Docs",
+ ),
+ )
+
+ result = builder.build_layers(
+ tenant_id="tenant-1",
+ app_id="app-1",
+ user_id="user-1",
+ tools=tools,
+ invoke_from=InvokeFrom.DEBUGGER,
+ knowledge_fs_spaces=spaces,
+ )
+
+ assert result.core_tools is not None
+ assert [prepared.name for prepared in result.core_tools.tools] == [
+ "create_research_task_1",
+ "create_research_task_2",
+ ]
+ assert [prepared.tool_name for prepared in result.core_tools.tools] == [
+ "create_research_task",
+ "create_research_task",
+ ]
+ for prepared, space in zip(result.core_tools.tools, spaces, strict=True):
+ assert prepared.runtime_parameters["resource"] == {
+ "kind": "knowledge_fs",
+ "control_space_id": space.control_space_id,
+ }
+ assert space.name in prepared.description
+ assert space.id in prepared.description
+ if space.description:
+ assert space.description in prepared.description
+ assert "resource" not in prepared.parameters_json_schema["properties"]
+
+
+def test_research_tool_without_single_bound_space_still_requires_resource() -> None:
+ tool = KnowledgeFSProvider().get_tool("create_research_task")
+ assert tool is not None
+ builder = WorkflowAgentDifyToolsBuilder(tool_runtime_provider=FakeRuntimeProvider(tool))
+ tools = AgentSoulToolsConfig.model_validate(
+ {
+ "dify_tools": [
+ {
+ "provider_id": "knowledge_fs",
+ "provider_type": "builtin",
+ "tool_name": "create_research_task",
+ "credential_type": "unauthorized",
+ }
+ ]
+ }
+ )
+
+ with pytest.raises(WorkflowAgentDifyToolsBuildError) as exc_info:
+ builder.build_layers(
+ tenant_id="tenant-1",
+ app_id="app-1",
+ user_id="user-1",
+ tools=tools,
+ invoke_from=InvokeFrom.DEBUGGER,
+ )
+
+ assert exc_info.value.error_code == "agent_tool_runtime_parameter_missing"
+
+
# ──────────────────────────────────────────────────────────────────────────────
# invoke_from is threaded through to ToolManager
# ──────────────────────────────────────────────────────────────────────────────
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
index e8c2efee1d0..a9471bfe523 100644
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
@@ -118,12 +118,14 @@ class CapturingPluginLayerBuilder:
# threaded through from ``DifyRunContext.invoke_from`` rather than
# hard-coded to a placeholder like ``VALIDATION``.
self.last_invoke_from: InvokeFrom | None = None
+ self.knowledge_fs_spaces = ()
- def build_layers(self, *, tenant_id, app_id, user_id, tools, invoke_from):
+ def build_layers(self, *, tenant_id, app_id, user_id, tools, invoke_from, knowledge_fs_spaces=()):
assert tenant_id == "tenant-1"
assert app_id == "app-1"
assert user_id == "user-1"
self.last_invoke_from = invoke_from
+ self.knowledge_fs_spaces = knowledge_fs_spaces
if not tools.dify_tools:
return SimpleNamespace(plugin_tools=None, core_tools=None, exposed_tool_names=lambda: [])
return SimpleNamespace(
@@ -149,7 +151,7 @@ class CapturingPluginLayerBuilder:
class FakeCoreLayerBuilder:
- def build_layers(self, *, tenant_id, app_id, user_id, tools, invoke_from):
+ def build_layers(self, *, tenant_id, app_id, user_id, tools, invoke_from, knowledge_fs_spaces=()):
assert tenant_id == "tenant-1"
assert app_id == "app-1"
assert user_id == "user-1"
@@ -1002,7 +1004,12 @@ def test_build_runs_classic_and_agent_knowledge_together(monkeypatch: pytest.Mon
"id": "new",
"name": "New Docs",
"control_space_id": "00000000-0000-4000-8000-000000000001",
- }
+ },
+ {
+ "id": "other",
+ "name": "Other Docs",
+ "control_space_id": "00000000-0000-4000-8000-000000000002",
+ },
],
}
}
@@ -1015,11 +1022,15 @@ def test_build_runs_classic_and_agent_knowledge_together(monkeypatch: pytest.Mon
config_snapshot=soul,
)
- result = WorkflowAgentRuntimeRequestBuilder().build(replace(context, snapshot=snapshot))
+ tool_builder = CapturingPluginLayerBuilder()
+ result = WorkflowAgentRuntimeRequestBuilder(dify_tools_builder=tool_builder).build(
+ replace(context, snapshot=snapshot)
+ )
layers = {layer.name: layer for layer in result.request.composition.layers}
assert layers["knowledge"].config["sets"][0]["id"] == "classic"
assert layers["knowledge_fs"].config["spaces"][0]["id"] == "new"
+ assert [space.id for space in tool_builder.knowledge_fs_spaces] == ["new", "other"]
assert result.metadata["runtime_support"]["reserved_status"]["knowledge"] == (
"supported_by_legacy_retrieval_and_knowledge_fs_cli"
)