Agent Framework Copilot Studio Integration

1.0.0b260409 · active · verified Wed Apr 15

The `agent-framework-copilotstudio` library provides a Python integration for connecting to Microsoft Copilot Studio agents using the Microsoft Agent Framework. It enables developers to build, orchestrate, and deploy AI agents and multi-agent workflows, supporting both low-code Copilot Studio agents and custom Python agents. The library is actively maintained, with frequent preview releases (indicated by 'b' in version numbers), and is part of Microsoft's broader Agent Framework ecosystem.

Common errors

```
ModuleNotFoundError: No module named 'microsoft'
```
cause The package is named 'microsoft_agents' but the import statement uses 'microsoft', leading to a module not found error.

fix Use the correct import statement: 'from microsoft_agents import CopilotStudioAgent'.
```
ImportError: cannot import name 'CopilotStudioAgent' from 'semantic_kernel.agents'
```
cause The 'CopilotStudioAgent' class is not located in 'semantic_kernel.agents', causing an import error.

fix Import 'CopilotStudioAgent' from the correct module: 'from agent_framework.microsoft import CopilotStudioAgent'.
```
ModuleNotFoundError: No module named 'copilotstudio'
```
cause Attempting to import 'copilotstudio' directly, which does not exist as a standalone module.

fix Ensure the 'agent-framework-copilotstudio' package is installed and use the correct import path: 'from agent_framework.microsoft import CopilotStudioAgent'.
```
ModuleNotFoundError: No module named 'microsoft.agents'
```
cause This error typically occurs when the Python import statement uses a dotted path (e.g., `microsoft.agents`) that does not match the actual installed package name, which often uses underscores (e.g., `microsoft_agents`). This can happen when the `agent-framework-copilotstudio` library or a dependency expects a module path that differs from the installed package structure.

fix Verify the correct package name and module structure. If you're importing a component from `agent-framework-copilotstudio`, ensure the import path precisely matches the installed package's internal layout. For example, if a component is expected from `microsoft.agents.copilotstudio.client`, but the installed package is `microsoft_agents`, you might need to adjust the import or ensure all necessary `agent-framework` packages are installed with correct versions.
```
ModuleNotFoundError: No module named 'copilot.types'
```
cause This error indicates that a module named 'copilot.types' cannot be found, often due to breaking API changes in a dependency (`github-copilot-sdk` in a similar case) or an outdated version of the `agent-framework-copilotstudio` library. The expected module path or component may have been moved or removed in a newer version of an underlying SDK.

fix Ensure that all dependent SDKs (like `github-copilot-sdk` if applicable, or other core Copilot Studio SDKs) are compatible with the `agent-framework-copilotstudio` version you are using. Update `agent-framework-copilotstudio` and its dependencies to their latest compatible versions using `pip install --upgrade agent-framework-copilotstudio` and check for release notes regarding breaking changes or new import paths.

Warnings

gotcha Incorrect or missing environment variables will prevent the agent from connecting. Ensure `COPILOTSTUDIOAGENT__ENVIRONMENTID` (format: `Default-<guid>`), `COPILOTSTUDIOAGENT__SCHEMANAME`, `COPILOTSTUDIOAGENT__AGENTAPPID`, and `COPILOTSTUDIOAGENT__TENANTID` are correctly set and accessible to your application. Your Copilot Studio agent must also be published and accessible in the Power Platform Admin Center.
Fix: Verify all required environment variables are correctly defined. Confirm your Azure AD app registration has public client flows enabled, necessary Power Platform API permissions, and admin consent. Ensure the Copilot Studio agent is published and its environment ID is in the `Default-<guid>` format.
gotcha Vague or overly short topic model descriptions in Copilot Studio can lead to poor agent performance and misinterpretation of user intents. The generative orchestration relies heavily on clear and descriptive topic descriptions.
Fix: Provide detailed and unambiguous topic descriptions within Copilot Studio, focusing on outcomes rather than just features. This helps the underlying large language model correctly route user queries.
gotcha When deploying Copilot Studio agents within Application Lifecycle Management (ALM) solutions, new agent components (like topics or tools) might not be automatically included in the solution. This can lead to missing or outdated components in new environments.
Fix: Always manually add new agent components to your solution after creation. Although you may create an agent within the solution's context, new sub-components often require explicit inclusion.
gotcha Multilevel agent chaining is not supported, which can limit complex multi-agent orchestration scenarios.
Fix: Design multi-agent systems to avoid direct multilevel chaining. Consider alternative orchestration patterns or single-level interactions where a primary agent delegates to other agents without deep nesting.
gotcha Data loss prevention (DLP) errors can occur if connectors used by the agent are not in the same data group or are blocked by the tenant administrator.
Fix: Review your Power Platform data policies. Ensure all connectors utilized by your Copilot Studio agent are allowed and configured within the appropriate data groups to prevent DLP violations. Consult with your Power Platform administrator if necessary.

Install

pip install agent-framework-copilotstudio --pre Install preview version

Imports

CopilotStudioAgent

from agent_framework.microsoft import CopilotStudioAgent

Quickstart

This quickstart demonstrates how to initialize and interact with a `CopilotStudioAgent`. It assumes the necessary environment variables (`COPILOTSTUDIOAGENT__ENVIRONMENTID`, `COPILOTSTUDIOAGENT__SCHEMANAME`, `COPILOTSTUDIOAGENT__AGENTAPPID`, `COPILOTSTUDIOAGENT__TENANTID`) are configured for authentication and agent identification. The example includes both a standard `run` command and a streaming `run` for real-time responses.

import asyncio
import os

# Ensure these environment variables are set before running:
# COPILOTSTUDIOAGENT__ENVIRONMENTID="Default-<guid>"
# COPILOTSTUDIOAGENT__SCHEMANAME="<your-agent-schema-name>"
# COPILOTSTUDIOAGENT__AGENTAPPID="<your-client-id>"
# COPILOTSTUDIOAGENT__TENANTID="<your-tenant-id>"

# Example of how you might get them (replace with actual secure methods in production)
# os.environ['COPILOTSTUDIOAGENT__ENVIRONMENTID'] = os.environ.get('COPILOTSTUDIOAGENT__ENVIRONMENTID', '')
# os.environ['COPILOTSTUDIOAGENT__SCHEMANAME'] = os.environ.get('COPILOTSTUDIOAGENT__SCHEMANAME', '')
# os.environ['COPILOTSTUDIOAGENT__AGENTAPPID'] = os.environ.get('COPILOTSTUDIOAGENT__AGENTAPPID', '')
# os.environ['COPILOTSTUDIOAGENT__TENANTID'] = os.environ.get('COPILOTSTUDIOAGENT__TENANTID', '')

from agent_framework.microsoft import CopilotStudioAgent

async def main():
    try:
        agent = CopilotStudioAgent()
        print(f"Agent initialized with Environment ID: {os.environ.get('COPILOTSTUDIOAGENT__ENVIRONMENTID', 'Not Set')}")
        print("Sending query to Copilot Studio agent...")
        result = await agent.run("What are our company policies on remote work?")
        print(f"Agent response: {result}")
        
        print("\nStreaming example:")
        print("Agent (streaming): ", end="", flush=True)
        async for chunk in agent.run("What is the largest city in France?", stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
        print()

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Please ensure all required environment variables are set and your Copilot Studio agent is correctly configured and published.")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →