fix: add name-based MCP and A2A lookup

Author: radugheo

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.2.13"
+version = "0.2.14"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-platform/src/uipath/platform/agenthub/_remote_a2a_service.py

@@ -7,13 +7,15 @@
 
 import warnings
 from typing import Any, List
+from urllib.parse import quote
 
 from ..common._base_service import BaseService
 from ..common._bindings import resource_override
 from ..common._config import UiPathApiConfig
 from ..common._execution_context import UiPathExecutionContext
 from ..common._folder_context import FolderContext, header_folder
 from ..common._models import Endpoint, RequestSpec
+from ..common._resource_identifier import resolve_retrieve_identifier
 from ..orchestrator import FolderService
 from .remote_a2a import RemoteA2aAgent
 
@@ -150,20 +152,23 @@ async def main():
         data = response.json()
         return [RemoteA2aAgent.model_validate(agent) for agent in data.get("value", [])]
 
+    @resource_override(resource_type="remoteA2aAgent", resource_identifier="name")
     @resource_override(resource_type="remoteA2aAgent", resource_identifier="slug")
     def retrieve(
         self,
-        slug: str,
+        slug: str | None = None,
         *,
+        name: str | None = None,
         folder_path: str | None = None,
     ) -> RemoteA2aAgent:
-        """Retrieve a specific Remote A2A agent by slug.
+        """Retrieve a Remote A2A agent by its display name or legacy slug.
 
         .. warning::
             This method is experimental and subject to change.
 
         Args:
-            slug: The unique slug identifier for the agent.
+            slug: The legacy slug identifier of the agent.
+            name: The display name of the agent.
             folder_path: The folder path where the agent is located.
 
         Returns:
@@ -183,7 +188,8 @@ def retrieve(
             "remote_a2a.retrieve is experimental and subject to change.",
             stacklevel=2,
         )
-        spec = self._retrieve_spec(slug=slug, folder_path=folder_path)
+        identifier = resolve_retrieve_identifier(name=name, slug=slug)
+        spec = self._retrieve_spec(name=identifier, folder_path=folder_path)
         response = self.request(
             spec.method,
             url=spec.endpoint,
@@ -192,20 +198,23 @@ def retrieve(
         )
         return RemoteA2aAgent.model_validate(response.json())
 
+    @resource_override(resource_type="remoteA2aAgent", resource_identifier="name")
     @resource_override(resource_type="remoteA2aAgent", resource_identifier="slug")
     async def retrieve_async(
         self,
-        slug: str,
+        slug: str | None = None,
         *,
+        name: str | None = None,
         folder_path: str | None = None,
     ) -> RemoteA2aAgent:
-        """Asynchronously retrieve a specific Remote A2A agent by slug.
+        """Asynchronously retrieve a Remote A2A agent by display name or legacy slug.
 
         .. warning::
             This method is experimental and subject to change.
 
         Args:
-            slug: The unique slug identifier for the agent.
+            slug: The legacy slug identifier of the agent.
+            name: The display name of the agent.
             folder_path: The folder path where the agent is located.
 
         Returns:
@@ -229,7 +238,8 @@ async def main():
             "remote_a2a.retrieve_async is experimental and subject to change.",
             stacklevel=2,
         )
-        spec = self._retrieve_spec(slug=slug, folder_path=folder_path)
+        identifier = resolve_retrieve_identifier(name=name, slug=slug)
+        spec = self._retrieve_spec(name=identifier, folder_path=folder_path)
         response = await self.request_async(
             spec.method,
             url=spec.endpoint,
@@ -279,14 +289,16 @@ def _list_spec(
 
     def _retrieve_spec(
         self,
-        slug: str,
+        name: str,
         *,
         folder_path: str | None,
     ) -> RequestSpec:
         folder_key = self._resolve_folder_key(folder_path)
         return RequestSpec(
             method="GET",
-            endpoint=Endpoint(f"/agenthub_/api/remote-a2a-agents/{slug}"),
+            endpoint=Endpoint(
+                f"/agenthub_/api/remote-a2a-agents/{quote(name, safe='')}"
+            ),
             headers={
                 **header_folder(folder_key, None),
             },

packages/uipath-platform/src/uipath/platform/common/_resource_identifier.py

@@ -0,0 +1,12 @@
+"""Shared retrieve-identifier resolution for name/slug resources (MCP servers and Remote A2A agents)."""
+
+
+def resolve_retrieve_identifier(name: str | None, slug: str | None) -> str:
+    """Resolve a retrieve identifier, preferring the display name over the legacy slug."""
+    if name is not None and slug is not None:
+        raise ValueError("Specify either 'name' or 'slug', not both.")
+    if name is not None:
+        return name
+    if slug is not None:
+        return slug
+    raise TypeError("Either 'name' or 'slug' must be provided.")

packages/uipath-platform/src/uipath/platform/orchestrator/_mcp_service.py

@@ -1,4 +1,5 @@
 from typing import List
+from urllib.parse import quote
 
 from uipath.core.tracing import traced
 
@@ -8,6 +9,7 @@
 from ..common._execution_context import UiPathExecutionContext
 from ..common._folder_context import FolderContext, header_folder
 from ..common._models import Endpoint, RequestSpec
+from ..common._resource_identifier import resolve_retrieve_identifier
 from ._folder_service import FolderService
 from .mcp import McpServer
 
@@ -66,7 +68,7 @@ def list(
 
         return [McpServer.model_validate(server) for server in response.json()]
 
-    @traced(name="mcp_list", run_type="uipath")
+    @traced(name="mcp_list_async", run_type="uipath")
     async def list_async(
         self,
         *,
@@ -109,18 +111,21 @@ async def main():
 
         return [McpServer.model_validate(server) for server in response.json()]
 
+    @resource_override(resource_type="mcpServer", resource_identifier="name")
     @resource_override(resource_type="mcpServer", resource_identifier="slug")
     @traced(name="mcp_retrieve", run_type="uipath")
     def retrieve(
         self,
-        slug: str,
+        slug: str | None = None,
         *,
+        name: str | None = None,
         folder_path: str | None = None,
     ) -> McpServer:
-        """Retrieve a specific MCP server by its slug.
+        """Retrieve a specific MCP server by its display name or legacy slug.
 
         Args:
-            slug (str): The unique slug identifier for the server.
+            slug (Optional[str]): The legacy slug identifier of the server.
+            name (Optional[str]): The display name of the server.
             folder_path (Optional[str]): The path of the folder where the server is located.
 
         Returns:
@@ -132,12 +137,13 @@ def retrieve(
 
             client = UiPath()
 
-            server = client.mcp.retrieve(slug="my-server-slug", folder_path="MyFolder")
+            server = client.mcp.retrieve(name="My Server", folder_path="MyFolder")
             print(f"Server: {server.name}, URL: {server.mcp_url}")
             ```
         """
+        identifier = resolve_retrieve_identifier(name=name, slug=slug)
         spec = self._retrieve_spec(
-            slug=slug,
+            name=identifier,
             folder_path=folder_path,
         )
 
@@ -150,18 +156,21 @@ def retrieve(
 
         return McpServer.model_validate(response.json())
 
+    @resource_override(resource_type="mcpServer", resource_identifier="name")
     @resource_override(resource_type="mcpServer", resource_identifier="slug")
-    @traced(name="mcp_retrieve", run_type="uipath")
+    @traced(name="mcp_retrieve_async", run_type="uipath")
     async def retrieve_async(
         self,
-        slug: str,
+        slug: str | None = None,
         *,
+        name: str | None = None,
         folder_path: str | None = None,
     ) -> McpServer:
-        """Asynchronously retrieve a specific MCP server by its slug.
+        """Asynchronously retrieve an MCP server by its display name or legacy slug.
 
         Args:
-            slug (str): The unique slug identifier for the server.
+            slug (Optional[str]): The legacy slug identifier of the server.
+            name (Optional[str]): The display name of the server.
             folder_path (Optional[str]): The path of the folder where the server is located.
 
         Returns:
@@ -176,14 +185,15 @@ async def retrieve_async(
             sdk = UiPath()
 
             async def main():
-                server = await sdk.mcp.retrieve_async(slug="my-server-slug", folder_path="MyFolder")
+                server = await sdk.mcp.retrieve_async(name="My Server", folder_path="MyFolder")
                 print(f"Server: {server.name}, URL: {server.mcp_url}")
 
             asyncio.run(main())
             ```
         """
+        identifier = resolve_retrieve_identifier(name=name, slug=slug)
         spec = self._retrieve_spec(
-            slug=slug,
+            name=identifier,
             folder_path=folder_path,
         )
 
@@ -223,14 +233,14 @@ def _list_spec(
 
     def _retrieve_spec(
         self,
-        slug: str,
+        name: str,
         *,
         folder_path: str | None,
     ) -> RequestSpec:
         folder_key = self._resolve_folder_key(folder_path)
         return RequestSpec(
             method="GET",
-            endpoint=Endpoint(f"/agenthub_/api/servers/{slug}"),
+            endpoint=Endpoint(f"/agenthub_/api/servers/{quote(name, safe='')}"),
             headers={
                 **header_folder(folder_key, None),
             },