feat: introduce ToolsConfiguration on AgentMcpResourceConfig

Adds Cached / Dynamic discriminated union under a new ToolsConfiguration
model accessed via tools_configuration.cached_behaviour on the MCP resource.
Cached corresponds to the old dynamic_tools=none; Dynamic corresponds to
dynamic_tools=all. Schema mode is dropped from the new model for now and
will be reintroduced in a later sprint.

The old dynamic_tools field is removed from the model. Existing agent.json
files that still serialize dynamicTools (any value) continue to parse
unchanged because BaseCfg keeps extra="allow"; the legacy DynamicToolsMode
enum stays exported as a deprecated alias.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: radugheo

packages/uipath/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath"
-version = "2.10.67"
+version = "2.10.68"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath/src/uipath/agent/models/agent.py

@@ -446,13 +446,55 @@ class AgentMcpTool(BaseCfg):
 
 
 class DynamicToolsMode(str, CaseInsensitiveEnum):
-    """Dynamic tools mode enumeration."""
+    """Dynamic tools mode enumeration.
+
+    Deprecated: kept for backwards compatibility with older ``agent.json`` files
+    that still serialize the ``dynamicTools`` field. New code should use
+    :class:`ToolsConfiguration` (see ``AgentMcpResourceConfig.tools_configuration``).
+    """
 
     NONE = "none"
     SCHEMA = "schema"
     ALL = "all"
 
 
+class Cached(BaseCfg):
+    """Cached tools configuration: use the tools saved in the agent definition snapshot."""
+
+    type: Literal["cached"] = Field(default="cached", frozen=True)
+
+
+class Schema(BaseCfg):
+    """Schema tools configuration: server discovery filtered by snapshot allowlist.
+
+    Fetches the live tool list from the MCP server, but keeps only the tools
+    whose names are in the snapshot's ``available_tools``.
+
+    Not currently exposed in the frontend; the runtime continues to honor it so
+    the option can be re-enabled later without further model changes.
+    """
+
+    type: Literal["schema"] = Field(default="schema", frozen=True)
+
+
+class Dynamic(BaseCfg):
+    """Dynamic tools configuration: use whatever tools the MCP server exposes at runtime, with live schemas."""
+
+    type: Literal["dynamic"] = Field(default="dynamic", frozen=True)
+
+
+CachedBehaviour = Annotated[
+    Union[Cached, Schema, Dynamic],
+    Field(discriminator="type"),
+]
+
+
+class ToolsConfiguration(BaseCfg):
+    """Configuration describing how tools are sourced for an MCP resource."""
+
+    cached_behaviour: CachedBehaviour = Field(alias="cachedBehaviour")
+
+
 class AgentMcpResourceConfig(BaseAgentResourceConfig):
     """Agent MCP resource configuration model."""
 
@@ -462,8 +504,8 @@ class AgentMcpResourceConfig(BaseAgentResourceConfig):
     folder_path: str = Field(alias="folderPath")
     slug: str = Field(..., alias="slug")
     available_tools: List[AgentMcpTool] = Field(..., alias="availableTools")
-    dynamic_tools: DynamicToolsMode = Field(
-        default=DynamicToolsMode.NONE, alias="dynamicTools"
+    tools_configuration: Optional[ToolsConfiguration] = Field(
+        default=None, alias="toolsConfiguration"
     )
 
 
@@ -1337,6 +1379,27 @@ def _normalize_resources(v: Dict[str, Any]) -> None:
                     )
                     res["settings"] = settings
 
+            if res["$resourceType"] == "mcp":
+                # Legacy migration: translate `dynamicTools` (string enum) into
+                # `toolsConfiguration.cachedBehaviour` (discriminated union) when
+                # the new field is absent. Without this, old agent.json files
+                # with `dynamicTools="all"` would silently fall back to Cached.
+                has_new_field = (
+                    "toolsConfiguration" in res or "tools_configuration" in res
+                )
+                if not has_new_field:
+                    legacy = res.get("dynamicTools") or res.get("dynamic_tools")
+                    if isinstance(legacy, str):
+                        mapped_type = {
+                            "none": "cached",
+                            "schema": "schema",
+                            "all": "dynamic",
+                        }.get(legacy.lower())
+                        if mapped_type is not None:
+                            res["toolsConfiguration"] = {
+                                "cachedBehaviour": {"type": mapped_type}
+                            }
+
             out.append(res)
 
         v["resources"] = out

packages/uipath/tests/agent/models/test_agent.py

@@ -3950,3 +3950,90 @@ def test_argument_group_name_recipient_missing_argument_name_raises(self):
         payload = {"type": 8}
         with pytest.raises(ValidationError):
             TypeAdapter(AgentEscalationRecipient).validate_python(payload)
+
+
+class TestMcpToolsConfigurationLegacyMigration:
+    """Legacy `dynamicTools` is migrated into `toolsConfiguration` when missing."""
+
+    @staticmethod
+    def _mcp_resource(extra: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "$resourceType": "mcp",
+            "id": "11111111-1111-1111-1111-111111111111",
+            "name": "mcp_server",
+            "description": "Test MCP",
+            "isEnabled": True,
+            "slug": "mcp-server-time",
+            "folderPath": "/Shared",
+            "availableTools": [],
+            **extra,
+        }
+
+    @staticmethod
+    def _agent_def_payload(mcp_resource: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "id": "00000000-0000-0000-0000-000000000000",
+            "version": "1.1.0",
+            "name": "Agent",
+            "inputSchema": {"type": "object", "properties": {}},
+            "outputSchema": {"type": "object", "properties": {}},
+            "settings": {
+                "model": "gpt-5.4",
+                "maxTokens": 1000,
+                "temperature": 0,
+                "engine": "basic-v2",
+                "maxIterations": 10,
+                "mode": "standard",
+            },
+            "messages": [],
+            "resources": [mcp_resource],
+            "guardrails": [],
+        }
+
+    @pytest.mark.parametrize(
+        "legacy, expected_type",
+        [
+            ("none", "cached"),
+            ("schema", "schema"),
+            ("all", "dynamic"),
+            ("ALL", "dynamic"),  # case-insensitive
+        ],
+    )
+    def test_legacy_dynamic_tools_migrates_to_tools_configuration(
+        self, legacy: str, expected_type: str
+    ):
+        payload = self._agent_def_payload(self._mcp_resource({"dynamicTools": legacy}))
+        config: AgentDefinition = TypeAdapter(AgentDefinition).validate_python(payload)
+        mcp = next(
+            r for r in config.resources if r.resource_type == AgentResourceType.MCP
+        )
+        assert isinstance(mcp, AgentMcpResourceConfig)
+        assert mcp.tools_configuration is not None
+        assert mcp.tools_configuration.cached_behaviour.type == expected_type
+
+    def test_new_field_wins_when_both_are_present(self):
+        # toolsConfiguration is the source of truth when both fields are set.
+        payload = self._agent_def_payload(
+            self._mcp_resource(
+                {
+                    "dynamicTools": "all",
+                    "toolsConfiguration": {"cachedBehaviour": {"type": "cached"}},
+                }
+            )
+        )
+        config: AgentDefinition = TypeAdapter(AgentDefinition).validate_python(payload)
+        mcp = next(
+            r for r in config.resources if r.resource_type == AgentResourceType.MCP
+        )
+        assert isinstance(mcp, AgentMcpResourceConfig)
+        assert mcp.tools_configuration is not None
+        assert mcp.tools_configuration.cached_behaviour.type == "cached"
+
+    def test_missing_both_fields_leaves_configuration_unset(self):
+        payload = self._agent_def_payload(self._mcp_resource({}))
+        config: AgentDefinition = TypeAdapter(AgentDefinition).validate_python(payload)
+        mcp = next(
+            r for r in config.resources if r.resource_type == AgentResourceType.MCP
+        )
+        assert isinstance(mcp, AgentMcpResourceConfig)
+        assert mcp.tools_configuration is None