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.

feat(workflow-generator): prefer installed tools (#40611)

Crazywoola58653f2cdb63
diff --git a/api/core/workflow/generator/prompts/node_builder_prompts.py b/api/core/workflow/generator/prompts/node_builder_prompts.py
index 7e8be29cf67..ff36b76ba9e 100644
--- a/api/core/workflow/generator/prompts/node_builder_prompts.py
+++ b/api/core/workflow/generator/prompts/node_builder_prompts.py
@@ -127,11 +127,11 @@ def format_start_inputs_section(start_inputs: list[dict[str, Any]]) -> str:
def format_tool_catalogue_section(catalogue_text: str) -> str:
- """Render exact tool identifiers for a tool-node builder only."""
+ """Render the legacy full catalogue when no structured selection exists."""
if not catalogue_text.strip():
return ""
return (
- "# Available tools (use these exact provider/tool identifiers — "
+ "# Available installed tools (use these exact provider/tool identifiers — "
"set provider_id and provider_name to the provider portion and "
"tool_name to the tool portion)\n\n"
f"{catalogue_text}\n\n"
diff --git a/api/core/workflow/generator/prompts/planner_prompts.py b/api/core/workflow/generator/prompts/planner_prompts.py
index 6c0bc5d20e6..7515ac87f04 100644
--- a/api/core/workflow/generator/prompts/planner_prompts.py
+++ b/api/core/workflow/generator/prompts/planner_prompts.py
@@ -59,15 +59,20 @@ minimum set of Dify workflow nodes needed to fulfil it, in execution order.
node that combines every result, then one "llm" node that consumes the
template output as context; the retrievals are parallel inputs to the
template, not mutually exclusive branches
-5. PREFER "tool" over "http-request" or "code" whenever an installed tool from the
- "Available tools" section below covers the task (e.g. web search, time lookup,
- scraping, audio, translation, etc.). Only fall back to "http-request" for
- arbitrary external APIs not provided by any installed tool, and to "code" for
- genuine data transformations no tool can express.
+5. INSTALLED-TOOL-FIRST planning: before choosing each functional node, scan the
+ "Relevant installed tools" section below for a semantic capability match. When an installed
+ tool can perform that step, you MUST use a "tool" node instead of "llm",
+ "http-request", or "code". This includes common capabilities such as web search,
+ scraping, time lookup, audio, translation, messaging, and external-service actions.
+ Use "http-request" only for an external API not covered by an installed tool, "code"
+ only for a genuine data transformation, and "llm" only for reasoning or generation
+ the tools do not provide. Never add an unrelated tool merely because it is installed.
6. Each node "label" must be a short, human-readable, Title-Case name (≤ 25 chars).
7. Each node "purpose" is one sentence explaining what it does in this workflow.
- For "tool" nodes, name the chosen tool inside the purpose, e.g.
- "Search the web using google/search.".
+ Every "tool" node MUST also include
+ ``"tool": {"provider_id": "<provider>", "tool_name": "<tool>"}``, copied
+ exactly from Relevant installed tools, and name the same provider/tool in its purpose.
+ Example: ``"purpose": "Search the web using google/search."``.
8. For "iteration" and "loop" nodes (containers), list the container node first
and then EACH inner-pipeline step as its own entry tagged with
``"parent": "<container-label>"``. Container children execute in declaration
@@ -223,7 +228,7 @@ def format_tool_catalogue_section(catalogue_text: str) -> str:
if not catalogue_text.strip():
return ""
return (
- "# Available tools (planner: when picking 'tool' nodes, choose "
- "from this list and reference them by exact provider/tool name)\n\n"
+ "# Relevant installed tools (dynamically selected; when an entry covers a workflow step, "
+ "the planner must choose a 'tool' node and copy its explicit provider_id and tool_name values)\n\n"
f"{catalogue_text}\n\n"
)
diff --git a/api/core/workflow/generator/prompts/tool_router_prompts.py b/api/core/workflow/generator/prompts/tool_router_prompts.py
new file mode 100644
index 00000000000..94af72b8169
--- /dev/null
+++ b/api/core/workflow/generator/prompts/tool_router_prompts.py
@@ -0,0 +1,41 @@
+"""Prompts for extracting installed-tool capability queries.
+
+The router deliberately does not see the installed catalogue. It converts the
+user's request into a handful of concise English search queries; deterministic
+server-side ranking then resolves those queries against the complete catalogue.
+"""
+
+TOOL_ROUTER_SYSTEM_PROMPT = """You route workflow requirements to installed tools.
+
+Identify only capabilities that should be performed by an external or built-in
+tool, such as web search, scraping, current time, translation, media processing,
+messaging, or actions in third-party services. Do not request tools for pure LLM
+reasoning, writing, summarization, classification, templating, branching, or
+ordinary data transformation.
+
+Return exactly one JSON object:
+{
+ "needs_tools": true,
+ "queries": [
+ {
+ "capability": "short English capability phrase",
+ "keywords": ["web", "search", "internet"]
+ }
+ ]
+}
+
+Rules:
+- Set needs_tools=false and queries=[] when no external tool capability is needed.
+- Emit at most 5 queries and at most 8 keywords per query.
+- Translate or normalize non-English requests into English search terms.
+- Describe capabilities, not guessed product or plugin names.
+- Return JSON only, without Markdown or prose.
+"""
+
+
+TOOL_ROUTER_USER_PROMPT = """# User instruction
+
+{instruction}
+
+{ideal_output_section}Return the tool-routing JSON now.
+"""
diff --git a/api/core/workflow/generator/runner.py b/api/core/workflow/generator/runner.py
index 12cbca22d65..a0fa6e3f500 100644
--- a/api/core/workflow/generator/runner.py
+++ b/api/core/workflow/generator/runner.py
@@ -7,6 +7,7 @@ separated from the infrastructure layer.
Pipeline:
+ 0. ROUTER — only for large tool catalogues, extract capability queries.
1. PLANNER — short LLM call producing a high-level node list.
2. BUILDERS — bounded concurrent LLM calls producing compact node configs.
3. POSTPROC — fill safe defaults, lay nodes out left-to-right, dedupe
@@ -17,7 +18,7 @@ Intentionally NOT here (deferred to a future iteration):
- Mermaid rendering
- Broad semantic auto-repair when multiple valid graph interpretations exist
- Multi-step validation engine with classification of fixable vs. user-required errors
- - Tool / model catalogue filtering
+ - Model catalogue filtering
If quality regresses below product threshold we add those back; for now the
planner and bounded parallel node builders shipped behind cmd+k `/create` are
@@ -53,6 +54,18 @@ from core.workflow.generator.prompts.planner_prompts import (
format_ideal_output_section,
format_tool_catalogue_section,
)
+from core.workflow.generator.prompts.tool_router_prompts import TOOL_ROUTER_SYSTEM_PROMPT, TOOL_ROUTER_USER_PROMPT
+from core.workflow.generator.tool_catalogue import (
+ DIRECT_TOOL_INJECTION_LIMIT,
+ ToolCapabilityQuery,
+ ToolCatalogueEntry,
+ find_tool_entry,
+ format_tool_builder_context,
+ format_tool_catalogue,
+ select_legacy_fallback_tools,
+ select_tool_candidates,
+ text_mentions_tool_identifier,
+)
from core.workflow.generator.types import (
GraphDict,
GraphViewportDict,
@@ -106,6 +119,7 @@ _DEFAULT_FILE_UPLOAD_METHODS = ("local_file", "remote_url")
# is generous headroom while still bounding a runaway response. Builder calls
# keep the caller's budget so complex node configs are not truncated.
_PLANNER_DEFAULT_MAX_TOKENS = 4096
+_TOOL_ROUTER_MAX_TOKENS = 256
# Per-node calls trade a larger request count for a shorter critical path.
@@ -305,6 +319,28 @@ def _build_plan_event(
}
+def _find_planned_tool_entry(node: dict[str, Any], entries: list[ToolCatalogueEntry]) -> ToolCatalogueEntry | None:
+ """Resolve the installed tool selected by one planner node.
+
+ New planner responses carry a structured ``tool`` selector. The purpose
+ fallback keeps older/smaller models useful when they follow the instruction
+ to name ``provider/tool`` but omit the optional object.
+ """
+ tool_selector = node.get("tool")
+ if isinstance(tool_selector, dict):
+ provider_name = str(tool_selector.get("provider_id") or tool_selector.get("provider_name") or "")
+ tool_name = str(tool_selector.get("tool_name") or "")
+ entry = find_tool_entry(entries, provider_name, tool_name)
+ if entry is not None:
+ return entry
+
+ purpose = str(node.get("purpose") or "")
+ for entry in entries:
+ if text_mentions_tool_identifier(purpose, entry["provider_name"], entry["tool_name"]):
+ return entry
+ return None
+
+
def _stage_error_to_envelope_code(exc: Exception) -> str:
"""Map a stage-typed exception to the result envelope's error code."""
if isinstance(exc, _StageJSONError):
@@ -336,6 +372,7 @@ class WorkflowGenerator:
instruction: str,
ideal_output: str = "",
tool_catalogue_text: str = "",
+ tool_catalogue_entries: list[ToolCatalogueEntry] | None = None,
installed_tools: set[tuple[str, str]] | None = None,
current_graph: dict[str, Any] | None = None,
) -> WorkflowGenerateResultDict:
@@ -353,13 +390,16 @@ class WorkflowGenerator:
marked ``keep`` are reused without an LLM call. ``None`` (the default)
is plain create-from-scratch behaviour.
- ``tool_catalogue_text`` is the formatted list of installed tools for
- the calling tenant (see ``tool_catalogue.build_tool_catalogue`` /
- ``format_tool_catalogue``). It's injected into both the planner and
- builder prompts so the LLM can pick concrete ``provider/tool``
- identifiers instead of inventing names; node builders receive it
- only for tool nodes. An empty string skips the section entirely (useful
- for unit tests).
+ ``tool_catalogue_text`` is an optional preformatted compatibility
+ override. Production calls leave it empty so the runner can dynamically
+ select relevant entries from ``tool_catalogue_entries`` after seeing
+ the instruction. Tests and internal callers may still supply text
+ directly, which bypasses routing.
+
+ ``tool_catalogue_entries`` carries the complete catalogue as structured
+ server-owned metadata. Small catalogues are injected directly; large
+ ones are routed to a relevant subset for the planner. Tool builders,
+ hydration, and validation continue to use the complete inventory.
``installed_tools`` is the structural sibling — a set of
``(provider_name, tool_name)`` pairs the validator consults to reject
@@ -391,6 +431,7 @@ class WorkflowGenerator:
instruction=instruction,
ideal_output=ideal_output,
tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_entries=tool_catalogue_entries,
installed_tools=installed_tools,
current_graph=current_graph,
):
@@ -415,6 +456,7 @@ class WorkflowGenerator:
instruction: str,
ideal_output: str = "",
tool_catalogue_text: str = "",
+ tool_catalogue_entries: list[ToolCatalogueEntry] | None = None,
installed_tools: set[tuple[str, str]] | None = None,
current_graph: dict[str, Any] | None = None,
) -> Iterator[tuple[str, dict[str, Any]]]:
@@ -438,6 +480,7 @@ class WorkflowGenerator:
instruction=instruction,
ideal_output=ideal_output,
tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_entries=tool_catalogue_entries,
installed_tools=installed_tools,
current_graph=current_graph,
)
@@ -455,6 +498,7 @@ class WorkflowGenerator:
instruction: str,
ideal_output: str = "",
tool_catalogue_text: str = "",
+ tool_catalogue_entries: list[ToolCatalogueEntry] | None = None,
installed_tools: set[tuple[str, str]] | None = None,
current_graph: dict[str, Any] | None = None,
) -> Iterator[tuple[str, dict[str, Any]]]:
@@ -470,6 +514,17 @@ class WorkflowGenerator:
stamped with the resolved concrete ``mode``.
"""
+ full_tool_catalogue_entries = tool_catalogue_entries or []
+ planner_tool_catalogue_text = cls._resolve_prompt_tool_catalogue(
+ model_instance=model_instance,
+ model_parameters=model_parameters,
+ instruction=instruction,
+ ideal_output=ideal_output,
+ tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_entries=full_tool_catalogue_entries,
+ current_graph=current_graph,
+ )
+
# ── 1. PLANNER ────────────────────────────────────────────────────
plan, plan_err = cls._run_stage(
stage="Planner",
@@ -480,7 +535,7 @@ class WorkflowGenerator:
mode=mode,
instruction=instruction,
ideal_output=ideal_output,
- tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_text=planner_tool_catalogue_text,
current_graph=current_graph,
),
)
@@ -538,7 +593,8 @@ class WorkflowGenerator:
ideal_output=ideal_output,
plan_nodes=plan_nodes,
plan_edges=plan_edges,
- tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_text=planner_tool_catalogue_text,
+ tool_catalogue_entries=full_tool_catalogue_entries,
start_inputs=start_inputs,
current_graph=current_graph,
)
@@ -562,6 +618,11 @@ class WorkflowGenerator:
graph = cast(GraphDict, graph)
# ── 3. POSTPROC + VALIDATE ────────────────────────────────────────
+ cls._hydrate_tool_nodes(
+ graph=graph,
+ plan_nodes=plan_nodes,
+ tool_catalogue_entries=full_tool_catalogue_entries,
+ )
graph = cls._postprocess_graph(graph=graph, mode=resolved_mode)
# ``app_name`` / ``icon`` are planner display metadata; both default
@@ -613,6 +674,163 @@ class WorkflowGenerator:
logger.exception("Workflow generator: %s step failed", stage.lower())
return None, _err(WorkflowGenerateErrorCode.MODEL_ERROR, f"{failure_fallback_message}: {e}")
+ # ------------------------------------------------------------------
+ # Tool routing
+ # ------------------------------------------------------------------
+ @classmethod
+ def _resolve_prompt_tool_catalogue(
+ cls,
+ *,
+ model_instance,
+ model_parameters: dict[str, Any],
+ instruction: str,
+ ideal_output: str,
+ tool_catalogue_text: str,
+ tool_catalogue_entries: list[ToolCatalogueEntry],
+ current_graph: dict[str, Any] | None,
+ ) -> str:
+ """Return the relevant installed-tool text for the planner.
+
+ A non-empty preformatted string is an explicit compatibility override.
+ Production service calls pass the complete structured catalogue and let
+ this method dynamically route large inventories. Router failures are
+ intentionally non-fatal and fall back to the legacy 80-tool prompt.
+ """
+ if tool_catalogue_text.strip():
+ return tool_catalogue_text
+ tool_count = len(tool_catalogue_entries)
+ if not tool_catalogue_entries:
+ return ""
+ if tool_count <= DIRECT_TOOL_INJECTION_LIMIT:
+ logger.info(
+ "Workflow generator: tool catalogue selection mode=direct total=%s query_count=0 "
+ "candidates=%s elapsed_ms=0.0",
+ tool_count,
+ tool_count,
+ )
+ return format_tool_catalogue(tool_catalogue_entries, max_tools=None)
+
+ started_at = time.monotonic()
+ explicit_text = f"{instruction}\n{ideal_output}"
+ query_count = 0
+ candidate_count = 0
+ try:
+ needs_tools, queries = cls._run_tool_router(
+ model_instance=model_instance,
+ model_parameters=model_parameters,
+ instruction=instruction,
+ ideal_output=ideal_output,
+ )
+ query_count = len(queries)
+ selection = select_tool_candidates(
+ tool_catalogue_entries,
+ queries if needs_tools else [],
+ explicit_text=explicit_text,
+ current_graph=current_graph,
+ )
+ candidate_count = len(selection.entries)
+ if selection.unmatched_queries:
+ fallback_entries = select_legacy_fallback_tools(
+ tool_catalogue_entries,
+ explicit_text=explicit_text,
+ current_graph=current_graph,
+ )
+ logger.warning(
+ "Workflow generator: tool catalogue selection mode=fallback reason=unmatched_query "
+ "total=%s query_count=%s candidates=%s pinned=%s elapsed_ms=%.1f",
+ tool_count,
+ query_count,
+ len(fallback_entries),
+ selection.pinned_count,
+ (time.monotonic() - started_at) * 1000,
+ )
+ return format_tool_catalogue(fallback_entries, max_tools=None)
+
+ logger.info(
+ "Workflow generator: tool catalogue selection mode=routed total=%s needs_tools=%s "
+ "query_count=%s candidates=%s pinned=%s elapsed_ms=%.1f",
+ tool_count,
+ needs_tools,
+ query_count,
+ candidate_count,
+ selection.pinned_count,
+ (time.monotonic() - started_at) * 1000,
+ )
+ return format_tool_catalogue(selection.entries, max_tools=None)
+ except Exception as e:
+ fallback_entries = select_legacy_fallback_tools(
+ tool_catalogue_entries,
+ explicit_text=explicit_text,
+ current_graph=current_graph,
+ )
+ logger.warning(
+ "Workflow generator: tool catalogue selection mode=fallback reason=%s total=%s "
+ "query_count=%s candidates=%s elapsed_ms=%.1f",
+ type(e).__name__,
+ tool_count,
+ query_count,
+ len(fallback_entries),
+ (time.monotonic() - started_at) * 1000,
+ )
+ return format_tool_catalogue(fallback_entries, max_tools=None)
+
+ @classmethod
+ def _run_tool_router(
+ cls,
+ *,
+ model_instance,
+ model_parameters: dict[str, Any],
+ instruction: str,
+ ideal_output: str,
+ ) -> tuple[bool, list[ToolCapabilityQuery]]:
+ user_prompt = TOOL_ROUTER_USER_PROMPT.format(
+ instruction=instruction.strip(),
+ ideal_output_section=format_ideal_output_section(ideal_output),
+ )
+ response = cls._invoke_with_retry(
+ model_instance=model_instance,
+ prompt_messages=[
+ SystemPromptMessage(content=TOOL_ROUTER_SYSTEM_PROMPT),
+ UserPromptMessage(content=user_prompt),
+ ],
+ model_parameters=_clamp_for_tool_router(model_parameters),
+ stage="Tool Router",
+ )
+ response_text = response.message.get_text_content() or ""
+ try:
+ parsed = json_repair.loads(response_text)
+ except Exception as e:
+ raise _StageJSONError("Tool Router", str(e)) from e
+ if not isinstance(parsed, dict):
+ raise _StageJSONError("Tool Router", f"Non-object JSON: {type(parsed).__name__}")
+
+ needs_tools = parsed.get("needs_tools")
+ raw_queries = parsed.get("queries")
+ if not isinstance(needs_tools, bool):
+ raise _StageSchemaError("Tool Router", "needs_tools must be a boolean")
+ if not isinstance(raw_queries, list):
+ raise _StageSchemaError("Tool Router", "queries must be an array")
+ if not needs_tools:
+ return False, []
+
+ queries: list[ToolCapabilityQuery] = []
+ for raw_query in raw_queries[:5]:
+ if not isinstance(raw_query, dict):
+ continue
+ raw_capability = raw_query.get("capability")
+ capability = raw_capability.strip() if isinstance(raw_capability, str) else ""
+ raw_keywords = raw_query.get("keywords")
+ keywords = (
+ [keyword.strip() for keyword in raw_keywords[:8] if isinstance(keyword, str) and keyword.strip()]
+ if isinstance(raw_keywords, list)
+ else []
+ )
+ if capability:
+ queries.append(ToolCapabilityQuery(capability=capability, keywords=keywords))
+ if not queries:
+ raise _StageSchemaError("Tool Router", "needs_tools=true requires at least one capability query")
+ return True, queries
+
# ------------------------------------------------------------------
# Shared LLM call + JSON parse with one-shot retry
# ------------------------------------------------------------------
@@ -810,6 +1028,7 @@ class WorkflowGenerator:
plan_nodes: list[dict[str, Any]],
plan_edges: list[dict[str, Any]],
tool_catalogue_text: str,
+ tool_catalogue_entries: list[ToolCatalogueEntry],
start_inputs: list[dict[str, Any]],
current_graph: dict[str, Any] | None,
) -> GraphDict:
@@ -853,6 +1072,7 @@ class WorkflowGenerator:
target_node=node,
plan_json=plan_json,
tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_entries=tool_catalogue_entries,
start_inputs=start_inputs,
existing_node=existing_by_id.get(str(node.get("id"))),
): str(node.get("id"))
@@ -894,6 +1114,7 @@ class WorkflowGenerator:
target_node: dict[str, Any],
plan_json: str,
tool_catalogue_text: str,
+ tool_catalogue_entries: list[ToolCatalogueEntry],
start_inputs: list[dict[str, Any]],
existing_node: dict[str, Any] | None,
) -> dict[str, Any]:
@@ -912,6 +1133,14 @@ class WorkflowGenerator:
"# Existing config to preserve unless the instruction changes it\n\n"
f"{json.dumps(existing_data, ensure_ascii=False, separators=(',', ':'))}\n\n"
)
+ tool_catalogue_section = ""
+ if node_type == BuiltinNodeTypes.TOOL:
+ selected_tool = _find_planned_tool_entry(target_node, tool_catalogue_entries)
+ tool_catalogue_section = (
+ format_tool_builder_context(selected_tool)
+ if selected_tool is not None
+ else format_node_tool_catalogue_section(tool_catalogue_text)
+ )
user_prompt = NODE_BUILDER_USER_PROMPT.format(
node_id=node_id,
node_type=node_type,
@@ -921,9 +1150,7 @@ class WorkflowGenerator:
ideal_output_section=format_ideal_output_section(ideal_output),
mode_section=mode_section,
model_section=model_section,
- tool_catalogue_section=(
- format_node_tool_catalogue_section(tool_catalogue_text) if node_type == BuiltinNodeTypes.TOOL else ""
- ),
+ tool_catalogue_section=tool_catalogue_section,
start_inputs_section=(
format_start_inputs_section(start_inputs) if node_type == BuiltinNodeTypes.START else ""
),
@@ -944,6 +1171,99 @@ class WorkflowGenerator:
raise _StageSchemaError(f"Builder {node_id}", "missing 'config' object")
return cast(dict[str, Any], config)
+ @staticmethod
+ def _hydrate_tool_nodes(
+ *,
+ graph: GraphDict,
+ plan_nodes: list[dict[str, Any]],
+ tool_catalogue_entries: list[ToolCatalogueEntry],
+ ) -> None:
+ """Stamp generated tool nodes with trusted installed-tool metadata.
+
+ The model still owns variable bindings, but provider identity, plugin
+ metadata, parameter declarations, output schema, and form defaults are
+ deterministic catalogue data. Hydrating them here prevents a selected
+ installed plugin from becoming an unusable guessed node configuration.
+ """
+ if not tool_catalogue_entries:
+ return
+ planned_by_id = {
+ str(node.get("id") or ""): node
+ for node in plan_nodes
+ if node.get("node_type") == BuiltinNodeTypes.TOOL and node.get("id")
+ }
+ for node in graph.get("nodes") or []:
+ planned = planned_by_id.get(str(node.get("id") or ""))
+ if planned is None:
+ continue
+ data = node.get("data")
+ if not isinstance(data, dict):
+ continue
+ entry = _find_planned_tool_entry(planned, tool_catalogue_entries)
+ if entry is None:
+ entry = find_tool_entry(
+ tool_catalogue_entries,
+ str(data.get("provider_id") or data.get("provider_name") or ""),
+ str(data.get("tool_name") or ""),
+ )
+ if entry is None:
+ continue
+
+ data.update(
+ {
+ "provider_id": entry["provider_name"],
+ "provider_name": entry["provider_name"],
+ "provider_type": entry["provider_type"],
+ "tool_name": entry["tool_name"],
+ "tool_label": entry["tool_label"] or entry["tool_name"],
+ "tool_description": entry.get("description", ""),
+ "tool_node_version": "2",
+ }
+ )
+ for field in ("plugin_id", "plugin_unique_identifier"):
+ value = entry.get(field, "")
+ if value:
+ data[field] = value
+ else:
+ data.pop(field, None)
+
+ parameters = deepcopy(entry.get("parameters") or [])
+ data["paramSchemas"] = parameters
+ parameter_names = [str(parameter.get("name")) for parameter in parameters if parameter.get("name")]
+ parameter_name_set = set(parameter_names)
+ llm_parameter_names = {
+ str(parameter.get("name"))
+ for parameter in parameters
+ if parameter.get("name") and parameter.get("form") != "form"
+ }
+ form_parameter_names = parameter_name_set - llm_parameter_names
+ data["params"] = dict.fromkeys(parameter_names, "")
+
+ raw_tool_parameters = data.get("tool_parameters")
+ data["tool_parameters"] = (
+ {name: value for name, value in raw_tool_parameters.items() if name in llm_parameter_names}
+ if isinstance(raw_tool_parameters, dict)
+ else {}
+ )
+ raw_configurations = data.get("tool_configurations")
+ configurations = (
+ {name: value for name, value in raw_configurations.items() if name in form_parameter_names}
+ if isinstance(raw_configurations, dict)
+ else {}
+ )
+ data["tool_configurations"] = configurations
+ for parameter in parameters:
+ if parameter.get("form") != "form" or parameter.get("default") is None:
+ continue
+ name = str(parameter.get("name") or "")
+ if name:
+ configurations.setdefault(
+ name,
+ {"type": "constant", "value": deepcopy(parameter["default"])},
+ )
+ output_schema = entry.get("output_schema") or {}
+ data["output_schema"] = deepcopy(output_schema)
+
@classmethod
def _assemble_parallel_graph(
cls,
@@ -2455,6 +2775,14 @@ def _clamp_for_planner(params: dict[str, Any]) -> dict[str, Any]:
return out
+def _clamp_for_tool_router(params: dict[str, Any]) -> dict[str, Any]:
+ """Use a small deterministic budget for capability-query extraction."""
+ out = dict(params)
+ out["temperature"] = 0.1
+ out["max_tokens"] = _TOOL_ROUTER_MAX_TOKENS
+ return out
+
+
def _label_from_variable(var: str) -> str:
"""Turn ``snake_case`` / ``camelCase`` into a Title-Cased UI label."""
if not var:
diff --git a/api/core/workflow/generator/tool_catalogue.py b/api/core/workflow/generator/tool_catalogue.py
index 98450ff4214..83eb902abc7 100644
--- a/api/core/workflow/generator/tool_catalogue.py
+++ b/api/core/workflow/generator/tool_catalogue.py
@@ -10,34 +10,86 @@ tool_label).
Format: one tool per line, ``- <provider>/<tool> — <one-line description>``.
-The list is intentionally capped — if a tenant has hundreds of plugin tools,
-sending the full catalogue blows past LLM context windows. We sort by
-provider name and truncate to ``_MAX_TOOLS`` lines so the prompt stays
-bounded. Tools beyond the cap are dropped silently; if quality suffers, the
-fix is a planner-time relevance filter, not a bigger dump.
+The prompt representation is intentionally capped — if a tenant has hundreds
+of plugin tools, sending the full catalogue blows past LLM context windows.
+``build_tool_catalogue`` still returns the COMPLETE installed inventory because
+the validator and node hydrator must never mistake an installed tool beyond the
+prompt cap for a missing one. ``format_tool_catalogue`` alone truncates the
+sorted inventory to ``_MAX_PROMPT_TOOLS`` lines.
"""
+import json
import logging
+import re
+import unicodedata
+from dataclasses import dataclass
+from difflib import SequenceMatcher
from operator import itemgetter
-from typing import TypedDict
+from typing import Any, NotRequired, TypedDict
from core.tools.builtin_tool.provider import BuiltinToolProviderController
+from core.tools.entities.common_entities import I18nObject
+from core.tools.entities.tool_entities import ToolDescription
from core.tools.plugin_tool.provider import PluginToolProviderController
from core.tools.tool_manager import ToolManager
logger = logging.getLogger(__name__)
-_MAX_TOOLS = 80
+_MAX_PROMPT_TOOLS = 80
+DIRECT_TOOL_INJECTION_LIMIT = 24
+MAX_ROUTED_TOOL_CANDIDATES = 16
+MAX_ROUTED_TOOLS_PER_QUERY = 3
+MAX_ROUTED_TOOLS_PER_PROVIDER = 4
+
+_MAX_FUZZY_TEXT_LENGTH = 160
+_MIN_NAME_FUZZY_RATIO = 0.72
+_TOKEN_PATTERN = re.compile(r"[^\W_]+", re.UNICODE)
+_CAMEL_BOUNDARY_PATTERN = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+_TOOL_IDENTIFIER_LEFT_BOUNDARY = r"(?<![\w/.:@-])"
+_TOOL_IDENTIFIER_RIGHT_BOUNDARY = r"(?![\w/@-]|[.:][\w])"
+_QUERY_STOP_WORDS = frozenset(
+ {
+ "a",
+ "an",
+ "and",
+ "for",
+ "from",
+ "in",
+ "of",
+ "on",
+ "or",
+ "the",
+ "to",
+ "tool",
+ "using",
+ "with",
+ }
+)
class ToolCatalogueEntry(TypedDict):
provider_name: str
- provider_type: str # "builtin" | "plugin" — what the workflow tool node uses
+ provider_type: str # "builtin" | "api" | "workflow" | "mcp" — workflow node value
plugin_id: str # empty string for hardcoded built-ins
+ plugin_unique_identifier: NotRequired[str]
tool_name: str
tool_label: str
description: str # one-line LLM-friendly description
+ parameters: NotRequired[list[dict[str, Any]]]
+ output_schema: NotRequired[dict[str, Any]]
+
+
+class ToolCapabilityQuery(TypedDict):
+ capability: str
+ keywords: list[str]
+
+
+@dataclass(frozen=True)
+class ToolCandidateSelection:
+ entries: list[ToolCatalogueEntry]
+ unmatched_queries: list[str]
+ pinned_count: int
def build_tool_catalogue(tenant_id: str) -> list[ToolCatalogueEntry]:
@@ -46,19 +98,25 @@ def build_tool_catalogue(tenant_id: str) -> list[ToolCatalogueEntry]:
Failures inside a single provider (mis-declared tool, plugin runtime
error) are logged and skipped — one bad provider must not break the
- whole generator. Returns at most ``_MAX_TOOLS`` entries.
+ whole generator. Returns the complete installed inventory; prompt-specific
+ truncation belongs to ``format_tool_catalogue``.
"""
entries: list[ToolCatalogueEntry] = []
for provider in ToolManager.list_builtin_providers(tenant_id):
provider_name = provider.entity.identity.name
plugin_id = ""
- # Hardcoded built-ins return "builtin"; plugin providers return "plugin".
- # Use the provider's own declared value so the catalogue matches what
- # ``tool`` workflow nodes need in their ``data.provider_type`` field.
- provider_type = provider.provider_type.value
+ # The tool-provider domain distinguishes hardcoded providers from
+ # plugin providers ("builtin" vs "plugin"), while workflow tool nodes
+ # deliberately group BOTH under provider_type="builtin". This mirrors
+ # ToolTransformService.builtin_provider_to_user_provider and the web
+ # CollectionType contract; leaking "plugin" here makes generated nodes
+ # invisible to the canvas' installed-tool collection.
+ provider_type = "builtin"
+ plugin_unique_identifier = ""
if isinstance(provider, PluginToolProviderController):
plugin_id = provider.plugin_id or ""
+ plugin_unique_identifier = provider.plugin_unique_identifier or ""
elif not isinstance(provider, BuiltinToolProviderController):
# Unknown provider class — skip rather than guess.
continue
@@ -82,21 +140,23 @@ def build_tool_catalogue(tenant_id: str) -> list[ToolCatalogueEntry]:
provider_name=provider_name,
provider_type=provider_type,
plugin_id=plugin_id,
+ plugin_unique_identifier=plugin_unique_identifier,
tool_name=tool_name,
tool_label=tool_label,
description=description,
+ parameters=[parameter.model_dump(mode="json") for parameter in tool.entity.parameters],
+ output_schema=dict(tool.entity.output_schema),
)
)
except Exception:
logger.exception(
- "Workflow generator: failed to describe tool %s in provider %s",
- getattr(getattr(tool, "entity", None), "identity", None),
+ "Workflow generator: failed to describe a tool in provider %s",
provider_name,
)
continue
entries.sort(key=itemgetter("provider_name", "tool_name"))
- return entries[:_MAX_TOOLS]
+ return entries
def installed_tool_keys(entries: list[ToolCatalogueEntry]) -> set[tuple[str, str]]:
@@ -114,40 +174,333 @@ def installed_tool_keys(entries: list[ToolCatalogueEntry]) -> set[tuple[str, str
return {(e["provider_name"], e["tool_name"]) for e in entries}
-def format_tool_catalogue(entries: list[ToolCatalogueEntry]) -> str:
+def format_tool_catalogue(entries: list[ToolCatalogueEntry], *, max_tools: int | None = _MAX_PROMPT_TOOLS) -> str:
"""
- Render the catalogue as a compact multi-line block for prompt injection.
- Returns an empty string when no tools are installed — callers should skip
- the section entirely in that case.
+ Render a compact multi-line catalogue for prompt
+ injection. Returns an empty string when no tools are installed — callers
+ should skip the section entirely in that case. The default preserves the
+ legacy cap; routed callers pass ``max_tools=None`` for their selected set.
"""
if not entries:
return ""
lines = []
- for e in entries:
+ prompt_entries = entries if max_tools is None else entries[:max_tools]
+ for e in prompt_entries:
desc = e["description"].replace("\n", " ").strip()
if len(desc) > 120:
desc = desc[:117] + "..."
line = f"- {e['provider_name']}/{e['tool_name']}"
if e["tool_label"] and e["tool_label"] != e["tool_name"]:
line += f" ({e['tool_label']})"
+ # provider names for plugin tools commonly contain slashes themselves
+ # (for example ``langgenius/google/google``). Explicit JSON-quoted
+ # fields remove the ambiguous "split on the last slash" guess while
+ # retaining the readable provider/tool display id.
+ line += (
+ f" [provider_id={json.dumps(e['provider_name'], ensure_ascii=False)}; "
+ f"tool_name={json.dumps(e['tool_name'], ensure_ascii=False)}]"
+ )
if desc:
line += f" — {desc}"
lines.append(line)
return "\n".join(lines)
-def _i18n_text(label) -> str:
- """Pull the English label out of an I18nObject (falls back to .name)."""
+def find_tool_entry(entries: list[ToolCatalogueEntry], provider_name: str, tool_name: str) -> ToolCatalogueEntry | None:
+ """Return one exact installed-tool entry, or ``None`` when unavailable."""
+ provider_name = provider_name.strip()
+ tool_name = tool_name.strip()
+ for entry in entries:
+ if entry["provider_name"] == provider_name and entry["tool_name"] == tool_name:
+ return entry
+ return None
+
+
+def text_mentions_tool_identifier(
+ text: str,
+ provider_name: str,
+ tool_name: str,
+ *,
+ ignore_case: bool = False,
+) -> bool:
+ """Return whether text contains one complete ``provider/tool`` identifier."""
+ identifier = f"{provider_name}/{tool_name}"
+ flags = re.IGNORECASE if ignore_case else 0
+ return bool(
+ re.search(
+ rf"{_TOOL_IDENTIFIER_LEFT_BOUNDARY}{re.escape(identifier)}{_TOOL_IDENTIFIER_RIGHT_BOUNDARY}",
+ text,
+ flags=flags,
+ )
+ )
+
+
+def select_tool_candidates(
+ entries: list[ToolCatalogueEntry],
+ queries: list[ToolCapabilityQuery],
+ *,
+ explicit_text: str = "",
+ current_graph: dict[str, Any] | None = None,
+) -> ToolCandidateSelection:
+ """Select a small, deterministic prompt catalogue from the full inventory.
+
+ Exact identifiers in the request and tools already present in a refine
+ graph are pinned. Routed candidates are ranked independently per capability
+ and then merged under global and per-provider diversity caps. Pinned tools
+ are never dropped by those caps.
+ """
+ pinned_keys = _find_explicit_tool_keys(entries, explicit_text)
+ pinned_keys.update(_find_current_graph_tool_keys(entries, current_graph))
+ entries_by_key = {(entry["provider_name"], entry["tool_name"]): entry for entry in entries}
+ pinned = [entry for entry in entries if (entry["provider_name"], entry["tool_name"]) in pinned_keys]
+
+ candidate_scores: dict[tuple[str, str], float] = {}
+ unmatched_queries: list[str] = []
+ for query in queries[:5]:
+ ranked = _rank_tools_for_query(entries, query)
+ confident = [(score, entry) for score, entry, is_confident in ranked if is_confident]
+ if not confident:
+ capability = str(query.get("capability") or "").strip()
+ if capability:
+ unmatched_queries.append(capability)
+ continue
+ for score, entry in confident[:MAX_ROUTED_TOOLS_PER_QUERY]:
+ key = (entry["provider_name"], entry["tool_name"])
+ candidate_scores[key] = max(score, candidate_scores.get(key, 0.0))
+
+ ranked_keys = sorted(
+ candidate_scores,
+ key=lambda key: (-candidate_scores[key], key[0], key[1]),
+ )
+ provider_counts: dict[str, int] = {}
+ routed: list[ToolCatalogueEntry] = []
+ for key in ranked_keys:
+ if key in pinned_keys:
+ continue
+ provider_name = key[0]
+ if provider_counts.get(provider_name, 0) >= MAX_ROUTED_TOOLS_PER_PROVIDER:
+ continue
+ routed.append(entries_by_key[key])
+ provider_counts[provider_name] = provider_counts.get(provider_name, 0) + 1
+ if len(routed) >= MAX_ROUTED_TOOL_CANDIDATES:
+ break
+
+ return ToolCandidateSelection(
+ entries=[*pinned, *routed],
+ unmatched_queries=unmatched_queries,
+ pinned_count=len(pinned),
+ )
+
+
+def select_legacy_fallback_tools(
+ entries: list[ToolCatalogueEntry],
+ *,
+ explicit_text: str = "",
+ current_graph: dict[str, Any] | None = None,
+) -> list[ToolCatalogueEntry]:
+ """Keep pinned tools while reproducing the legacy bounded prompt fallback."""
+ pinned = select_tool_candidates(
+ entries,
+ [],
+ explicit_text=explicit_text,
+ current_graph=current_graph,
+ ).entries
+ pinned_keys = {(entry["provider_name"], entry["tool_name"]) for entry in pinned}
+ regular_limit = max(0, _MAX_PROMPT_TOOLS - len(pinned))
+ regular = [entry for entry in entries if (entry["provider_name"], entry["tool_name"]) not in pinned_keys][
+ :regular_limit
+ ]
+ return [*pinned, *regular]
+
+
+def _find_explicit_tool_keys(
+ entries: list[ToolCatalogueEntry],
+ text: str,
+) -> set[tuple[str, str]]:
+ if not text.strip():
+ return set()
+ keys: set[tuple[str, str]] = set()
+ for entry in entries:
+ if text_mentions_tool_identifier(
+ text,
+ entry["provider_name"],
+ entry["tool_name"],
+ ignore_case=True,
+ ):
+ keys.add((entry["provider_name"], entry["tool_name"]))
+ return keys
+
+
+def _find_current_graph_tool_keys(
+ entries: list[ToolCatalogueEntry],
+ current_graph: dict[str, Any] | None,
+) -> set[tuple[str, str]]:
+ if not current_graph:
+ return set()
+ installed = {(entry["provider_name"], entry["tool_name"]) for entry in entries}
+ keys: set[tuple[str, str]] = set()
+ for node in current_graph.get("nodes") or []:
+ if not isinstance(node, dict):
+ continue
+ data = node.get("data")
+ if not isinstance(data, dict) or data.get("type") != "tool":
+ continue
+ key = (
+ str(data.get("provider_id") or data.get("provider_name") or "").strip(),
+ str(data.get("tool_name") or "").strip(),
+ )
+ if key in installed:
+ keys.add(key)
+ return keys
+
+
+def _rank_tools_for_query(
+ entries: list[ToolCatalogueEntry], query: ToolCapabilityQuery
+) -> list[tuple[float, ToolCatalogueEntry, bool]]:
+ capability = str(query.get("capability") or "").strip()
+ keywords = [str(keyword).strip() for keyword in (query.get("keywords") or []) if str(keyword).strip()]
+ query_text = " ".join([capability, *keywords]).strip()
+ query_normalized = _normalize_search_text(query_text)
+ query_tokens = _search_tokens(query_text)
+ ranked: list[tuple[float, ToolCatalogueEntry, bool]] = []
+
+ for entry in entries:
+ identifier = f"{entry['provider_name']}/{entry['tool_name']}"
+ name_text = f"{entry['provider_name']} {entry['tool_name']}"
+ label_text = entry["tool_label"]
+ description_text = entry["description"]
+ name_tokens = _search_tokens(name_text)
+ label_tokens = _search_tokens(label_text)
+ description_tokens = _search_tokens(description_text)
+ name_overlap = len(query_tokens & name_tokens)
+ label_overlap = len(query_tokens & label_tokens)
+ description_overlap = len(query_tokens & description_tokens)
+
+ normalized_identifier = _normalize_search_text(identifier)
+ normalized_name = _normalize_search_text(entry["tool_name"])
+ normalized_label = _normalize_search_text(label_text)
+ normalized_description = _normalize_search_text(description_text)
+ phrase_bonus = 0.0
+ if query_normalized and query_normalized in normalized_identifier:
+ phrase_bonus = 8.0
+ elif query_normalized and query_normalized in normalized_label:
+ phrase_bonus = 6.0
+ elif query_normalized and query_normalized in normalized_description:
+ phrase_bonus = 2.0
+
+ fuzzy_ratio = max(
+ _fuzzy_ratio(query_normalized, normalized_name),
+ _fuzzy_ratio(query_normalized, normalized_label),
+ )
+ score = phrase_bonus + name_overlap * 5.0 + label_overlap * 3.0 + description_overlap + fuzzy_ratio
+ is_confident = bool(
+ name_overlap or label_overlap or description_overlap or fuzzy_ratio >= _MIN_NAME_FUZZY_RATIO
+ )
+ ranked.append((score, entry, is_confident))
+
+ ranked.sort(key=lambda item: (-item[0], item[1]["provider_name"], item[1]["tool_name"]))
+ return ranked
+
+
+def _normalize_search_text(text: str) -> str:
+ camel_spaced = _CAMEL_BOUNDARY_PATTERN.sub(" ", unicodedata.normalize("NFKC", text))
+ return " ".join(_TOKEN_PATTERN.findall(camel_spaced.replace("_", " ").replace("-", " "))).casefold()
+
+
+def _search_tokens(text: str) -> set[str]:
+ return {
+ token for token in _normalize_search_text(text).split() if len(token) > 1 and token not in _QUERY_STOP_WORDS
+ }
+
+
+def _fuzzy_ratio(query: str, candidate: str) -> float:
+ if not query or not candidate:
+ return 0.0
+ return SequenceMatcher(
+ None,
+ query[:_MAX_FUZZY_TEXT_LENGTH],
+ candidate[:_MAX_FUZZY_TEXT_LENGTH],
+ autojunk=False,
+ ).ratio()
+
+
+def format_tool_builder_context(entry: ToolCatalogueEntry) -> str:
+ """Render the exact node identity and parameter contract for one tool.
+
+ The planner sees the compact multi-tool catalogue; a tool node builder only
+ needs the selected entry. Keeping this context focused both reduces tokens
+ and prevents the builder from silently switching to another installed tool.
+ """
+ identity = {
+ "provider_id": entry["provider_name"],
+ "provider_name": entry["provider_name"],
+ "provider_type": entry["provider_type"],
+ "plugin_id": entry.get("plugin_id", ""),
+ "plugin_unique_identifier": entry.get("plugin_unique_identifier", ""),
+ "tool_name": entry["tool_name"],
+ "tool_label": entry["tool_label"] or entry["tool_name"],
+ }
+ lines = [
+ "# Selected installed tool",
+ "",
+ "Copy these identity fields EXACTLY; do not switch tools or invent identifiers:",
+ json.dumps(identity, ensure_ascii=False, separators=(",", ":")),
+ ]
+
+ description = entry.get("description", "").replace("\n", " ").strip()
+ if description:
+ lines.extend(["", f"Capability: {description}"])
+
+ parameters = entry.get("parameters") or []
+ if parameters:
+ lines.extend(
+ [
+ "",
+ "Parameters (form=llm -> tool_parameters; form=form -> tool_configurations):",
+ ]
+ )
+ for parameter in parameters:
+ name = str(parameter.get("name") or "").strip()
+ if not name:
+ continue
+ form = str(parameter.get("form") or "llm")
+ type_ = str(parameter.get("type") or "string")
+ requirement = "required" if parameter.get("required") else "optional"
+ detail = str(parameter.get("llm_description") or "").replace("\n", " ").strip()
+ options = parameter.get("options") or []
+ option_values = [str(option.get("value")) for option in options if isinstance(option, dict)]
+ suffixes = []
+ if option_values:
+ suffixes.append("options=" + json.dumps(option_values, ensure_ascii=False, separators=(",", ":")))
+ if parameter.get("default") is not None:
+ suffixes.append(
+ "default=" + json.dumps(parameter["default"], ensure_ascii=False, separators=(",", ":"))
+ )
+ if detail:
+ suffixes.append(detail[:160])
+ suffix = " — " + "; ".join(suffixes) if suffixes else ""
+ lines.append(f"- {name}: {type_}, form={form}, {requirement}{suffix}")
+
+ lines.extend(
+ [
+ "",
+ "Use upstream variables for required LLM parameters whenever possible. "
+ "Keep declared defaults for form parameters and omit undeclared parameter names.",
+ "",
+ ]
+ )
+ return "\n".join(lines)
+
+
+def _i18n_text(label: I18nObject | None) -> str:
+ """Pull the English label out of an I18nObject, falling back to Chinese."""
if label is None:
return ""
- en = getattr(label, "en_US", None)
- if en:
- return en
- return getattr(label, "zh_Hans", "") or ""
+ return label.en_US or label.zh_Hans or ""
-def _tool_description(description) -> str:
+def _tool_description(description: ToolDescription | None) -> str:
"""Pull the LLM-facing description (``.llm``) from a ToolDescription."""
if description is None:
return ""
- return getattr(description, "llm", "") or ""
+ return description.llm or ""
diff --git a/api/core/workflow/generator/types.py b/api/core/workflow/generator/types.py
index d5afb851117..6c7341e16ea 100644
--- a/api/core/workflow/generator/types.py
+++ b/api/core/workflow/generator/types.py
@@ -63,6 +63,7 @@ class PlannerNodeDict(TypedDict):
purpose: str
parent: NotRequired[str]
action: NotRequired[Literal["keep", "update", "add"]]
+ tool: NotRequired[dict[str, str]]
class PlannerEdgeDict(TypedDict):
diff --git a/api/services/workflow_generator_service.py b/api/services/workflow_generator_service.py
index b7121b8997e..2ac697d28a9 100644
--- a/api/services/workflow_generator_service.py
+++ b/api/services/workflow_generator_service.py
@@ -18,7 +18,11 @@ from typing import Any
from core.app.app_config.entities import ModelConfig
from core.model_manager import ModelInstance, ModelManager
from core.workflow.generator import WorkflowGenerator
-from core.workflow.generator.tool_catalogue import build_tool_catalogue, format_tool_catalogue, installed_tool_keys
+from core.workflow.generator.tool_catalogue import (
+ ToolCatalogueEntry,
+ build_tool_catalogue,
+ installed_tool_keys,
+)
from core.workflow.generator.types import (
WorkflowGenerateResultDict,
WorkflowGenerationModeRequest,
@@ -62,8 +66,8 @@ class WorkflowGeneratorService:
controller can map them to existing HTTP error envelopes (same
envelope as ``/rule-generate``).
"""
- model_instance, model_parameters, tool_catalogue_text, installed_tools = cls._resolve_generation_context(
- tenant_id=tenant_id, model_config=model_config
+ model_instance, model_parameters, tool_catalogue_entries, tool_catalogue_text, installed_tools = (
+ cls._resolve_generation_context(tenant_id=tenant_id, model_config=model_config)
)
return WorkflowGenerator.generate_workflow_graph(
@@ -76,6 +80,7 @@ class WorkflowGeneratorService:
instruction=instruction,
ideal_output=ideal_output,
tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_entries=tool_catalogue_entries,
installed_tools=installed_tools,
current_graph=current_graph,
)
@@ -101,8 +106,8 @@ class WorkflowGeneratorService:
instance propagate to the caller (the controller emits them as a
single ``result`` SSE event).
"""
- model_instance, model_parameters, tool_catalogue_text, installed_tools = cls._resolve_generation_context(
- tenant_id=tenant_id, model_config=model_config
+ model_instance, model_parameters, tool_catalogue_entries, tool_catalogue_text, installed_tools = (
+ cls._resolve_generation_context(tenant_id=tenant_id, model_config=model_config)
)
yield from WorkflowGenerator.generate_workflow_graph_stream(
@@ -115,6 +120,7 @@ class WorkflowGeneratorService:
instruction=instruction,
ideal_output=ideal_output,
tool_catalogue_text=tool_catalogue_text,
+ tool_catalogue_entries=tool_catalogue_entries,
installed_tools=installed_tools,
current_graph=current_graph,
)
@@ -125,7 +131,13 @@ class WorkflowGeneratorService:
*,
tenant_id: str,
model_config: ModelConfig,
- ) -> tuple[ModelInstance, dict[str, Any], str, set[tuple[str, str]] | None]:
+ ) -> tuple[
+ ModelInstance,
+ dict[str, Any],
+ list[ToolCatalogueEntry],
+ str,
+ set[tuple[str, str]] | None,
+ ]:
"""Resolve the model instance, completion params, and tool catalogue.
Build the installed-tool catalogue for this tenant so the planner /
@@ -147,13 +159,19 @@ class WorkflowGeneratorService:
model_parameters: dict[str, Any] = dict(model_config.completion_params or {})
+ tool_catalogue_entries: list[ToolCatalogueEntry] = []
+ # Formatting is instruction-dependent and therefore owned by the
+ # runner. Keep the text slot empty so the complete structured catalogue
+ # can be dynamically routed after the instruction is available.
tool_catalogue_text = ""
installed_tools: set[tuple[str, str]] | None = None
try:
- entries = build_tool_catalogue(tenant_id)
- tool_catalogue_text = format_tool_catalogue(entries)
- installed_tools = installed_tool_keys(entries)
+ tool_catalogue_entries = build_tool_catalogue(tenant_id)
+ installed_tools = installed_tool_keys(tool_catalogue_entries)
except Exception:
logger.exception("Workflow generator: failed to build tool catalogue for tenant %s", tenant_id)
+ tool_catalogue_entries = []
+ tool_catalogue_text = ""
+ installed_tools = None
- return model_instance, model_parameters, tool_catalogue_text, installed_tools
+ return model_instance, model_parameters, tool_catalogue_entries, tool_catalogue_text, installed_tools
diff --git a/api/tests/unit_tests/core/llm_generator/test_llm_generator_missing.py b/api/tests/unit_tests/core/llm_generator/test_llm_generator_missing.py
index fc890f778c9..77c887fef8d 100644
--- a/api/tests/unit_tests/core/llm_generator/test_llm_generator_missing.py
+++ b/api/tests/unit_tests/core/llm_generator/test_llm_generator_missing.py
@@ -170,7 +170,10 @@ class TestBuildSuggestionContext:
result = LLMGenerator._build_suggestion_context("tenant")
assert "Knowledge bases:\n- kb1\n- kb2" in result
- assert "Installed tools:\n- provider/tool1 — First tool\n- provider/tool2 — Second tool" in result
+ assert (
+ 'Installed tools:\n- provider/tool1 [provider_id="provider"; tool_name="tool1"] — First tool\n'
+ '- provider/tool2 [provider_id="provider"; tool_name="tool2"] — Second tool'
+ ) in result
def test_both_fail(self, dataset_session: Session, monkeypatch: pytest.MonkeyPatch):
def fail_query(_orm_execute_state: object) -> None:
diff --git a/api/tests/unit_tests/core/workflow/generator/test_prompts.py b/api/tests/unit_tests/core/workflow/generator/test_prompts.py
index 3b68bb2d888..399cb5465f9 100644
--- a/api/tests/unit_tests/core/workflow/generator/test_prompts.py
+++ b/api/tests/unit_tests/core/workflow/generator/test_prompts.py
@@ -27,6 +27,11 @@ class TestPlannerSystemPrompt:
assert '"mode": "workflow | advanced-chat"' in PLANNER_SYSTEM_PROMPT
assert "When the ``# Mode`` section says auto, YOU decide" in PLANNER_SYSTEM_PROMPT
+ def test_prioritizes_installed_tools_and_requires_structured_selection(self):
+ assert "INSTALLED-TOOL-FIRST" in PLANNER_SYSTEM_PROMPT
+ assert 'you MUST use a "tool" node' in PLANNER_SYSTEM_PROMPT
+ assert '"tool": {"provider_id": "<provider>", "tool_name": "<tool>"}' in PLANNER_SYSTEM_PROMPT
+
class TestFormatIdealOutputSection:
def test_returns_empty_string_for_blank_input(self):
@@ -49,8 +54,8 @@ class TestToolCatalogueSections:
def test_planner_includes_catalogue(self):
out = format_planner_tool_catalogue_section("- google/search — Search.")
- assert "# Available tools" in out
- assert "planner" in out.lower()
+ assert "# Relevant installed tools" in out
+ assert "dynamically selected" in out.lower()
assert "- google/search — Search." in out
def test_node_builder_returns_empty_when_catalogue_is_blank(self):
diff --git a/api/tests/unit_tests/core/workflow/generator/test_runner.py b/api/tests/unit_tests/core/workflow/generator/test_runner.py
index c252abee80a..35ed9f1ad5a 100644
--- a/api/tests/unit_tests/core/workflow/generator/test_runner.py
+++ b/api/tests/unit_tests/core/workflow/generator/test_runner.py
@@ -11,14 +11,15 @@ import json
import threading
import time
from copy import deepcopy
-from typing import Any, cast
-from unittest.mock import MagicMock
+from typing import Any, cast, override
+from unittest.mock import MagicMock, patch
import pytest
from jinja2 import Template
from configs import dify_config
-from core.workflow.generator.runner import WorkflowGenerator
+from core.workflow.generator.runner import WorkflowGenerator, _find_planned_tool_entry
+from core.workflow.generator.tool_catalogue import ToolCatalogueEntry
from core.workflow.generator.types import GraphDict
@@ -98,6 +99,303 @@ class _GraphFixtureModel:
return _llm_result(json.dumps({"config": data}))
+class _RoutingGraphFixtureModel(_GraphFixtureModel):
+ """Graph fixture model with a dedicated response for the optional tool router."""
+
+ def __init__(self, planner: str, graph: str, router_response: str) -> None:
+ self.router_response = router_response
+ self.router_calls: list[dict[str, Any]] = []
+ super().__init__(planner, graph)
+
+ @override
+ def _invoke(self, *, prompt_messages, model_parameters, stream):
+ system_prompt = str(prompt_messages[0].content)
+ if "route workflow requirements" in system_prompt.lower():
+ self.router_calls.append(
+ {
+ "prompt_messages": list(prompt_messages),
+ "model_parameters": dict(model_parameters),
+ }
+ )
+ return _llm_result(self.router_response)
+ return super()._invoke(
+ prompt_messages=prompt_messages,
+ model_parameters=model_parameters,
+ stream=stream,
+ )
+
+
+def _tool_entry(provider: str, tool: str, *, label: str = "", description: str = "") -> ToolCatalogueEntry:
+ return ToolCatalogueEntry(
+ provider_name=provider,
+ provider_type="builtin",
+ plugin_id="",
+ tool_name=tool,
+ tool_label=label,
+ description=description,
+ )
+
+
+class TestDynamicToolRouting:
+ def test_small_catalogue_is_injected_without_router_call(self):
+ model = MagicMock()
+ entries = [_tool_entry("provider", f"tool_{index:02d}") for index in range(24)]
+
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={"temperature": 0.8},
+ instruction="Do something",
+ ideal_output="",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=None,
+ )
+
+ assert len(text.splitlines()) == 24
+ model.invoke_llm.assert_not_called()
+
+ def test_large_catalogue_routes_chinese_instruction_to_relevant_english_tool(self):
+ model = MagicMock()
+ model.invoke_llm.return_value = _llm_result(
+ json.dumps(
+ {
+ "needs_tools": True,
+ "queries": [
+ {
+ "capability": "web search",
+ "keywords": ["internet", "current", "results"],
+ }
+ ],
+ }
+ )
+ )
+ entries = [
+ *[
+ _tool_entry(f"provider_{index}", "records", description="Manage stored records.")
+ for index in range(499)
+ ],
+ _tool_entry(
+ "langgenius/google/google",
+ "search",
+ label="Google Search",
+ description="Search the current web and return internet results.",
+ ),
+ ]
+
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={"temperature": 0.9, "max_tokens": 4096},
+ instruction="搜索今天的人工智能新闻",
+ ideal_output="包含来源链接",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=None,
+ )
+
+ assert "langgenius/google/google/search" in text
+ assert "provider_0/records" not in text
+ call_kwargs = model.invoke_llm.call_args.kwargs
+ assert call_kwargs["model_parameters"] == {"temperature": 0.1, "max_tokens": 256}
+ assert "搜索今天的人工智能新闻" in str(call_kwargs["prompt_messages"][1].content)
+
+ def test_router_needs_no_tools_but_keeps_existing_refine_tool(self):
+ model = MagicMock()
+ model.invoke_llm.return_value = _llm_result(json.dumps({"needs_tools": False, "queries": []}))
+ entries = [
+ *[_tool_entry(f"provider_{index}", "generic") for index in range(30)],
+ _tool_entry("langgenius/time/time", "current_time", label="Current Time"),
+ ]
+ current_graph = {
+ "nodes": [
+ {
+ "id": "time-node",
+ "data": {
+ "type": "tool",
+ "provider_id": "langgenius/time/time",
+ "tool_name": "current_time",
+ },
+ }
+ ]
+ }
+
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={},
+ instruction="Only rename the app",
+ ideal_output="",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=current_graph,
+ )
+
+ assert text.count("\n") == 0
+ assert "langgenius/time/time/current_time" in text
+
+ def test_invalid_router_response_falls_back_to_legacy_80_tool_prompt(self):
+ model = MagicMock()
+ model.invoke_llm.return_value = _llm_result("not a json object")
+ entries = [_tool_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={},
+ instruction="Use an external capability",
+ ideal_output="",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=None,
+ )
+
+ assert len(text.splitlines()) == 80
+ assert model.invoke_llm.call_count == 1
+
+ def test_router_json_parser_exception_falls_back_to_legacy_prompt(self):
+ model = MagicMock()
+ model.invoke_llm.return_value = _llm_result("invalid")
+ entries = [_tool_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ with patch("core.workflow.generator.runner.json_repair.loads", side_effect=ValueError("bad JSON")):
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={},
+ instruction="Use an external capability",
+ ideal_output="",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=None,
+ )
+
+ assert len(text.splitlines()) == 80
+ assert model.invoke_llm.call_count == 1
+
+ @pytest.mark.parametrize(
+ "router_payload",
+ [
+ {"needs_tools": "yes", "queries": []},
+ {"needs_tools": True, "queries": "not-an-array"},
+ {"needs_tools": True, "queries": [None]},
+ {"needs_tools": True, "queries": [{"capability": ["not", "a", "string"]}]},
+ ],
+ )
+ def test_invalid_router_query_schema_falls_back_to_legacy_prompt(self, router_payload: dict[str, Any]):
+ model = MagicMock()
+ model.invoke_llm.return_value = _llm_result(json.dumps(router_payload))
+ entries = [_tool_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={},
+ instruction="Use an external capability",
+ ideal_output="",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=None,
+ )
+
+ assert len(text.splitlines()) == 80
+ assert model.invoke_llm.call_count == 1
+
+ def test_router_exception_falls_back_without_blocking_generation(self):
+ model = MagicMock()
+ model.invoke_llm.side_effect = RuntimeError("router unavailable")
+ entries = [_tool_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={},
+ instruction="Use an external capability",
+ ideal_output="",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=None,
+ )
+
+ assert len(text.splitlines()) == 80
+ assert model.invoke_llm.call_count == 1
+
+ def test_unmatched_router_query_falls_back_to_legacy_prompt(self, caplog: pytest.LogCaptureFixture):
+ model = MagicMock()
+ model.invoke_llm.return_value = _llm_result(
+ json.dumps(
+ {
+ "needs_tools": True,
+ "queries": [{"capability": "quantum melody", "keywords": ["qubits", "music"]}],
+ }
+ )
+ )
+ entries = [_tool_entry("provider", f"tool_{index:03d}", description="Manage records.") for index in range(100)]
+
+ text = WorkflowGenerator._resolve_prompt_tool_catalogue(
+ model_instance=model,
+ model_parameters={},
+ instruction="Create something external",
+ ideal_output="",
+ tool_catalogue_text="",
+ tool_catalogue_entries=entries,
+ current_graph=None,
+ )
+
+ assert len(text.splitlines()) == 80
+ assert "reason=unmatched_query" in caplog.text
+ assert "candidates=80" in caplog.text
+
+ def test_router_failure_does_not_surface_as_model_error(self):
+ planner = json.dumps(
+ {
+ "title": "Summary",
+ "description": "Summarize text.",
+ "nodes": [
+ {"id": "node1", "label": "Start", "node_type": "start", "purpose": "Receive text."},
+ {"id": "node2", "label": "Summarize", "node_type": "llm", "purpose": "Summarize text."},
+ {"id": "node3", "label": "End", "node_type": "end", "purpose": "Return summary."},
+ ],
+ "edges": [
+ {"source": "node1", "target": "node2"},
+ {"source": "node2", "target": "node3"},
+ ],
+ }
+ )
+ graph = json.dumps(
+ {
+ "nodes": [
+ {"id": "node1", "data": {"type": "start", "title": "Start", "variables": []}},
+ {
+ "id": "node2",
+ "data": {
+ "type": "llm",
+ "title": "Summarize",
+ "model": {"provider": "openai", "name": "gpt-4o", "mode": "chat"},
+ "prompt_template": [],
+ },
+ },
+ {"id": "node3", "data": {"type": "end", "title": "End", "outputs": []}},
+ ],
+ "edges": [
+ {"id": "a", "source": "node1", "target": "node2", "type": "custom"},
+ {"id": "b", "source": "node2", "target": "node3", "type": "custom"},
+ ],
+ "viewport": {"x": 0, "y": 0, "zoom": 0.7},
+ }
+ )
+ model = _RoutingGraphFixtureModel(planner, graph, "not a json object")
+ entries = [_tool_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ result = WorkflowGenerator.generate_workflow_graph(
+ model_instance=model,
+ model_parameters={},
+ provider="openai",
+ model_name="gpt-4o",
+ model_mode="chat",
+ mode="workflow",
+ instruction="Summarize text",
+ tool_catalogue_entries=entries,
+ installed_tools={(entry["provider_name"], entry["tool_name"]) for entry in entries},
+ )
+
+ assert "MODEL_ERROR" not in [error["code"] for error in result["errors"]]
+ assert result["error"] == ""
+
+
class _ParallelBuilderModel:
"""Thread-safe fake that blocks the first ``barrier_parties`` node builders together."""
@@ -1503,6 +1801,192 @@ class TestWorkflowGeneratorEdgeCases:
joined = "\n".join(all_prompts)
assert joined.count("- google/search — Search.") == 2
+ def test_structured_tool_selection_hydrates_trusted_installed_metadata(self):
+ entry = cast(
+ ToolCatalogueEntry,
+ {
+ "provider_name": "langgenius/google/google",
+ "provider_type": "builtin",
+ "plugin_id": "langgenius/google",
+ "plugin_unique_identifier": "langgenius/google:1.0@checksum",
+ "tool_name": "search",
+ "tool_label": "Google Search",
+ "description": "Search the web.",
+ "parameters": [
+ {
+ "name": "query",
+ "type": "string",
+ "form": "llm",
+ "required": True,
+ "default": None,
+ "options": [],
+ },
+ {
+ "name": "safe_search",
+ "type": "select",
+ "form": "form",
+ "required": False,
+ "default": "moderate",
+ "options": [{"value": "moderate"}],
+ },
+ ],
+ "output_schema": {"type": "object", "properties": {"text": {"type": "string"}}},
+ },
+ )
+ plan_nodes = [
+ {
+ "id": "node2",
+ "node_type": "tool",
+ "purpose": "Search using langgenius/google/google/search.",
+ "tool": {"provider_id": "langgenius/google/google", "tool_name": "search"},
+ }
+ ]
+ graph = cast(
+ GraphDict,
+ {
+ "nodes": [
+ {
+ "id": "node2",
+ "type": "custom",
+ "position": {"x": 0, "y": 0},
+ "data": {
+ "type": "tool",
+ "provider_id": "hallucinated",
+ "provider_type": "plugin",
+ "tool_name": "fake",
+ "tool_parameters": {
+ "query": {"type": "mixed", "value": "{{#node1.query#}}"},
+ "invented": {"type": "constant", "value": "wrong"},
+ },
+ "tool_configurations": {
+ "safe_search": {"type": "constant", "value": "strict"},
+ "invented": {"type": "constant", "value": "wrong"},
+ },
+ "params": {"invented": ""},
+ },
+ }
+ ],
+ "edges": [],
+ "viewport": {"x": 0, "y": 0, "zoom": 0.7},
+ },
+ )
+
+ WorkflowGenerator._hydrate_tool_nodes(
+ graph=graph,
+ plan_nodes=plan_nodes,
+ tool_catalogue_entries=[entry],
+ )
+
+ data = graph["nodes"][0]["data"]
+ assert data["provider_id"] == "langgenius/google/google"
+ assert data["provider_type"] == "builtin"
+ assert data["plugin_id"] == "langgenius/google"
+ assert data["tool_name"] == "search"
+ assert data["tool_parameters"]["query"]["value"] == "{{#node1.query#}}"
+ assert "invented" not in data["tool_parameters"]
+ assert data["tool_configurations"] == {"safe_search": {"type": "constant", "value": "strict"}}
+ assert data["params"] == {"query": "", "safe_search": ""}
+ assert data["paramSchemas"][0]["name"] == "query"
+ assert data["output_schema"]["properties"]["text"]["type"] == "string"
+
+ def test_tool_selection_falls_back_to_exact_identifier_in_purpose(self):
+ entry = cast(
+ ToolCatalogueEntry,
+ {
+ "provider_name": "langgenius/google/google",
+ "provider_type": "builtin",
+ "plugin_id": "langgenius/google",
+ "tool_name": "search",
+ "tool_label": "Google Search",
+ "description": "Search the web.",
+ },
+ )
+
+ selected = _find_planned_tool_entry(
+ {
+ "purpose": "Search using langgenius/google/google/search.",
+ "tool": {"provider_id": "wrong/provider", "tool_name": "search"},
+ },
+ [entry],
+ )
+
+ assert selected == entry
+
+ def test_purpose_fallback_does_not_select_a_prefix_tool(self):
+ short_entry = _tool_entry("provider", "search")
+ exact_entry = _tool_entry("provider", "search-web")
+
+ selected = _find_planned_tool_entry(
+ {"purpose": "Search using provider/search-web."},
+ [short_entry, exact_entry],
+ )
+
+ assert selected == exact_entry
+
+ def test_tool_hydration_skips_unrelated_nodes_and_can_resolve_from_graph_data(self):
+ entry = cast(
+ ToolCatalogueEntry,
+ {
+ "provider_name": "time",
+ "provider_type": "builtin",
+ "plugin_id": "",
+ "tool_name": "current_time",
+ "tool_label": "Current Time",
+ "description": "Return the current time.",
+ "parameters": [],
+ },
+ )
+ plan_nodes = [
+ {"id": "no-data", "node_type": "tool", "purpose": "Broken data."},
+ {"id": "from-data", "node_type": "tool", "purpose": "Return the time."},
+ {"id": "not-installed", "node_type": "tool", "purpose": "Use missing/tool."},
+ ]
+ graph = cast(
+ GraphDict,
+ {
+ "nodes": [
+ {"id": "unplanned", "data": {"type": "tool"}},
+ {"id": "no-data", "data": "invalid"},
+ {
+ "id": "from-data",
+ "data": {
+ "type": "tool",
+ "provider_id": "time",
+ "tool_name": "current_time",
+ "plugin_id": "stale/plugin",
+ "plugin_unique_identifier": "stale/plugin:1.0@checksum",
+ "tool_parameters": ["invalid"],
+ "tool_configurations": None,
+ "params": {"stale": ""},
+ "output_schema": {"stale": True},
+ },
+ },
+ {
+ "id": "not-installed",
+ "data": {"type": "tool", "provider_id": "missing", "tool_name": "tool"},
+ },
+ ],
+ "edges": [],
+ "viewport": {"x": 0, "y": 0, "zoom": 0.7},
+ },
+ )
+
+ WorkflowGenerator._hydrate_tool_nodes(
+ graph=graph,
+ plan_nodes=plan_nodes,
+ tool_catalogue_entries=[entry],
+ )
+
+ hydrated = graph["nodes"][2]["data"]
+ assert hydrated["provider_id"] == "time"
+ assert "plugin_id" not in hydrated
+ assert "plugin_unique_identifier" not in hydrated
+ assert hydrated["tool_parameters"] == {}
+ assert hydrated["tool_configurations"] == {}
+ assert hydrated["params"] == {}
+ assert hydrated["output_schema"] == {}
+ assert graph["nodes"][3]["data"]["provider_id"] == "missing"
+
def test_postprocess_lays_out_nodes_left_to_right_regardless_of_input(self):
# The LLM often returns wildly overlapping positions. The postprocess
# step must override them with a clean horizontal layout so the
diff --git a/api/tests/unit_tests/core/workflow/generator/test_tool_catalogue.py b/api/tests/unit_tests/core/workflow/generator/test_tool_catalogue.py
index 026ea823f6f..7f54f314266 100644
--- a/api/tests/unit_tests/core/workflow/generator/test_tool_catalogue.py
+++ b/api/tests/unit_tests/core/workflow/generator/test_tool_catalogue.py
@@ -3,13 +3,22 @@
from types import SimpleNamespace
from unittest.mock import patch
+from core.tools.entities.common_entities import I18nObject
+from core.tools.entities.tool_entities import ToolDescription
from core.workflow.generator.tool_catalogue import (
+ MAX_ROUTED_TOOL_CANDIDATES,
+ MAX_ROUTED_TOOLS_PER_PROVIDER,
+ ToolCapabilityQuery,
ToolCatalogueEntry,
_i18n_text,
_tool_description,
build_tool_catalogue,
+ find_tool_entry,
+ format_tool_builder_context,
format_tool_catalogue,
installed_tool_keys,
+ select_legacy_fallback_tools,
+ select_tool_candidates,
)
@@ -67,8 +76,8 @@ class TestFormatToolCatalogue:
)
lines = out.split("\n")
assert lines == [
- "- google/search — Search the web with Google.",
- "- time/current_time — Return the current time.",
+ '- google/search [provider_id="google"; tool_name="search"] — Search the web with Google.',
+ '- time/current_time [provider_id="time"; tool_name="current_time"] — Return the current time.',
]
def test_includes_label_when_different_from_tool_name(self):
@@ -77,7 +86,7 @@ class TestFormatToolCatalogue:
_entry("google", "search", label="Google Search", description="Search."),
]
)
- assert out == "- google/search (Google Search) — Search."
+ assert out == '- google/search (Google Search) [provider_id="google"; tool_name="search"] — Search.'
def test_omits_label_when_identical_to_tool_name(self):
out = format_tool_catalogue(
@@ -85,7 +94,25 @@ class TestFormatToolCatalogue:
_entry("time", "current_time", label="current_time", description="Now."),
]
)
- assert out == "- time/current_time — Now."
+ assert out == '- time/current_time [provider_id="time"; tool_name="current_time"] — Now.'
+
+ def test_caps_only_prompt_text_while_full_inventory_remains_available(self):
+ entries = [_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ out = format_tool_catalogue(entries)
+
+ assert len(out.splitlines()) == 80
+ assert "tool_079" in out
+ assert "tool_080" not in out
+ assert ("provider", "tool_099") in installed_tool_keys(entries)
+
+ def test_can_disable_prompt_cap_for_an_already_selected_catalogue(self):
+ entries = [_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ out = format_tool_catalogue(entries, max_tools=None)
+
+ assert len(out.splitlines()) == 100
+ assert "tool_099" in out
def test_truncates_long_descriptions(self):
long_desc = "x" * 200
@@ -100,11 +127,195 @@ class TestFormatToolCatalogue:
assert "line1 line2 line3" in out
-# ── Helpers ──────────────────────────────────────────────────────────────────
+class TestSelectToolCandidates:
+ def test_routes_english_capability_query_to_relevant_tool_description(self):
+ entries = [
+ *[_entry(f"provider_{index}", "generic", description="Manage generic records.") for index in range(30)],
+ _entry(
+ "langgenius/google/google",
+ "search",
+ label="Google Search",
+ description="Search the current web and return internet results.",
+ ),
+ ]
+
+ selection = select_tool_candidates(
+ entries,
+ [ToolCapabilityQuery(capability="web search", keywords=["internet", "current", "results"])],
+ )
+
+ assert [(entry["provider_name"], entry["tool_name"]) for entry in selection.entries] == [
+ ("langgenius/google/google", "search")
+ ]
+ assert selection.unmatched_queries == []
+
+ def test_pins_explicit_identifier_and_existing_refine_tool_without_queries(self):
+ entries = [
+ _entry("langgenius/google/google", "search"),
+ _entry("langgenius/time/time", "current_time"),
+ _entry("other", "tool"),
+ ]
+ current_graph = {
+ "nodes": [
+ {
+ "id": "time-node",
+ "data": {
+ "type": "tool",
+ "provider_id": "langgenius/time/time",
+ "tool_name": "current_time",
+ },
+ }
+ ]
+ }
+
+ selection = select_tool_candidates(
+ entries,
+ [],
+ explicit_text="Use langgenius/google/google/search for this step.",
+ current_graph=current_graph,
+ )
+
+ assert [(entry["provider_name"], entry["tool_name"]) for entry in selection.entries] == [
+ ("langgenius/google/google", "search"),
+ ("langgenius/time/time", "current_time"),
+ ]
+ assert selection.pinned_count == 2
+
+ def test_explicit_identifier_does_not_also_pin_a_hyphenated_prefix(self):
+ entries = [
+ _entry("provider", "search"),
+ _entry("provider", "search-web"),
+ ]
+
+ selection = select_tool_candidates(
+ entries,
+ [],
+ explicit_text="Use provider/search-web exactly.",
+ )
+
+ assert selection.entries == [entries[1]]
+ assert selection.pinned_count == 1
+
+ def test_reports_unmatched_capability_for_legacy_fallback(self):
+ selection = select_tool_candidates(
+ [_entry("records", "list", description="List stored database records.")],
+ [ToolCapabilityQuery(capability="synthesize quantum music", keywords=["qubits", "melody"])],
+ )
+
+ assert selection.entries == []
+ assert selection.unmatched_queries == ["synthesize quantum music"]
+
+ def test_deduplicates_one_tool_selected_by_multiple_queries(self):
+ entries = [
+ _entry(
+ "langgenius/google/google",
+ "search",
+ label="Google Search",
+ description="Search the current web and return internet results.",
+ )
+ ]
+ queries = [
+ ToolCapabilityQuery(capability="web search", keywords=["internet"]),
+ ToolCapabilityQuery(capability="internet lookup", keywords=["web"]),
+ ]
+
+ selection = select_tool_candidates(entries, queries)
+
+ assert selection.entries == entries
+
+ def test_enforces_provider_diversity(self):
+ words = ["alpha", "bravo", "charlie", "delta", "echo"]
+ entries = [
+ _entry("large_provider", f"{word}_action", description=f"Perform the {word} capability.") for word in words
+ ]
+ queries = [ToolCapabilityQuery(capability=word, keywords=[word]) for word in words]
+
+ selection = select_tool_candidates(entries, queries)
+
+ assert sum(entry["provider_name"] == "large_provider" for entry in selection.entries) == (
+ MAX_ROUTED_TOOLS_PER_PROVIDER
+ )
+ assert selection.entries == select_tool_candidates(entries, queries).entries
+
+ def test_500_tool_catalogue_never_exceeds_global_candidate_limit(self):
+ words = ["alpha", "bravo", "charlie", "delta", "echo"]
+ entries = [
+ _entry(
+ f"provider_{index:03d}",
+ f"tool_{index:03d}",
+ description=f"Handle {words[index % len(words)]} operations.",
+ )
+ for index in range(500)
+ ]
+ queries = [ToolCapabilityQuery(capability=word, keywords=[word]) for word in words]
+
+ selection = select_tool_candidates(entries, queries)
+ assert len(selection.entries) == 15
+ assert len(selection.entries) <= MAX_ROUTED_TOOL_CANDIDATES
-class _FakeI18n(SimpleNamespace):
- """Minimal stand-in for ``I18nObject`` — only the attrs we read."""
+ def test_legacy_fallback_keeps_explicit_tool_beyond_first_80(self):
+ entries = [_entry("provider", f"tool_{index:03d}") for index in range(100)]
+
+ selected = select_legacy_fallback_tools(
+ entries,
+ explicit_text="Use provider/tool_099 exactly.",
+ )
+
+ assert len(selected) == 80
+ assert selected[0]["tool_name"] == "tool_099"
+ assert any(entry["tool_name"] == "tool_078" for entry in selected)
+ assert all(entry["tool_name"] != "tool_079" for entry in selected)
+
+
+class TestToolBuilderContext:
+ def test_finds_exact_provider_and_tool_pair(self):
+ entries = [_entry("google", "search"), _entry("google", "maps")]
+
+ assert find_tool_entry(entries, "google", "search") == entries[0]
+ assert find_tool_entry(entries, "google", "missing") is None
+
+ def test_renders_trusted_identity_and_parameter_contract(self):
+ entry = _entry("langgenius/google/google", "search", label="Google Search", description="Search the web.")
+ entry["plugin_id"] = "langgenius/google"
+ entry["plugin_unique_identifier"] = "langgenius/google:1.0@checksum"
+ entry["parameters"] = [
+ {
+ "name": "",
+ "type": "string",
+ "form": "llm",
+ "required": False,
+ },
+ {
+ "name": "query",
+ "type": "string",
+ "form": "llm",
+ "required": True,
+ "default": None,
+ "options": [],
+ "llm_description": "The search query.",
+ },
+ {
+ "name": "safe_search",
+ "type": "select",
+ "form": "form",
+ "required": False,
+ "default": "moderate",
+ "options": [{"value": "moderate"}, {"value": "off"}],
+ },
+ ]
+
+ out = format_tool_builder_context(entry)
+
+ assert "Selected installed tool" in out
+ assert '"provider_type":"builtin"' in out
+ assert '"plugin_id":"langgenius/google"' in out
+ assert "query: string, form=llm, required" in out
+ assert 'safe_search: select, form=form, optional — options=["moderate","off"]; default="moderate"' in out
+ assert "- : string" not in out
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
class _FakeToolEntity(SimpleNamespace):
@@ -115,10 +326,6 @@ class _FakeToolIdentity(SimpleNamespace):
"""Identity holding ``name`` + ``label`` like ``ToolIdentity``."""
-class _FakeToolDescription(SimpleNamespace):
- """Description with the ``llm`` attribute we read for prompts."""
-
-
class _FakeTool:
"""Tool stand-in: ``.entity`` is the only attribute the catalogue reads."""
@@ -131,9 +338,11 @@ def _make_tool(name: str, label_en: str = "", description_llm: str = "") -> _Fak
entity=_FakeToolEntity(
identity=_FakeToolIdentity(
name=name,
- label=_FakeI18n(en_US=label_en, zh_Hans=""),
+ label=I18nObject(en_US=label_en),
),
- description=_FakeToolDescription(llm=description_llm),
+ description=ToolDescription(human=I18nObject(en_US=""), llm=description_llm),
+ parameters=[],
+ output_schema={},
)
)
@@ -157,11 +366,12 @@ def _make_builtin_provider(name: str, tools: list, raises_on_get_tools: bool = F
return provider
-def _make_plugin_provider(name: str, plugin_id: str, tools: list):
+def _make_plugin_provider(name: str, plugin_id: str | None, tools: list):
provider = SimpleNamespace(
entity=SimpleNamespace(identity=SimpleNamespace(name=name)),
provider_type=_FakeProviderType(value="plugin"),
plugin_id=plugin_id,
+ plugin_unique_identifier=f"{plugin_id}:1.0@checksum" if plugin_id else "",
get_tools=lambda: tools,
)
provider._is_plugin = True
@@ -210,15 +420,15 @@ class TestI18nText:
assert _i18n_text(None) == ""
def test_returns_en_us_when_present(self):
- assert _i18n_text(_FakeI18n(en_US="Search", zh_Hans="搜索")) == "Search"
+ assert _i18n_text(I18nObject(en_US="Search", zh_Hans="搜索")) == "Search"
def test_falls_back_to_zh_hans_when_en_us_blank(self):
# Some plugins ship only Chinese metadata; falling back keeps the
# planner aware of those tools instead of dropping them silently.
- assert _i18n_text(_FakeI18n(en_US="", zh_Hans="搜索")) == "搜索"
+ assert _i18n_text(I18nObject(en_US="", zh_Hans="搜索")) == "搜索"
- def test_returns_empty_when_both_locales_missing(self):
- assert _i18n_text(_FakeI18n()) == ""
+ def test_returns_empty_when_both_locales_are_blank(self):
+ assert _i18n_text(I18nObject(en_US="", zh_Hans="")) == ""
class TestToolDescription:
@@ -227,10 +437,14 @@ class TestToolDescription:
assert _tool_description(None) == ""
def test_returns_llm_attribute(self):
- assert _tool_description(_FakeToolDescription(llm="Web search")) == "Web search"
+ description = ToolDescription(human=I18nObject(en_US=""), llm="Web search")
+
+ assert _tool_description(description) == "Web search"
+
+ def test_returns_empty_when_llm_is_blank(self):
+ description = ToolDescription(human=I18nObject(en_US=""), llm="")
- def test_returns_empty_when_llm_missing(self):
- assert _tool_description(SimpleNamespace()) == ""
+ assert _tool_description(description) == ""
# ── build_tool_catalogue ─────────────────────────────────────────────────────
@@ -277,8 +491,11 @@ class TestBuildToolCatalogue:
("time", "current_time"),
]
google = entries[0]
- assert google["provider_type"] == "plugin"
+ # Plugin-backed tools still use provider_type="builtin" in workflow
+ # nodes; plugin identity lives in plugin_id / unique identifier.
+ assert google["provider_type"] == "builtin"
assert google["plugin_id"] == "langgenius/google"
+ assert google["plugin_unique_identifier"] == "langgenius/google:1.0@checksum"
assert google["tool_label"] == "Google Search"
assert google["description"] == "Search the web."
time_entry = entries[1]
@@ -330,9 +547,10 @@ class TestBuildToolCatalogue:
@patch("core.workflow.generator.tool_catalogue.isinstance", side_effect=_patched_isinstance)
@patch("core.workflow.generator.tool_catalogue.ToolManager.list_builtin_providers")
- def test_truncates_to_max_tools_to_keep_prompt_bounded(self, mock_list, mock_isinstance):
- # A tenant with hundreds of plugin tools would blow the LLM context
- # window. The catalogue caps the output at ``_MAX_TOOLS``.
+ def test_keeps_complete_inventory_for_validation_beyond_prompt_cap(self, mock_list, mock_isinstance):
+ # Prompt formatting is capped separately. Dropping entries here would
+ # make the validator falsely report installed tools after the cap as
+ # missing from the workspace.
big_provider = _make_builtin_provider(
"p",
[_make_tool(f"t{i:03d}") for i in range(200)],
@@ -341,7 +559,8 @@ class TestBuildToolCatalogue:
entries = build_tool_catalogue("tenant-1")
- assert len(entries) == 80
+ assert len(entries) == 200
+ assert ("p", "t199") in installed_tool_keys(entries)
@patch("core.workflow.generator.tool_catalogue.isinstance", side_effect=_patched_isinstance)
@patch("core.workflow.generator.tool_catalogue.ToolManager.list_builtin_providers")
diff --git a/api/tests/unit_tests/services/test_workflow_generator_service.py b/api/tests/unit_tests/services/test_workflow_generator_service.py
index 24c46eac5df..48b5d9c5523 100644
--- a/api/tests/unit_tests/services/test_workflow_generator_service.py
+++ b/api/tests/unit_tests/services/test_workflow_generator_service.py
@@ -27,20 +27,26 @@ class TestWorkflowGeneratorService:
@patch("services.workflow_generator_service.WorkflowGenerator")
@patch("services.workflow_generator_service.ModelManager")
@patch("services.workflow_generator_service.build_tool_catalogue")
- @patch("services.workflow_generator_service.format_tool_catalogue")
- def test_forwards_model_instance_and_catalogue_text_to_generator(
+ def test_forwards_model_instance_and_complete_catalogue_to_generator(
self,
- mock_format_catalogue: MagicMock,
mock_build_catalogue: MagicMock,
mock_model_manager: MagicMock,
mock_workflow_generator: MagicMock,
):
- """Happy path: model_instance + catalogue text + payload flow through."""
+ """Happy path: the runner receives the complete catalogue for dynamic routing."""
# Arrange
instance = MagicMock(name="model_instance")
mock_model_manager.for_tenant.return_value.get_model_instance.return_value = instance
- mock_build_catalogue.return_value = [{"provider_name": "google"}]
- mock_format_catalogue.return_value = "- google/search — Search."
+ mock_build_catalogue.return_value = [
+ {
+ "provider_name": "google",
+ "provider_type": "builtin",
+ "plugin_id": "",
+ "tool_name": "search",
+ "tool_label": "Search",
+ "description": "Search.",
+ }
+ ]
mock_workflow_generator.generate_workflow_graph.return_value = {
"graph": {"nodes": [], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 0.7}},
"message": "ok",
@@ -66,7 +72,8 @@ class TestWorkflowGeneratorService:
assert call_kwargs["mode"] == "workflow"
assert call_kwargs["instruction"] == "Summarize a URL"
assert call_kwargs["ideal_output"] == "A 3-sentence summary"
- assert call_kwargs["tool_catalogue_text"] == "- google/search — Search."
+ assert call_kwargs["tool_catalogue_text"] == ""
+ assert call_kwargs["tool_catalogue_entries"] == mock_build_catalogue.return_value
assert call_kwargs["model_parameters"] == {"temperature": 0.4}
assert result["error"] == ""
@@ -107,10 +114,8 @@ class TestWorkflowGeneratorService:
@patch("services.workflow_generator_service.WorkflowGenerator")
@patch("services.workflow_generator_service.ModelManager")
@patch("services.workflow_generator_service.build_tool_catalogue")
- @patch("services.workflow_generator_service.format_tool_catalogue")
def test_defaults_ideal_output_to_empty_string(
self,
- mock_format_catalogue: MagicMock,
mock_build_catalogue: MagicMock,
mock_model_manager: MagicMock,
mock_workflow_generator: MagicMock,
@@ -118,7 +123,6 @@ class TestWorkflowGeneratorService:
"""Callers can omit ideal_output; the runner should still receive ""."""
mock_model_manager.for_tenant.return_value.get_model_instance.return_value = MagicMock()
mock_build_catalogue.return_value = []
- mock_format_catalogue.return_value = ""
mock_workflow_generator.generate_workflow_graph.return_value = {
"graph": {"nodes": [], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 0.7}},
"message": "",
@@ -139,10 +143,8 @@ class TestWorkflowGeneratorService:
@patch("services.workflow_generator_service.WorkflowGenerator")
@patch("services.workflow_generator_service.ModelManager")
@patch("services.workflow_generator_service.build_tool_catalogue")
- @patch("services.workflow_generator_service.format_tool_catalogue")
def test_forwards_current_graph_for_refine(
self,
- mock_format_catalogue: MagicMock,
mock_build_catalogue: MagicMock,
mock_model_manager: MagicMock,
mock_workflow_generator: MagicMock,
@@ -150,7 +152,6 @@ class TestWorkflowGeneratorService:
"""The cmd+k `/refine` path passes the existing draft graph through to the runner."""
mock_model_manager.for_tenant.return_value.get_model_instance.return_value = MagicMock()
mock_build_catalogue.return_value = []
- mock_format_catalogue.return_value = ""
mock_workflow_generator.generate_workflow_graph.return_value = {
"graph": {"nodes": [], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 0.7}},
"message": "",
@@ -172,10 +173,8 @@ class TestWorkflowGeneratorService:
@patch("services.workflow_generator_service.WorkflowGenerator")
@patch("services.workflow_generator_service.ModelManager")
@patch("services.workflow_generator_service.build_tool_catalogue")
- @patch("services.workflow_generator_service.format_tool_catalogue")
def test_defaults_current_graph_to_none_for_create(
self,
- mock_format_catalogue: MagicMock,
mock_build_catalogue: MagicMock,
mock_model_manager: MagicMock,
mock_workflow_generator: MagicMock,
@@ -183,7 +182,6 @@ class TestWorkflowGeneratorService:
"""Omitting current_graph (the `/create` path) forwards None to the runner."""
mock_model_manager.for_tenant.return_value.get_model_instance.return_value = MagicMock()
mock_build_catalogue.return_value = []
- mock_format_catalogue.return_value = ""
mock_workflow_generator.generate_workflow_graph.return_value = {
"graph": {"nodes": [], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 0.7}},
"message": "",
@@ -203,10 +201,8 @@ class TestWorkflowGeneratorService:
@patch("services.workflow_generator_service.WorkflowGenerator")
@patch("services.workflow_generator_service.ModelManager")
@patch("services.workflow_generator_service.build_tool_catalogue")
- @patch("services.workflow_generator_service.format_tool_catalogue")
def test_auto_mode_forwards_sentinel_to_runner(
self,
- mock_format_catalogue: MagicMock,
mock_build_catalogue: MagicMock,
mock_model_manager: MagicMock,
mock_workflow_generator: MagicMock,
@@ -214,7 +210,6 @@ class TestWorkflowGeneratorService:
"""``mode="auto"`` passes straight through — the planner resolves it, no extra LLM call."""
mock_model_manager.for_tenant.return_value.get_model_instance.return_value = MagicMock()
mock_build_catalogue.return_value = []
- mock_format_catalogue.return_value = ""
mock_workflow_generator.generate_workflow_graph.return_value = {
"graph": {"nodes": [], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 0.7}},
"message": "",
@@ -235,10 +230,8 @@ class TestWorkflowGeneratorService:
@patch("services.workflow_generator_service.WorkflowGenerator")
@patch("services.workflow_generator_service.ModelManager")
@patch("services.workflow_generator_service.build_tool_catalogue")
- @patch("services.workflow_generator_service.format_tool_catalogue")
def test_explicit_mode_passes_through_unchanged(
self,
- mock_format_catalogue: MagicMock,
mock_build_catalogue: MagicMock,
mock_model_manager: MagicMock,
mock_workflow_generator: MagicMock,
@@ -246,7 +239,6 @@ class TestWorkflowGeneratorService:
"""A concrete mode reaches the runner verbatim."""
mock_model_manager.for_tenant.return_value.get_model_instance.return_value = MagicMock()
mock_build_catalogue.return_value = []
- mock_format_catalogue.return_value = ""
mock_workflow_generator.generate_workflow_graph.return_value = {
"graph": {"nodes": [], "edges": [], "viewport": {"x": 0, "y": 0, "zoom": 0.7}},
"message": "",
@@ -265,10 +257,8 @@ class TestWorkflowGeneratorService:
@patch("services.workflow_generator_service.WorkflowGenerator")
@patch("services.workflow_generator_service.ModelManager")
@patch("services.workflow_generator_service.build_tool_catalogue")
- @patch("services.workflow_generator_service.format_tool_catalogue")
def test_stream_delegates_to_runner_stream(
self,
- mock_format_catalogue: MagicMock,
mock_build_catalogue: MagicMock,
mock_model_manager: MagicMock,
mock_workflow_generator: MagicMock,
@@ -277,7 +267,6 @@ class TestWorkflowGeneratorService:
instance = MagicMock(name="model_instance")
mock_model_manager.for_tenant.return_value.get_model_instance.return_value = instance
mock_build_catalogue.return_value = []
- mock_format_catalogue.return_value = ""
def _runner_stream(**_kwargs):
yield ("plan", {"mode": "workflow"})