{"id":6499,"library":"agent-framework-copilotstudio","title":"Agent Framework Copilot Studio Integration","description":"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.","status":"active","version":"1.0.0b260409","language":"en","source_language":"en","source_url":"https://github.com/iLoveAgents/agent-framework-copilot-studio","tags":["AI","Agents","Microsoft","Copilot Studio","Agent Framework"],"install":[{"cmd":"pip install agent-framework-copilotstudio --pre","lang":"bash","label":"Install preview version"}],"dependencies":[{"reason":"Used for managing environment variables for configuration.","package":"python-dotenv","optional":false},{"reason":"Used for asynchronous HTTP requests, likely for communication with Copilot Studio APIs.","package":"aiohttp","optional":false}],"imports":[{"symbol":"CopilotStudioAgent","correct":"from agent_framework.microsoft import CopilotStudioAgent"}],"quickstart":{"code":"import asyncio\nimport os\n\n# Ensure these environment variables are set before running:\n# COPILOTSTUDIOAGENT__ENVIRONMENTID=\"Default-<guid>\"\n# COPILOTSTUDIOAGENT__SCHEMANAME=\"<your-agent-schema-name>\"\n# COPILOTSTUDIOAGENT__AGENTAPPID=\"<your-client-id>\"\n# COPILOTSTUDIOAGENT__TENANTID=\"<your-tenant-id>\"\n\n# Example of how you might get them (replace with actual secure methods in production)\n# os.environ['COPILOTSTUDIOAGENT__ENVIRONMENTID'] = os.environ.get('COPILOTSTUDIOAGENT__ENVIRONMENTID', '')\n# os.environ['COPILOTSTUDIOAGENT__SCHEMANAME'] = os.environ.get('COPILOTSTUDIOAGENT__SCHEMANAME', '')\n# os.environ['COPILOTSTUDIOAGENT__AGENTAPPID'] = os.environ.get('COPILOTSTUDIOAGENT__AGENTAPPID', '')\n# os.environ['COPILOTSTUDIOAGENT__TENANTID'] = os.environ.get('COPILOTSTUDIOAGENT__TENANTID', '')\n\nfrom agent_framework.microsoft import CopilotStudioAgent\n\nasync def main():\n    try:\n        agent = CopilotStudioAgent()\n        print(f\"Agent initialized with Environment ID: {os.environ.get('COPILOTSTUDIOAGENT__ENVIRONMENTID', 'Not Set')}\")\n        print(\"Sending query to Copilot Studio agent...\")\n        result = await agent.run(\"What are our company policies on remote work?\")\n        print(f\"Agent response: {result}\")\n        \n        print(\"\\nStreaming example:\")\n        print(\"Agent (streaming): \", end=\"\", flush=True)\n        async for chunk in agent.run(\"What is the largest city in France?\", stream=True):\n            if chunk.text:\n                print(chunk.text, end=\"\", flush=True)\n        print()\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Please ensure all required environment variables are set and your Copilot Studio agent is correctly configured and published.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Multilevel agent chaining is not supported, which can limit complex multi-agent orchestration scenarios.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Use the correct import statement: 'from microsoft_agents import CopilotStudioAgent'.","cause":"The package is named 'microsoft_agents' but the import statement uses 'microsoft', leading to a module not found error.","error":"ModuleNotFoundError: No module named 'microsoft'"},{"fix":"Import 'CopilotStudioAgent' from the correct module: 'from agent_framework.microsoft import CopilotStudioAgent'.","cause":"The 'CopilotStudioAgent' class is not located in 'semantic_kernel.agents', causing an import error.","error":"ImportError: cannot import name 'CopilotStudioAgent' from 'semantic_kernel.agents'"},{"fix":"Ensure the 'agent-framework-copilotstudio' package is installed and use the correct import path: 'from agent_framework.microsoft import CopilotStudioAgent'.","cause":"Attempting to import 'copilotstudio' directly, which does not exist as a standalone module.","error":"ModuleNotFoundError: No module named 'copilotstudio'"},{"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.","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.","error":"ModuleNotFoundError: No module named 'microsoft.agents'"},{"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.","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.","error":"ModuleNotFoundError: No module named 'copilot.types'"}]}