From e3aef56bd03d2a62f40778330d4a10980eea552e Mon Sep 17 00:00:00 2001 From: Dmytro Struk <13853051+dmytrostruk@users.noreply.github.com> Date: Thu, 11 Sep 2025 15:28:45 -0700 Subject: [PATCH] Added examples --- .../samples/getting_started/agents/README.md | 6 ++ .../agents/copilotstudio/README.md | 96 +++++++++++++++++++ .../copilotstudio/copilotstudio_basic.py | 47 +++++++++ .../copilotstudio_with_explicit_settings.py | 87 +++++++++++++++++ 4 files changed, 236 insertions(+) create mode 100644 python/samples/getting_started/agents/copilotstudio/README.md create mode 100644 python/samples/getting_started/agents/copilotstudio/copilotstudio_basic.py create mode 100644 python/samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py diff --git a/python/samples/getting_started/agents/README.md b/python/samples/getting_started/agents/README.md index 14233b7812..80aa37a533 100644 --- a/python/samples/getting_started/agents/README.md +++ b/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 | diff --git a/python/samples/getting_started/agents/copilotstudio/README.md b/python/samples/getting_started/agents/copilotstudio/README.md new file mode 100644 index 0000000000..bc862b6cb3 --- /dev/null +++ b/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 diff --git a/python/samples/getting_started/agents/copilotstudio/copilotstudio_basic.py b/python/samples/getting_started/agents/copilotstudio/copilotstudio_basic.py new file mode 100644 index 0000000000..169f9957cd --- /dev/null +++ b/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()) diff --git a/python/samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py b/python/samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py new file mode 100644 index 0000000000..46566dfab7 --- /dev/null +++ b/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())