microsoft-agents-copilotstudio-client 1.9.0.dev5__tar.gz → 1.9.0.dev10__tar.gz

{microsoft_agents_copilotstudio_client-1.9.0.dev5/microsoft_agents_copilotstudio_client.egg-info → microsoft_agents_copilotstudio_client-1.9.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-copilotstudio-client
-Version: 1.9.0.dev5
+Version: 1.9.0.dev10
 Summary: A client library for Microsoft Agents
 Author: Microsoft Corporation
 License-Expression: MIT
@@ -15,7 +15,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: microsoft-agents-hosting-core==1.9.0.dev5
+Requires-Dist: microsoft-agents-hosting-core==1.9.0.dev10
 Dynamic: license-file
 Dynamic: requires-dist
 
@@ -230,6 +230,28 @@ def create_client():
     return copilot_client
 ```
 
+#### Conversation Endpoint Discovery
+
+For published agents without a `direct_connect_url`, the client first sends an
+authenticated `GET` to
+`https://<environment-host>/copilotstudio/agents/<escaped-schema-name>/conversation-endpoints`.
+The host is selected from the configured environment and cloud. Discovery uses the
+client's bearer token and the configured `client_session_settings`.
+
+The client validates all advertised endpoints before storing them and uses each
+operation URL as returned, preserving its query string and escaping conversation
+IDs when substituting `{conversationId}`. `createConversation`, `executeTurn`, and
+`continueTurn` are required; `subscribe` is optional and subscription fails
+explicitly when the agent does not advertise it. The client has no continue-turn
+operation.
+
+Successful discovery is reused for the lifetime of the client, with concurrent
+calls coordinated to avoid duplicate initialization. Failures and cancellation
+allow a later call to retry. The discovered create URL is written to
+`settings.direct_connect_url`; clearing that value triggers discovery again.
+Assigning a different explicit URL switches back to legacy direct-URL routing.
+Explicit direct URLs and prebuilt agents bypass discovery entirely.
+
 #### DirectConnect URL Mode (Simplified Setup)
 
 For simplified setup, you can use a DirectConnect URL instead of environment-based configuration:

microsoft_agents_copilotstudio_client-1.9.0.dev10/VERSION.txt

@@ -0,0 +1 @@
+1.9.0.dev10

microsoft_agents_copilotstudio_client-1.9.0.dev10/microsoft_agents/copilotstudio/client/_conversation_endpoint_discovery.py

@@ -0,0 +1,106 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+from urllib.parse import quote, urlsplit, urlunsplit
+
+from .connection_settings import ConnectionSettings
+from .errors import copilot_studio_errors
+from .power_platform_environment import PowerPlatformEnvironment
+
+ConversationOperation = Literal["createConversation", "executeTurn", "subscribe"]
+_CONVERSATION_ID = "{conversationId}"
+
+
+def get_discovery_url(settings: ConnectionSettings) -> str:
+    url = urlsplit(PowerPlatformEnvironment.get_copilot_studio_connection_url(settings))
+    return urlunsplit(
+        (
+            url.scheme,
+            url.netloc,
+            f"/copilotstudio/agents/{quote(settings.agent_identifier, safe='')}/conversation-endpoints",
+            "",
+            "",
+        )
+    )
+
+
+def _validate_url(
+    value: object, discovery_url: str, requires_conversation_id: bool
+) -> str:
+    error = str(copilot_studio_errors.InvalidDiscoveryOperationUrl)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(error)
+
+    remainder = value.replace(_CONVERSATION_ID, "")
+    if (
+        requires_conversation_id != (_CONVERSATION_ID in value)
+        or "{" in remainder
+        or "}" in remainder
+        or "\\" in value
+        or any(character.isspace() or ord(character) < 32 for character in value)
+    ):
+        raise ValueError(error)
+
+    try:
+        discovery = urlsplit(discovery_url)
+        url = urlsplit(value.replace(_CONVERSATION_ID, "conversation"))
+        host = discovery.hostname or ""
+        suffix_index = host.find(".environment.")
+        suffix = host[suffix_index:] if suffix_index >= 0 else "." + host
+        valid = (
+            url.scheme == "https"
+            and (url.port if url.port is not None else 443)
+            == (discovery.port if discovery.port is not None else 443)
+            and bool(url.hostname)
+            and url.hostname.endswith(suffix)
+            and url.username is None
+            and url.password is None
+            and not url.fragment
+        )
+    except ValueError as exc:
+        raise ValueError(error) from exc
+    if not valid:
+        raise ValueError(error)
+    return value
+
+
+@dataclass(frozen=True)
+class ConversationEndpoints:
+    create_conversation: str
+    execute_turn: str
+    continue_turn: str
+    subscribe: Optional[str]
+
+    @classmethod
+    def from_response(cls, data: object, discovery_url: str) -> "ConversationEndpoints":
+        if not isinstance(data, dict):
+            raise ValueError(str(copilot_studio_errors.InvalidDiscoveryResponse))
+
+        return cls(
+            create_conversation=_validate_url(
+                data.get("createConversation"), discovery_url, False
+            ),
+            execute_turn=_validate_url(data.get("executeTurn"), discovery_url, True),
+            continue_turn=_validate_url(data.get("continueTurn"), discovery_url, True),
+            subscribe=(
+                _validate_url(data["subscribe"], discovery_url, True)
+                if data.get("subscribe") is not None
+                else None
+            ),
+        )
+
+    def get_url(
+        self, operation: ConversationOperation, conversation_id: Optional[str] = None
+    ) -> str:
+        if operation == "createConversation":
+            return self.create_conversation
+        if not conversation_id:
+            raise ValueError(str(copilot_studio_errors.DiscoveryConversationIdRequired))
+        url = self.execute_turn if operation == "executeTurn" else self.subscribe
+        if url is None:
+            raise NotImplementedError(
+                str(copilot_studio_errors.DiscoverySubscribeNotSupported)
+            )
+        return url.replace(_CONVERSATION_ID, quote(conversation_id, safe=""))

{microsoft_agents_copilotstudio_client-1.9.0.dev5 → microsoft_agents_copilotstudio_client-1.9.0.dev10}/microsoft_agents/copilotstudio/client/copilot_client.py

@@ -1,13 +1,23 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
-import aiohttp
+import asyncio
+import json
 import logging
 from typing import AsyncIterable, Optional
 
+import aiohttp
+
 from microsoft_agents.activity import Activity, ActivityTypes, ConversationAccount
 
+from ._conversation_endpoint_discovery import (
+    ConversationEndpoints,
+    ConversationOperation,
+    get_discovery_url,
+)
+from .agent_type import AgentType
 from .connection_settings import ConnectionSettings
+from .errors import copilot_studio_errors
 from .execute_turn_request import ExecuteTurnRequest
 from .power_platform_environment import PowerPlatformEnvironment
 from .start_request import StartRequest
@@ -34,6 +44,91 @@ class CopilotClient:
         self._logger = logging.getLogger(__name__)
         self.conversation_id = ""
         self._island_experimental_url = ""
+        self._discovery_lock = asyncio.Lock()
+        self._discovered_direct_connect_url: Optional[str] = None
+        self._discovered_endpoints: Optional[ConversationEndpoints] = None
+
+    async def _resolve_connection_url(
+        self, conversation_id: Optional[str] = None, subscribe: bool = False
+    ) -> str:
+        if (
+            self.settings.copilot_agent_type != AgentType.PREBUILT
+            and not self.settings.direct_connect_url
+        ):
+            async with self._discovery_lock:
+                if (
+                    self.settings.copilot_agent_type != AgentType.PREBUILT
+                    and not self.settings.direct_connect_url
+                ):
+                    endpoints = await self._discover_endpoints()
+                    if (
+                        self.settings.copilot_agent_type != AgentType.PREBUILT
+                        and not self.settings.direct_connect_url
+                    ):
+                        self._discovered_endpoints = endpoints
+                        self._discovered_direct_connect_url = (
+                            endpoints.create_conversation
+                        )
+                        self.settings.direct_connect_url = endpoints.create_conversation
+
+        if (
+            self.settings.copilot_agent_type != AgentType.PREBUILT
+            and self._discovered_endpoints is not None
+            and self.settings.direct_connect_url == self._discovered_direct_connect_url
+        ):
+            operation: ConversationOperation = (
+                "subscribe"
+                if subscribe
+                else "executeTurn" if conversation_id else "createConversation"
+            )
+            return self._discovered_endpoints.get_url(operation, conversation_id)
+        return PowerPlatformEnvironment.get_copilot_studio_connection_url(
+            settings=self.settings,
+            conversation_id=conversation_id,
+            create_subscribe_link=subscribe,
+        )
+
+    async def _discover_endpoints(self) -> ConversationEndpoints:
+        if not self._token or not self._token.strip():
+            raise ValueError(str(copilot_studio_errors.DiscoveryAccessTokenRequired))
+
+        url = get_discovery_url(self.settings)
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": self.APPLICATION_JSON_TYPE,
+            "User-Agent": UserAgentHelper.get_user_agent_header(),
+        }
+        if self.settings.enable_diagnostics:
+            self._logger.debug(">>> SEND TO %s", url)
+
+        async with aiohttp.ClientSession(
+            **self.settings.client_session_settings
+        ) as session:
+            async with session.get(
+                url, headers=headers, allow_redirects=False
+            ) as response:
+                if response.status != 200:
+                    self._logger.error(
+                        "Error discovering conversation endpoints: %s", response.status
+                    )
+                    raise aiohttp.ClientResponseError(
+                        response.request_info,
+                        response.history,
+                        status=response.status,
+                        message="Error discovering conversation endpoints",
+                        headers=response.headers,
+                    )
+                try:
+                    data = await response.json()
+                except (
+                    json.JSONDecodeError,
+                    UnicodeDecodeError,
+                    aiohttp.ContentTypeError,
+                ) as exc:
+                    raise ValueError(
+                        str(copilot_studio_errors.InvalidDiscoveryResponse)
+                    ) from exc
+                return ConversationEndpoints.from_response(data, url)
 
     async def post_request(
         self, url: str, data: dict, headers: dict
@@ -112,9 +207,7 @@ class CopilotClient:
         :return: An asynchronous iterable of Activity objects received in the response.
         """
 
-        url = PowerPlatformEnvironment.get_copilot_studio_connection_url(
-            settings=self.settings
-        )
+        url = await self._resolve_connection_url()
         data = {"emitStartConversationEvent": emit_start_conversation_event}
         headers = {
             "Content-Type": self.APPLICATION_JSON_TYPE,
@@ -164,9 +257,7 @@ class CopilotClient:
             activity.conversation.id or self._current_conversation_id
         )
 
-        url = PowerPlatformEnvironment.get_copilot_studio_connection_url(
-            settings=self.settings, conversation_id=local_conversation_id
-        )
+        url = await self._resolve_connection_url(local_conversation_id)
         data = ExecuteTurnRequest(activity=activity).model_dump(
             mode="json", by_alias=True, exclude_unset=True
         )
@@ -188,9 +279,7 @@ class CopilotClient:
         :return: An asynchronous iterable of Activity objects received in the response.
         """
 
-        url = PowerPlatformEnvironment.get_copilot_studio_connection_url(
-            settings=self.settings
-        )
+        url = await self._resolve_connection_url()
         data = start_request.model_dump(mode="json", by_alias=True, exclude_unset=True)
         headers = {
             "Content-Type": self.APPLICATION_JSON_TYPE,
@@ -249,12 +338,7 @@ class CopilotClient:
         if not conversation_id:
             raise ValueError("CopilotClient.subscribe: conversation_id cannot be None")
 
-        # Build the subscribe URL using the environment helper to ensure correct path and query handling
-        url = PowerPlatformEnvironment.get_copilot_studio_connection_url(
-            settings=self.settings,
-            conversation_id=conversation_id,
-            create_subscribe_link=True,
-        )
+        url = await self._resolve_connection_url(conversation_id, subscribe=True)
         headers = {
             "Content-Type": self.APPLICATION_JSON_TYPE,
             "Authorization": f"Bearer {self._token}",

{microsoft_agents_copilotstudio_client-1.9.0.dev5 → microsoft_agents_copilotstudio_client-1.9.0.dev10}/microsoft_agents/copilotstudio/client/errors/error_resources.py

@@ -52,6 +52,31 @@ class CopilotStudioErrorResources:
         -65006,
     )
 
+    InvalidDiscoveryResponse = ErrorMessage(
+        "Conversation endpoint discovery returned an invalid JSON object.",
+        -65007,
+    )
+
+    InvalidDiscoveryOperationUrl = ErrorMessage(
+        "Conversation endpoint discovery returned an invalid operation URL.",
+        -65008,
+    )
+
+    DiscoveryConversationIdRequired = ErrorMessage(
+        "A conversation ID is required for this operation.",
+        -65009,
+    )
+
+    DiscoverySubscribeNotSupported = ErrorMessage(
+        "The agent does not advertise a subscribe endpoint.",
+        -65010,
+    )
+
+    DiscoveryAccessTokenRequired = ErrorMessage(
+        "A non-empty access token is required for conversation endpoint discovery.",
+        -65011,
+    )
+
     def __init__(self):
         """Initialize CopilotStudioErrorResources."""
         pass

{microsoft_agents_copilotstudio_client-1.9.0.dev5 → microsoft_agents_copilotstudio_client-1.9.0.dev10}/microsoft_agents/copilotstudio/client/power_platform_environment.py

@@ -322,6 +322,7 @@ class PowerPlatformEnvironment:
         if cloud == PowerPlatformCloud.OTHER and not cloud_base_address:
             raise ValueError(str(copilot_studio_errors.CloudBaseAddressRequired))
         cloud_base_address = cloud_base_address or "api.unknown.powerplatform.com"
+        cloud_base_address = urlparse(cloud_base_address).netloc or cloud_base_address
         normalized_resource_id = environment_id.lower().replace("-", "")
         id_suffix_length = PowerPlatformEnvironment.get_id_suffix_length(cloud)
         hex_prefix = normalized_resource_id[:-id_suffix_length]

microsoft_agents_copilotstudio_client-1.9.0.dev5/readme.md → microsoft_agents_copilotstudio_client-1.9.0.dev10/microsoft_agents_copilotstudio_client.egg-info/PKG-INFO

@@ -1,3 +1,24 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-copilotstudio-client
+Version: 1.9.0.dev10
+Summary: A client library for Microsoft Agents
+Author: Microsoft Corporation
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: microsoft-agents-hosting-core==1.9.0.dev10
+Dynamic: license-file
+Dynamic: requires-dist
+
 # Microsoft Agents Copilot Studio Client
 
 [![PyPI version](https://img.shields.io/pypi/v/microsoft-agents-copilotstudio-client)](https://pypi.org/project/microsoft-agents-copilotstudio-client/)
@@ -209,6 +230,28 @@ def create_client():
     return copilot_client
 ```
 
+#### Conversation Endpoint Discovery
+
+For published agents without a `direct_connect_url`, the client first sends an
+authenticated `GET` to
+`https://<environment-host>/copilotstudio/agents/<escaped-schema-name>/conversation-endpoints`.
+The host is selected from the configured environment and cloud. Discovery uses the
+client's bearer token and the configured `client_session_settings`.
+
+The client validates all advertised endpoints before storing them and uses each
+operation URL as returned, preserving its query string and escaping conversation
+IDs when substituting `{conversationId}`. `createConversation`, `executeTurn`, and
+`continueTurn` are required; `subscribe` is optional and subscription fails
+explicitly when the agent does not advertise it. The client has no continue-turn
+operation.
+
+Successful discovery is reused for the lifetime of the client, with concurrent
+calls coordinated to avoid duplicate initialization. Failures and cancellation
+allow a later call to retry. The discovered create URL is written to
+`settings.direct_connect_url`; clearing that value triggers discovery again.
+Assigning a different explicit URL switches back to legacy direct-URL routing.
+Explicit direct URLs and prebuilt agents bypass discovery entirely.
+
 #### DirectConnect URL Mode (Simplified Setup)
 
 For simplified setup, you can use a DirectConnect URL instead of environment-based configuration:
@@ -555,4 +598,4 @@ audience = PowerPlatformEnvironment.get_token_audience(
 |Semantic Kernel Integration|A weather agent built with Semantic Kernel|[semantic-kernel-multiturn](https://github.com/microsoft/Agents/blob/main/samples/python/semantic-kernel-multiturn/README.md)|
 |Streaming Agent|Streams OpenAI responses|[azure-ai-streaming](https://github.com/microsoft/Agents/blob/main/samples/python/azureai-streaming/README.md)|
 |Copilot Studio Client|Console app to consume a Copilot Studio Agent|[copilotstudio-client](https://github.com/microsoft/Agents/blob/main/samples/python/copilotstudio-client/README.md)|
-|Cards Agent|Agent that uses rich cards to enhance conversation design |[cards](https://github.com/microsoft/Agents/blob/main/samples/python/cards/README.md)|
+|Cards Agent|Agent that uses rich cards to enhance conversation design |[cards](https://github.com/microsoft/Agents/blob/main/samples/python/cards/README.md)|

{microsoft_agents_copilotstudio_client-1.9.0.dev5 → microsoft_agents_copilotstudio_client-1.9.0.dev10}/microsoft_agents_copilotstudio_client.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 readme.md
 setup.py
 microsoft_agents/copilotstudio/client/__init__.py
+microsoft_agents/copilotstudio/client/_conversation_endpoint_discovery.py
 microsoft_agents/copilotstudio/client/agent_type.py
 microsoft_agents/copilotstudio/client/connection_settings.py
 microsoft_agents/copilotstudio/client/copilot_client.py

microsoft_agents_copilotstudio_client-1.9.0.dev10/microsoft_agents_copilotstudio_client.egg-info/requires.txt

@@ -0,0 +1 @@
+microsoft-agents-hosting-core==1.9.0.dev10

microsoft_agents_copilotstudio_client-1.9.0.dev5/PKG-INFO → microsoft_agents_copilotstudio_client-1.9.0.dev10/readme.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: microsoft-agents-copilotstudio-client
-Version: 1.9.0.dev5
-Summary: A client library for Microsoft Agents
-Author: Microsoft Corporation
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/microsoft/Agents
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: microsoft-agents-hosting-core==1.9.0.dev5
-Dynamic: license-file
-Dynamic: requires-dist
-
 # Microsoft Agents Copilot Studio Client
 
 [![PyPI version](https://img.shields.io/pypi/v/microsoft-agents-copilotstudio-client)](https://pypi.org/project/microsoft-agents-copilotstudio-client/)
@@ -230,6 +209,28 @@ def create_client():
     return copilot_client
 ```
 
+#### Conversation Endpoint Discovery
+
+For published agents without a `direct_connect_url`, the client first sends an
+authenticated `GET` to
+`https://<environment-host>/copilotstudio/agents/<escaped-schema-name>/conversation-endpoints`.
+The host is selected from the configured environment and cloud. Discovery uses the
+client's bearer token and the configured `client_session_settings`.
+
+The client validates all advertised endpoints before storing them and uses each
+operation URL as returned, preserving its query string and escaping conversation
+IDs when substituting `{conversationId}`. `createConversation`, `executeTurn`, and
+`continueTurn` are required; `subscribe` is optional and subscription fails
+explicitly when the agent does not advertise it. The client has no continue-turn
+operation.
+
+Successful discovery is reused for the lifetime of the client, with concurrent
+calls coordinated to avoid duplicate initialization. Failures and cancellation
+allow a later call to retry. The discovered create URL is written to
+`settings.direct_connect_url`; clearing that value triggers discovery again.
+Assigning a different explicit URL switches back to legacy direct-URL routing.
+Explicit direct URLs and prebuilt agents bypass discovery entirely.
+
 #### DirectConnect URL Mode (Simplified Setup)
 
 For simplified setup, you can use a DirectConnect URL instead of environment-based configuration:
@@ -576,4 +577,4 @@ audience = PowerPlatformEnvironment.get_token_audience(
 |Semantic Kernel Integration|A weather agent built with Semantic Kernel|[semantic-kernel-multiturn](https://github.com/microsoft/Agents/blob/main/samples/python/semantic-kernel-multiturn/README.md)|
 |Streaming Agent|Streams OpenAI responses|[azure-ai-streaming](https://github.com/microsoft/Agents/blob/main/samples/python/azureai-streaming/README.md)|
 |Copilot Studio Client|Console app to consume a Copilot Studio Agent|[copilotstudio-client](https://github.com/microsoft/Agents/blob/main/samples/python/copilotstudio-client/README.md)|
-|Cards Agent|Agent that uses rich cards to enhance conversation design |[cards](https://github.com/microsoft/Agents/blob/main/samples/python/cards/README.md)|
+|Cards Agent|Agent that uses rich cards to enhance conversation design |[cards](https://github.com/microsoft/Agents/blob/main/samples/python/cards/README.md)|

microsoft_agents_copilotstudio_client-1.9.0.dev5/VERSION.txt

@@ -1 +0,0 @@
-1.9.0.dev5

microsoft_agents_copilotstudio_client-1.9.0.dev5/microsoft_agents_copilotstudio_client.egg-info/requires.txt

@@ -1 +0,0 @@
-microsoft-agents-hosting-core==1.9.0.dev5