feat(datafabric): inject ontology schema into inner SQL agent system prompt by sankalp-uipath · Pull Request #911 · UiPath/uipath-langchain-python

sankalp-uipath · 2026-06-16T12:50:47Z

What

Grounds the Data Fabric inner SQL agent with the configured ontology by fetching it deterministically and embedding it in the inner system prompt — there is no LLM-decided tool. When a context has a nested ontologySet, the ontology's OWL schema is fetched once (at sub-graph build) and injected, so the model always writes SQL against the real schema.

ontology_fetcher.py — fetch_ontology_text(entities_service, ontologies): fetches each configured ontology's OWL via EntitiesService.get_ontology_file_async, concatenated; individual failures degrade gracefully to "use the entity schemas" rather than raising.
datafabric_tool.py — the handler's _ensure_datafabric_graph eagerly fetches the ontology text (once, cached with the compiled graph) when ontologies are configured and the flag is on, and passes it into the graph.
datafabric_prompt_builder.py — the ## Available Ontology section embeds the OWL as the authoritative schema the LLM grounds on.
datafabric_subgraph.py — the inner agent has a single tool, execute_sql; the ontology arrives via the prompt, not a tool.
context_tool.py — resolves ontologies from the nested ontologySet (flag-gated at the entry).

Why

Deterministic injection guarantees the model always has the ontology in context. An optional fetch_ontology tool (the earlier approach) is frequently not called by the model, so grounding silently doesn't happen. Injecting it directly removes that failure mode — and it keeps the inner graph a plain single-tool SQL loop.

Notes

Feature-flagged (DataFabricOntologyEnabled, default off) at every entry — ontology resolution (context_tool) and the eager fetch (datafabric_tool) are each gated on the same shared constant. Off ⇒ no fetch, byte-for-byte the original entities-only prompt.
Ontology names/folders are pinned from the agent definition, never supplied by the LLM.
Graceful degrade: a missing/oversized ontology never fails the run.
Resolution uses name + folderId only; aligned with SDK #1728 dropping the unused ontology referenceKey.
Depends on SDK #1728 (uipath 2.11.17 / uipath-platform 0.1.83, nested ontologySet model). Unit/lint CI stays red until #1728 merges and publishes; then uv lock (range uipath<2.12.0) turns them green. Do not merge a .dev pin.
Runtime delivery of the flag also requires it in uipath-agents-python's _ALL_FLAGS prefetch list + the gitops flag (gitops-centralized-cluster PR) deployed for the target tenants.
Follow-up PR adds R2RML fetching on top of this (branch feat/datafabric-ontology-r2rml-grounding).

Copilot

Pull request overview

Adds an optional fetch_ontology inner tool to the Data Fabric SQL sub-agent so the inner LLM can retrieve a configured ontology’s OWL schema from the QueryEngine REST API and use it to generate semantically-correct SQL.

Changes:

Introduces an ontology REST client (fetch_ontology_owl) with name validation and size limiting.
Adds a fetch_ontology leaf tool with an instance-level cache and wires it into the inner Data Fabric subgraph alongside execute_sql.
Threads ontology_name / folder_key into the Data Fabric tool construction path (with an env-var fallback).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`src/uipath_langchain/agent/tools/datafabric_tool/ontology_fetch_tool.py`	New leaf tool (`fetch_ontology`) and cached fetcher wrapper for inner SQL agent use.
`src/uipath_langchain/agent/tools/datafabric_tool/ontology_client.py`	New client helper to fetch OWL content via `EntitiesService.request_async`, including name validation and payload cap.
`src/uipath_langchain/agent/tools/datafabric_tool/models.py`	Adds an intentionally-empty args schema (`OntologyFetchInput`) for the new tool.
`src/uipath_langchain/agent/tools/datafabric_tool/datafabric_tool.py`	Plumbs `ontology_name` / `folder_key` into the query handler creation (currently with env-var fallback).
`src/uipath_langchain/agent/tools/datafabric_tool/datafabric_subgraph.py`	Adds optional `fetch_ontology` tool binding and dispatch-by-tool-name inside the inner subgraph.

+    The result is cached on this instance. Because the instance lives as long
+    as the compiled sub-graph (which the handler caches), repeated calls across
+    queries hit the API at most once, surviving the per-query reset of the
+    inner sub-graph state.


…lder)

milind-jain-uipath · 2026-06-17T09:26:52Z

+    safe_name = _validate_ontology_name(ontology_name)
+    # Same datafabric_ service the entities calls target; matches the
+    # QueryEngine ontology route GET /ontologies/{ontologyName}/files/{fileType}.
+    endpoint = f"datafabric_/api/ontologies/{safe_name}/files/owl"


these need to be stitched in uipath-python

…logy_file (drop local client)

…ogy-fetch-tool

…y fallback

…ctory mapping

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

UIPath-Harshit · 2026-06-26T06:20:18Z

@@ -131,35 +143,62 @@
            *[self._execute_tool_call(tc) for tc in last.tool_calls]
        )
        tool_messages = [msg for msg, _ in results]
-        all_succeeded = bool(results) and all(success for _, success in results)
+        # End as soon as ANY tool call is a terminal success (a row-returning
+        # execute_sql). `any` not `all`: a non-terminal tool (e.g. fetch_ontology)
+        # co-issued in the same turn must not prevent a successful SQL from ending
+        # the loop.
+        any_succeeded = any(success for _, success in results)


Instead of any_ check for FF to see what graph gets constructed.

            ToolMessage(
                content=str(result),
                tool_call_id=tool_call["id"],
-                name="execute_sql",
+                name=name,
            ),


+    # Ontologies are first-class bindings, mirroring entity_set: a LIST, each
+    # carrying its own folderId so it is resolved from its own folder (entities
+    # may also span several folders). Empty → no fetch tool added. Config comes
+    # only from the agent definition (the binding), never from process env.
+    entity_folders = {


+    out = await graph.tool_node(DataFabricSubgraphState(messages=[ai]))
+    # SQL returned rows → terminal, even though fetch_ontology (non-terminal)
+    # was co-issued in the same turn. This is the all()->any() fix.
+    assert out["last_tool_success"] is True
+    assert len(out["messages"]) == 2
+


…age.status to match host node

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

+import logging
+from typing import Any
+


+            return self._cached
+        if not self._ontologies:
+            return "No ontologies are configured for this agent."
+        blocks = [await self._fetch_one(name, folder) for name, folder in self._ontologies]


+            tool_messages = [msg for msg, _ in results]
        return {
            "messages": tool_messages,
            "iteration_count": state.iteration_count + len(last.tool_calls),


…ather)

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

+        # End as soon as ANY tool call is a terminal success (a row-returning
+        # execute_sql). `any` not `all`: a non-terminal tool (e.g. fetch_ontology)
+        # co-issued in the same turn must not prevent a successful SQL from ending
+        # the loop.
+        any_succeeded = any(success for _, success in results)
+        # When short-circuiting to END, return ONLY the terminal-success
+        # ToolMessages so the outer agent's result is the query rows — not a
+        # co-issued fetch_ontology's OWL. On a non-terminal turn keep all messages
+        # so the inner LLM can use them on its next pass.
+        if any_succeeded:
+            tool_messages = [msg for msg, success in results if success]
+        else:
+            tool_messages = [msg for msg, _ in results]


andreitava-uip · 2026-06-30T09:16:27Z

+        self._entities_service = entities_service
+        self._ontologies = ontologies
+        self._cached: str | None = None


outer agent does not support true parallel invocation. Parallel tool calls are executed sequentially by the outer agent, so each SQL agent instance won't be concurrently called.

+    async def __call__(self, **_kwargs: Any) -> str:
+        """Fetch all configured ontologies (cached), concatenated for the LLM."""
+        if self._cached is not None:
+            return self._cached
+        if not self._ontologies:
+            return "No ontologies are configured for this agent."
+        # Fetch all ontologies concurrently — each fetch is independent; order is
+        # preserved by gather, so the concatenation is deterministic.
+        blocks = await asyncio.gather(
+            *(self._fetch_one(name, folder) for name, folder in self._ontologies)
+        )
+        self._cached = "\n\n".join(blocks)
+        return self._cached


+    tool = create_datafabric_query_tool(resource, MagicMock())  # type: ignore[arg-type]
+
+    assert tool.coroutine._ontologies == [("library", "f1")]


+    tool = create_datafabric_query_tool(resource, MagicMock())  # type: ignore[arg-type]
+
+    assert tool.coroutine._ontologies == [("finance", "f2")]


+    tool = create_datafabric_query_tool(resource, MagicMock())  # type: ignore[arg-type]
+
+    assert tool.coroutine._ontologies == []


Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

        return {
            "messages": tool_messages,
            "iteration_count": state.iteration_count + len(last.tool_calls),
-            "last_tool_success": all_succeeded,
+            "last_tool_success": any_succeeded,
        }


+    async def __call__(self, **_kwargs: Any) -> str:
+        """Fetch all configured ontologies (cached), concatenated for the LLM."""
+        if self._cached is not None:
+            return self._cached
+        if not self._ontologies:
+            return "No ontologies are configured for this agent."
+        # Fetch all ontologies concurrently — each fetch is independent; order is
+        # preserved by gather, so the concatenation is deterministic.
+        blocks = await asyncio.gather(
+            *(self._fetch_one(name, folder) for name, folder in self._ontologies)
+        )
+        self._cached = "\n\n".join(blocks)
+        return self._cached


UIPath-Harshit · 2026-06-26T06:14:22Z

+        # Inner toolset: always execute_sql; optionally an LLM-decided
+        # fetch_ontology tool when one or more ontologies are configured.
+        inner_tools: list[BaseTool] = [self._execute_sql_tool]
+        if ontologies:


EnabledNewLlmClients <- check for the feature flag impl of this to ensure out feature is behind the feature flag.

yes, will add it.

UIPath-Harshit · 2026-06-26T06:16:50Z

+        # fetch_ontology tool when one or more ontologies are configured.
+        inner_tools: list[BaseTool] = [self._execute_sql_tool]
+        if ontologies:
+            inner_tools.append(


This doesnt update the subgraph ? correct?

UIPath-Harshit · 2026-06-26T06:20:18Z

@@ -131,35 +143,62 @@ async def tool_node(self, state: DataFabricSubgraphState) -> dict[str, Any]:
            *[self._execute_tool_call(tc) for tc in last.tool_calls]
        )
        tool_messages = [msg for msg, _ in results]
-        all_succeeded = bool(results) and all(success for _, success in results)
+        # End as soon as ANY tool call is a terminal success (a row-returning
+        # execute_sql). `any` not `all`: a non-terminal tool (e.g. fetch_ontology)
+        # co-issued in the same turn must not prevent a successful SQL from ending
+        # the loop.
+        any_succeeded = any(success for _, success in results)


Instead of any_ check for FF to see what graph gets constructed.

UIPath-Harshit · 2026-06-26T06:20:38Z

+    entity set) as ``ontologySet`` items. Each carries its own ``folderId``, so
+    it is fetched from its own folder.
+    """
+    items = getattr(resource, "ontology_set", None) or []


Same as other PR. ontology_set?

…d flag

andreitava-uip · 2026-06-30T08:53:33Z

+def test_fetch_ontology_bound_only_when_ontologies(make_graph):
+    without = make_graph(None)
+    assert "execute_sql" in without._tools_by_name
+    assert "fetch_ontology" not in without._tools_by_name
+
+    with_onto = make_graph([("library", None)])
+    assert "fetch_ontology" in with_onto._tools_by_name


nit: splitting this test into two(should bind when present/should not bind when absent) is trivial and allows instantly knowing what failed from the test name alone without checking the assertion message.

andreitava-uip · 2026-06-30T09:16:27Z

+        self._entities_service = entities_service
+        self._ontologies = ontologies
+        self._cached: str | None = None


outer agent does not support true parallel invocation. Parallel tool calls are executed sequentially by the outer agent, so each SQL agent instance won't be concurrently called.

andreitava-uip · 2026-06-30T09:28:35Z

+    # An ontology context is not a standalone tool — it only grounds the Data
+    # Fabric entity tool, which gathers it via resolve_context_ontologies.
+    if resource.context_type == AgentContextType.DATA_FABRIC_ONTOLOGY:
+        return None


If it is not a standalone tool at runtime, I think it is confusing to model it as a top level resource at design time. So far, all "resource nodes" in a lowcode agent (either standalone or part of flow), are independently executable and show up in traces. This is now a different paradigm, it is an optional helper tool that will be part of another tool's subgraph.

That being said this only applies to how it's modeled today. If we indeed plan to expand ontology support in the future such that they will actually allow queries (via something like SPARQL statements for instance); then it will be better for future proofing to define them top level (at least in the package mapping). We can figure out a less confusing design time experience for now

Yes, we have plan to expand ontology support to make it a primary design experience i.e, user will select the ontologies and then it will resolve the entities internally, thus decision of making it top level resource as a part of iterative development.

andreitava-uip · 2026-06-30T09:35:10Z

+        lines.append("## Available Ontology (authoritative semantic schema)")
+        lines.append("")
+        lines.append(
+            f"This agent has a semantic ontology attached for these entities: "
+            f"{names}. It is the authoritative source for the exact column names, "
+            "value formats (date formats, codes, zero-padding), allowed values, "
+            "and the relationships between entities — richer and more reliable "
+            "than the field list below, which omits value formats and semantics."
+        )
+        lines.append("")
+        lines.append(
+            "**Before writing any SQL, call the `fetch_ontology` tool once** to "
+            "load it, then base your column names, filter values, and joins on "
+            "what it says. The entity tables below are a quick reference only; "
+            "the ontology is the source of truth when they disagree."
+        )
+        lines.append("")
+


nit: could be cleaner to have this as a single formatted string depending on names instead of individually applying each line like this.

Applicable to the existing sql_expert_system_prompt as well, but that one wasn't introduced by this PR

Fixed, please review. Also there are some changes linked to your other comment in the data fabric prompt builder (adding ontology text in the prompt).

andreitava-uip · 2026-06-30T10:34:09Z

+        # When short-circuiting to END, return ONLY the terminal-success
+        # ToolMessages so the outer agent's result is the query rows — not a
+        # co-issued fetch_ontology's OWL. On a non-terminal turn keep all messages
+        # so the inner LLM can use them on its next pass.


isn't concurrent execution of a ontology retrieval + data service query an anomaly? It doesn't seem to be correct. Why not mechanically enforce ontology retrieval and injecting it in the context. When is it useful for the llm to choose not to fetch the ontology?

Agreed, earlier we were doing so as to support future use cases where llm will query the ontology (for ex using SPARQL), instead of giving the complete ontology to agent.
But I agree with you right now it makes more sense to mechanically injecting it in the system prompt.
I have made the changes please review again.

…onstant

…ogy-fetch-tool

andreitava-uip · 2026-06-30T11:06:16Z

+    ontologies: list[tuple[str, str | None]] = []
+    for resource in resources:
+        if (
+            isinstance(resource, AgentContextResourceConfig)
+            and resource.is_datafabric_ontology
+        ):
+            for item in resource.ontology_set or []:
+                ontologies.append((item.name, item.folder_key))
+    return ontologies


if I understand correctly, we implicitly assume all topologies will apply to this data service entity context. Shouldn't the link be more explicitly defined? IE either:
a) when defining an Data Service Context resource you can also specify one or more ontologies
b) when defining the Ontology Context resource you specify the list of entities it describes

I am currently working on adding the R2RML mapping which will resolve the entities from ontologies at the agent runtime by the llm node implicitly (I am working on it in separate PR and is currently in progress ).

…ring ontology prompt)

…ontology tool

sonarqubecloud · 2026-07-01T10:08:56Z

Quality Gate failed

Failed conditions
72.7% Coverage on New Code (required ≥ 90%)

See analysis details on SonarQube Cloud

feat(datafabric): add fetch_ontology tool to DF inner SQL agent

c6e73eb

Copilot AI review requested due to automatic review settings June 16, 2026 12:50

Merge branch 'main' into feat/datafabric-ontology-fetch-tool

b67e170

Copilot started reviewing on behalf of sankalp-uipath June 16, 2026 12:51 View session

Copilot AI reviewed Jun 16, 2026

View reviewed changes

feat(datafabric): resolve ontology from agent.json binding (name + fo…

da19087

…lder)

milind-jain-uipath reviewed Jun 17, 2026

View reviewed changes

milind-jain-uipath requested changes Jun 17, 2026

View reviewed changes

sankalp-uipath added 5 commits June 17, 2026 15:23

refactor(datafabric): fetch ontology via SDK EntitiesService.get_onto…

4c22b8f

…logy_file (drop local client)

feat(datafabric): support multiple ontologies per context (ontologySet)

68f7cbf

Merge remote-tracking branch 'origin/main' into feat/datafabric-ontol…

ab77d65

…ogy-fetch-tool

fix(datafabric): end loop on any successful SQL; drop env-var ontolog…

40acdec

…y fallback

test(datafabric): cover ontology fetch tool, subgraph routing, and fa…

7a5bb69

…ctory mapping

sankalp-uipath requested a review from Copilot June 22, 2026 07:26

Copilot started reviewing on behalf of sankalp-uipath June 22, 2026 07:26 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

fix(datafabric): return only terminal tool msgs on END; drop ToolMess…

04f79c5

…age.status to match host node

sankalp-uipath requested a review from Copilot June 22, 2026 08:05

Copilot started reviewing on behalf of sankalp-uipath June 22, 2026 08:06 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

perf(datafabric): fetch configured ontologies concurrently (asyncio.g…

0ed6210

…ather)

sankalp-uipath requested a review from Copilot June 22, 2026 19:58

Copilot started reviewing on behalf of sankalp-uipath June 22, 2026 19:59 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

sankalp-uipath requested a review from milind-jain-uipath June 23, 2026 07:39

sankalp-uipath and others added 5 commits June 23, 2026 18:19

feat(datafabric): resolve ontologies via ontology_refs

e9c4cfb

Merge branch 'main' into feat/datafabric-ontology-fetch-tool

be5ef26

chore: consume uipath dev build (#1728) to unblock CI

1fd7a30

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

chore: revert temp dev-build pin; fix datafabric test mypy

a871a0a

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge branch 'main' into feat/datafabric-ontology-fetch-tool

dfdd3d6

sankalp-uipath requested a review from Copilot June 23, 2026 14:06

Copilot started reviewing on behalf of sankalp-uipath June 23, 2026 14:07 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

Merge branch 'main' into feat/datafabric-ontology-fetch-tool

a07adb9

sankalp-uipath mentioned this pull request Jun 24, 2026

feat(datafabric): fetch ontology R2RML alongside OWL #935

Open

sankalp-uipath added 2 commits June 25, 2026 13:43

refactor(datafabric): resolve ontologies from nested ontologySet

54db78f

refactor(datafabric): gather ontologies from datafabricontology context

941f3ff

UIPath-Harshit reviewed Jun 26, 2026

View reviewed changes

feat(datafabric): gate fetch_ontology behind DataFabricOntologyEnable…

86e5912

…d flag

sankalp-uipath force-pushed the feat/datafabric-ontology-fetch-tool branch from 8b04daa to 86e5912 Compare June 29, 2026 20:13

andreitava-uip reviewed Jun 30, 2026

View reviewed changes

sankalp-uipath added 3 commits June 30, 2026 16:06

test(datafabric): drop ontology referenceKey fixture

826f036

refactor(datafabric): gate ontology flag at every entry; share flag c…

e57d1b0

…onstant

Merge remote-tracking branch 'origin/main' into feat/datafabric-ontol…

2f41f40

…ogy-fetch-tool

andreitava-uip reviewed Jun 30, 2026

View reviewed changes

refactor(datafabric): address review nits (split bind test, single-st…

7fab6d5

…ring ontology prompt)

sankalp-uipath force-pushed the feat/datafabric-ontology-fetch-tool branch from fbb0bea to 9a4a187 Compare July 1, 2026 09:01

refactor(datafabric): inject ontology into system prompt, drop fetch_…

a35807b

…ontology tool

sankalp-uipath force-pushed the feat/datafabric-ontology-fetch-tool branch from 9a4a187 to a35807b Compare July 1, 2026 10:04

sankalp-uipath changed the title ~~feat(datafabric): add fetch_ontology tool to DF inner SQL agent~~ feat(datafabric): inject ontology schema into inner SQL agent system prompt Jul 1, 2026

		tool = create_datafabric_query_tool(resource, MagicMock()) # type: ignore[arg-type]

		assert tool.coroutine._ontologies == [("library", "f1")]

		tool = create_datafabric_query_tool(resource, MagicMock()) # type: ignore[arg-type]

		assert tool.coroutine._ontologies == []

Uh oh!

Conversation

sankalp-uipath commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sankalp-uipath Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sankalp-uipath Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sankalp-uipath Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Jul 1, 2026

Quality Gate failed

Uh oh!

sankalp-uipath commented Jun 16, 2026 •

edited

Loading

sankalp-uipath Jun 29, 2026 •

edited

Loading

sankalp-uipath Jul 1, 2026 •

edited

Loading

sankalp-uipath Jul 1, 2026 •

edited

Loading