feat: Enhance PowerPlatformEnvironment with DirectConnect URL support and new request models

[MattB-msft]

• Added support for DirectConnect URL mode in PowerPlatformEnvironment, allowing simplified connection setup.
• Introduced StartRequest model for initiating conversations with optional locale and conversation ID.
• Created SubscribeEvent, SubscribeRequest, and SubscribeResponse models for handling subscription operations.
• Implemented UserAgentHelper for generating user agent headers.
• Updated README with new usage examples for DirectConnect URL and advanced configuration options.
• Enhanced tests to cover new features and ensure functionality of DirectConnect URL handling.

This pull request introduces several improvements and new features to the microsoft-agents-copilotstudio-client package, focusing on enhanced configuration flexibility, environment-based setup, and improved HTTP request handling. The most significant changes include new options for connection settings, a utility for environment-driven configuration, and automatic user agent header management.

Enhancements to connection configuration and environment support:

• The ConnectionSettings class now supports additional parameters: direct_connect_url, use_experimental_endpoint, and enable_diagnostics, allowing for more flexible and advanced connection scenarios. [1] [2]
• Added a populate_from_environment static method to ConnectionSettings that enables populating all connection-related settings from environment variables, simplifying configuration in deployment and CI/CD environments.

Improvements to HTTP request handling:

• The CopilotClient now automatically adds a custom User-Agent header to all outgoing requests via the new UserAgentHelper, improving diagnostics and traceability.

API surface and import updates:

• Updated __init__.py to expose new classes and protocols, including CopilotClientProtocol, StartRequest, SubscribeEvent, SubscribeRequest, SubscribeResponse, and UserAgentHelper, making them available for import. [1] [2]

Documentation and guidance:

• Added a comprehensive CLAUDE.md file that provides an overview of the repository, setup instructions, architecture, code style, testing, and common pitfalls, serving as a valuable resource for new contributors.

[Copilot]

Pull request overview

This PR expands the microsoft-agents-copilotstudio-client package to support DirectConnect URL-based configuration, adds new request/response models for starting and subscribing, and introduces automatic User-Agent header generation to improve request traceability.

Changes:

• Added DirectConnect URL support and environment-variable-driven configuration via ConnectionSettings.populate_from_environment().
• Introduced new models and APIs: StartRequest, subscription-related models/types, and CopilotClientProtocol.
• Added automatic User-Agent header injection and expanded docs/samples/tests for the new flows.

Reviewed changes

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

Show a summary per file

File	Description
tests/copilotstudio_client/test_copilot_client.py	Adds test coverage for StartRequest, subscribe events, DirectConnect URL handling, and env-based settings population.
test_samples/copilot_studio_client_sample/config.py	Refactors sample config to use ConnectionSettings.populate_from_environment() and adds new optional settings.
test_samples/copilot_studio_client_sample/chat_console_service.py	Updates sample to optionally start conversations via StartRequest.
libraries/microsoft-agents-copilotstudio-client/readme.md	Documents DirectConnect mode, StartRequest usage, subscription flow, and new configuration options.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/user_agent_helper.py	Introduces a helper for building a User-Agent header string.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/subscribe_response.py	Adds a placeholder model for subscribe responses.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/subscribe_request.py	Adds a placeholder model for subscribe requests.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/subscribe_event.py	Adds an event wrapper that pairs an Activity with an SSE event id.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/start_request.py	Adds a StartRequest model with locale + optional conversation id and correct JSON aliases.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/power_platform_environment.py	Adds DirectConnect URL mode, subscribe-link URL support, and cloud decoding from URL hostnames.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/copilot_client_protocol.py	Defines a protocol for Copilot client implementations.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/copilot_client.py	Adds User-Agent injection, StartRequest-based start method, send/execute helpers, and subscribe streaming.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/connection_settings.py	Adds DirectConnect URL + flags and introduces env-var-based settings population helper.
libraries/microsoft-agents-copilotstudio-client/microsoft_agents/copilotstudio/client/init.py	Exposes the new protocol, models, and helper via package exports.
CLAUDE.md	Adds repository-level contributor guidance (setup, architecture, style, testing).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.