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

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	Basic non-streaming and streaming execution with simple questions
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

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

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