chore: import upstream snapshot with attribution

python/samples/02-agents/providers/copilotstudio/README.md

@@ -0,0 +1,105 @@
+# 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
+import asyncio
+from agent_framework.microsoft import CopilotStudioAgent
+
+# Uses environment variables for configuration
+async def main():
+    # Create agent using environment variables
+    agent = CopilotStudioAgent()
+
+    # Run a simple query
+    result = await agent.run("What is the capital of France?")
+    print(result)
+
+asyncio.run(main())
+```
+
+### Explicit Configuration
+
+```python
+from agent_framework.microsoft 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,
+    custom_power_platform_cloud=None
+)
+
+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/02-agents/providers/copilotstudio/copilotstudio_basic.py

@@ -0,0 +1,59 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework.microsoft import CopilotStudioAgent
+from dotenv import load_dotenv
+
+"""
+Copilot Studio Agent Basic Example
+
+This sample demonstrates basic usage of CopilotStudioAgent with automatic configuration
+from environment variables, showing both streaming and non-streaming responses.
+"""
+
+
+# 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
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+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(query, stream=True):
+        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/02-agents/providers/copilotstudio/copilotstudio_with_explicit_settings.py

@@ -0,0 +1,109 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-copilotstudio",
+#     "microsoft-agents",
+# ]
+# ///
+# Run with any PEP 723 compatible runner, e.g.:
+#   uv run samples/02-agents/providers/copilotstudio/copilotstudio_with_explicit_settings.py
+
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework.microsoft import CopilotStudioAgent, acquire_token
+from dotenv import load_dotenv
+from microsoft_agents.copilotstudio.client import AgentType, ConnectionSettings, CopilotClient, PowerPlatformCloud
+
+"""
+Copilot Studio Agent with Explicit Settings Example
+
+This sample demonstrates explicit configuration of CopilotStudioAgent with manual
+token management and custom ConnectionSettings for production environments.
+"""
+
+
+# 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
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+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())