Python: Added Copilot Studio Agent (#722)

* Small fix in dotnet conformance tests

* Added CopilotStudioAgent implementation

* Added examples

* Updated package README

* Small fixes

* Small improvements

* Fixed dotnet tests

* Add unit tests

* Updated tests

* Small updates

* Small test fixes

* Revert "Small test fixes"

This reverts commit 983ac44a70.

* Small fixes in documentation

* Updated test configuration

* Revert "Updated test configuration"

This reverts commit 2a16fea815.

* Small fix

* Reverted TODO item

* Small suppressions

* More fixes

* Small fixes

* Fixed tests

* Removed disallow_any_unimported rule in all packages

* Fixes

python/samples/getting_started/agents/README.md

@@ -10,6 +10,12 @@ This folder contains examples demonstrating how to create and use agents with di
 |--------|-------------|
 | **[`foundry/`](foundry/)** | Create agents using Azure AI Foundry |
 
+### Microsoft Copilot Studio Examples
+
+| Folder | Description |
+|--------|-------------|
+| **[`copilotstudio/`](copilotstudio/)** | Create agents using Microsoft Copilot Studio |
+
 ### Azure OpenAI Examples
 
 | Folder | Description |

python/samples/getting_started/agents/copilotstudio/README.md

@@ -0,0 +1,96 @@
+# Copilot Studio Agent Examples
+
+This folder contains examples demonstrating how to create and use agents with Microsoft Copilot Studio using the Agent Framework.
+
+## Prerequisites
+
+Before running these examples, you need:
+
+1. **Copilot Studio Environment**: Access to a Microsoft Copilot Studio environment with a published copilot
+2. **App Registration**: An Azure AD App Registration with appropriate permissions
+3. **Environment Variables**: Set the following environment variables:
+   - `COPILOTSTUDIOAGENT__ENVIRONMENTID` - Your Copilot Studio environment ID
+   - `COPILOTSTUDIOAGENT__SCHEMANAME` - Your copilot's agent identifier/schema name
+   - `COPILOTSTUDIOAGENT__AGENTAPPID` - Your App Registration client ID
+   - `COPILOTSTUDIOAGENT__TENANTID` - Your Azure AD tenant ID
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| **[`copilotstudio_basic.py`](copilotstudio_basic.py)** | Basic non-streaming and streaming execution with simple questions |
+| **[`copilotstudio_with_explicit_settings.py`](copilotstudio_with_explicit_settings.py)** | Example with explicit settings and manual token acquisition |
+
+## Authentication
+
+The examples use MSAL (Microsoft Authentication Library) for authentication. The first time you run an example, you may need to complete an interactive authentication flow in your browser.
+
+### App Registration Setup
+
+Your Azure AD App Registration should have:
+
+1. **API Permissions**: 
+   - Power Platform API permissions (https://api.powerplatform.com/.default)
+   - Appropriate delegated permissions for your organization
+
+2. **Redirect URIs**: 
+   - For public client flows: `http://localhost` 
+   - Configure as appropriate for your authentication method
+
+3. **Authentication**: 
+   - Enable "Allow public client flows" if using interactive authentication
+
+## Usage Patterns
+
+### Basic Usage with Environment Variables
+
+```python
+from agent_framework.copilotstudio import CopilotStudioAgent
+
+# Uses environment variables for configuration
+agent = CopilotStudioAgent()
+result = await agent.run("What is the capital of France?")
+```
+
+### Explicit Configuration
+
+```python
+from agent_framework.copilotstudio import CopilotStudioAgent, acquire_token
+from microsoft_agents.copilotstudio.client import ConnectionSettings, CopilotClient, PowerPlatformCloud, AgentType
+
+# Acquire token manually
+token = acquire_token(
+    client_id="your-client-id",
+    tenant_id="your-tenant-id"
+)
+
+# Create settings and client
+settings = ConnectionSettings(
+    environment_id="your-environment-id",
+    agent_identifier="your-agent-schema-name",
+    cloud=PowerPlatformCloud.PROD,
+    copilot_agent_type=AgentType.PUBLISHED
+)
+
+client = CopilotClient(settings=settings, token=token)
+agent = CopilotStudioAgent(client=client)
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Errors**: 
+   - Verify your App Registration has correct permissions
+   - Ensure environment variables are set correctly
+   - Check that your tenant ID and client ID are valid
+
+2. **Environment/Agent Not Found**:
+   - Verify your environment ID is correct
+   - Ensure your copilot is published and the schema name is correct
+   - Check that you have access to the specified environment
+
+3. **Token Acquisition Failures**:
+   - Interactive authentication may require browser access
+   - Corporate firewalls may block authentication flows
+   - Try running with appropriate proxy settings if needed

python/samples/getting_started/agents/copilotstudio/copilotstudio_basic.py

@@ -0,0 +1,47 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.copilotstudio import CopilotStudioAgent
+
+# Environment variables needed:
+# COPILOTSTUDIOAGENT__ENVIRONMENTID - Environment ID where your copilot is deployed
+# COPILOTSTUDIOAGENT__SCHEMANAME - Agent identifier/schema name of your copilot
+# COPILOTSTUDIOAGENT__AGENTAPPID - Client ID for authentication
+# COPILOTSTUDIOAGENT__TENANTID - Tenant ID for authentication
+
+
+async def non_streaming_example() -> None:
+    """Example of non-streaming response (get the complete result at once)."""
+    print("=== Non-streaming Response Example ===")
+
+    agent = CopilotStudioAgent()
+
+    query = "What is the capital of France?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Agent: {result}\n")
+
+
+async def streaming_example() -> None:
+    """Example of streaming response (get results as they are generated)."""
+    print("=== Streaming Response Example ===")
+
+    agent = CopilotStudioAgent()
+
+    query = "What is the capital of Spain?"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    async for chunk in agent.run_stream(query):
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+    print("\n")
+
+
+async def main() -> None:
+    await non_streaming_example()
+    await streaming_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py

@@ -0,0 +1,87 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.copilotstudio import CopilotStudioAgent, acquire_token
+from microsoft_agents.copilotstudio.client import AgentType, ConnectionSettings, CopilotClient, PowerPlatformCloud
+
+# Environment variables needed:
+# COPILOTSTUDIOAGENT__ENVIRONMENTID - Environment ID where your copilot is deployed
+# COPILOTSTUDIOAGENT__SCHEMANAME - Agent identifier/schema name of your copilot
+# COPILOTSTUDIOAGENT__AGENTAPPID - Client ID for authentication
+# COPILOTSTUDIOAGENT__TENANTID - Tenant ID for authentication
+
+
+async def example_with_connection_settings() -> None:
+    """Example using explicit ConnectionSettings and CopilotClient."""
+    print("=== Copilot Studio Agent with Connection Settings ===")
+
+    # Configuration from environment variables
+    environment_id = os.environ["COPILOTSTUDIOAGENT__ENVIRONMENTID"]
+    agent_identifier = os.environ["COPILOTSTUDIOAGENT__SCHEMANAME"]
+    client_id = os.environ["COPILOTSTUDIOAGENT__AGENTAPPID"]
+    tenant_id = os.environ["COPILOTSTUDIOAGENT__TENANTID"]
+
+    # Acquire token using the acquire_token function
+    token = acquire_token(
+        client_id=client_id,
+        tenant_id=tenant_id,
+    )
+
+    # Create connection settings
+    settings = ConnectionSettings(
+        environment_id=environment_id,
+        agent_identifier=agent_identifier,
+        cloud=PowerPlatformCloud.PROD,  # Or PowerPlatformCloud.GOV, PowerPlatformCloud.HIGH, etc.
+        copilot_agent_type=AgentType.PUBLISHED,  # Or AgentType.PREBUILT
+        custom_power_platform_cloud=None,  # Optional: for custom cloud endpoints
+    )
+
+    # Create CopilotClient with explicit settings
+    client = CopilotClient(settings=settings, token=token)
+
+    # Create agent with explicit client
+    agent = CopilotStudioAgent(client=client)
+
+    # Run a simple query
+    query = "What is the capital of Italy?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Agent: {result}")
+
+
+async def example_with_explicit_parameters() -> None:
+    """Example using CopilotStudioAgent with all parameters explicitly provided."""
+    print("\n=== Copilot Studio Agent with All Explicit Parameters ===")
+
+    # Configuration from environment variables
+    environment_id = os.environ["COPILOTSTUDIOAGENT__ENVIRONMENTID"]
+    agent_identifier = os.environ["COPILOTSTUDIOAGENT__SCHEMANAME"]
+    client_id = os.environ["COPILOTSTUDIOAGENT__AGENTAPPID"]
+    tenant_id = os.environ["COPILOTSTUDIOAGENT__TENANTID"]
+
+    # Create agent with all parameters explicitly
+    agent = CopilotStudioAgent(
+        environment_id=environment_id,
+        agent_identifier=agent_identifier,
+        client_id=client_id,
+        tenant_id=tenant_id,
+        cloud=PowerPlatformCloud.PROD,
+        agent_type=AgentType.PUBLISHED,
+    )
+
+    # Run a simple query
+    query = "What is the capital of Japan?"
+    print(f"User: {query}")
+    result = await agent.run(query)
+    print(f"Agent: {result}")
+
+
+async def main() -> None:
+    await example_with_connection_settings()
+    await example_with_explicit_parameters()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())