Discovery endpoint for MCS client

[Axel Suárez (axelsrz)]

This pull request introduces conversation endpoint discovery to the Copilot Studio client, improving how the client locates and validates agent endpoints for published agents. The client now discovers, validates, and caches conversation operation URLs for published agents without a direct_connect_url, and falls back to legacy routing for prebuilt agents or explicit URLs. Error handling and documentation are also enhanced. The most important changes are grouped below.

Conversation Endpoint Discovery

• Added a new _conversation_endpoint_discovery.py module implementing endpoint discovery, validation, and the ConversationEndpoints dataclass for managing operation URLs. This includes strict validation of discovered URLs and error handling for invalid responses or missing data.
• Integrated endpoint discovery into CopilotClient, including asynchronous discovery, caching, and thread-safe initialization. All conversation operations (start_conversation, ask_question_with_activity, start_conversation_with_request, subscribe) now use the discovered endpoints when appropriate. [1] [2] [3] [4] [5] [6]
• Updated the documentation (readme.md and sample README) to describe endpoint discovery, configuration, and usage, including sample environment variables and setup instructions. [1] [2] [3]

Error Handling and Validation

• Added new error messages and codes for discovery failures, invalid URLs, missing conversation IDs, unsupported subscribe operations, and missing access tokens.
• Improved normalization of the cloud base address in environment endpoint selection.

Sample and Test Improvements

• Improved the sample client to use the new discovery mechanism, clarified token acquisition, and refactored the entry point for better readability and maintainability. [1] [2] [3]

These changes modernize the client’s connection logic, improve robustness, and provide clearer guidance for users and developers.

[Copilot]

🟡 Changes recommended

Discovery introduces routing regressions for clients sharing settings and published agents using experimental endpoints.

2 open findings

• Discovered URL suppresses experimental endpoint response handling · New
• Shared settings mutation breaks discovery state and endpoint routing · New

What changed in this PR

Adds conversation endpoint discovery to the Copilot Studio client for published agents, while retaining legacy routing for explicit URLs and prebuilt agents.

Changes:

• Discovers, validates, and caches operation URLs.
• Adds discovery error handling and regression tests.
• Updates documentation and sample authentication and configuration.

File	Description
tests/​copilotstudio_client/​test_copilot_client.py	Adjusts legacy-routing tests.
tests/​copilotstudio_client/​test_conversation_endpoint_discovery.py	Tests discovery, validation, caching, and retries.
tests/​copilotstudio_client/​test_console_sample.py	Tests token acquisition behavior.
test_samples/​copilot_studio_client_sample/​README.md	Documents setup and discovery.
test_samples/​copilot_studio_client_sample/​env.TEMPLATE	Adds cloud and discovery configuration.
test_samples/​copilot_studio_client_sample/​app.py	Updates authentication and entry point.
libraries/​microsoft-agents-copilotstudio-client/​readme.md	Explains discovery and overrides.
libraries/​microsoft-agents-copilotstudio-client/​microsoft_agents/​copilotstudio/​client/​power_platform_environment.py	Normalizes cloud base addresses.
libraries/​microsoft-agents-copilotstudio-client/​microsoft_agents/​copilotstudio/​client/​errors/​error_resources.py	Adds discovery errors.
libraries/​microsoft-agents-copilotstudio-client/​microsoft_agents/​copilotstudio/​client/​copilot_client.py	Integrates discovery into conversation operations.
libraries/​microsoft-agents-copilotstudio-client/​microsoft_agents/​copilotstudio/​client/​_conversation_endpoint_discovery.py	Implements endpoint validation and substitution.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.