{"id":6718,"library":"microsoft-agents-copilotstudio-client","title":"Microsoft Agents Copilot Studio Client","description":"The Microsoft Agents Copilot Studio Client library is a Python SDK for building and hosting custom agent extensions within Microsoft Copilot Studio. It provides an asynchronous framework to define agent behavior, handle incoming messages, manage conversation state, and integrate with the Copilot Studio platform. The library is actively developed, with frequent pre-1.0 releases, indicating an evolving API surface.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/Agents","tags":["microsoft","agents","copilotstudio","ai","client-library","bot","extension","generative-ai"],"install":[{"cmd":"pip install microsoft-agents-copilotstudio-client uvicorn","lang":"bash","label":"Install library and a web server"}],"dependencies":[],"imports":[{"symbol":"Agent","correct":"from microsoft.copilotstudio.agents import Agent"},{"symbol":"AgentExtension","correct":"from microsoft.copilotstudio.agents.extension import AgentExtension"},{"symbol":"AgentActivity","correct":"from microsoft.copilotstudio.agents.models import AgentActivity"},{"symbol":"UserMessage","correct":"from microsoft.copilotstudio.agents.models import UserMessage"},{"symbol":"TurnContext","correct":"from microsoft.copilotstudio.agents.turn_context import TurnContext"}],"quickstart":{"code":"import os\nfrom microsoft.copilotstudio.agents import Agent\nfrom microsoft.copilotstudio.agents.extension import AgentExtension\nfrom microsoft.copilotstudio.agents.models import AgentActivity, UserMessage\nfrom microsoft.copilotstudio.agents.turn_context import TurnContext\n\n# Define your agent\nagent = Agent()\n\n# Define an initial message handler\n@agent.on_message(\"initial_message\")\nasync def initial_message_handler(turn_context: TurnContext):\n    user_message = turn_context.activity.value\n    if user_message and isinstance(user_message, UserMessage):\n        print(f\"Received initial message: {user_message.text}\")\n        await turn_context.send_activity(\n            AgentActivity(value=\"Hello! I'm your Copilot Studio Agent.\")\n        )\n    else:\n        print(\"Received activity is not a UserMessage for initial_message.\")\n\n# Define a follow-up message handler\n@agent.on_message(\"follow_up_message\")\nasync def follow_up_message_handler(turn_context: TurnContext):\n    user_message = turn_context.activity.value\n    if user_message and isinstance(user_message, UserMessage):\n        print(f\"Received follow-up message: {user_message.text}\")\n        await turn_context.send_activity(\n            AgentActivity(value=f\"You said: '{user_message.text}'. How can I help further?\")\n        )\n    else:\n        print(\"Received activity is not a UserMessage for follow_up_message.\")\n\n# Create the AgentExtension application\n# APP_ID and APP_PASSWORD are required for Copilot Studio to authenticate and connect.\n# For local testing, you might leave them empty, but they are critical for deployment.\napp = AgentExtension(agent, app_id=os.environ.get(\"COPILOT_STUDIO_APP_ID\", \"\"),\n                     app_password=os.environ.get(\"COPILOT_STUDIO_APP_PASSWORD\", \"\"))\n\n# To run this agent locally:\n# 1. Save this code as `app.py`.\n# 2. Ensure `uvicorn` is installed (`pip install uvicorn`).\n# 3. From your terminal, execute: `uvicorn app:app --host 0.0.0.0 --port 3978`\n# This will start a web server for your agent, accessible at http://localhost:3978","lang":"python","description":"This quickstart demonstrates how to define a basic agent with message handlers using the `Agent` decorator and how to host it locally using `AgentExtension` and `uvicorn`. The `APP_ID` and `APP_PASSWORD` are crucial for Copilot Studio to authenticate and connect to your deployed agent."},"warnings":[{"fix":"Pin your dependency to a specific minor version and thoroughly test when upgrading, reviewing the official documentation for migration guides.","message":"As a pre-1.0 library (0.x.x), the API surface is subject to frequent breaking changes without major version bumps. Always consult the latest GitHub README or changelog for specific version changes.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Understand that you are building the 'backend' for a Copilot Studio agent, not a consumer of one. The `AgentExtension` class integrates with web frameworks to expose your agent logic as an HTTP endpoint.","message":"This library is designed for *implementing* agent extensions that are hosted by Copilot Studio, not for *making requests to* Copilot Studio agents as a client. Its usage pattern involves defining handlers for incoming messages and activities, typically exposed via a webhook.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `COPILOT_STUDIO_APP_ID` and `COPILOT_STUDIO_APP_PASSWORD` environment variables are set correctly (or provided directly) when deploying. These credentials establish trust between your agent endpoint and Copilot Studio.","message":"Authentication for your agent extension requires `APP_ID` and `APP_PASSWORD`. These must be correctly configured in your Copilot Studio agent settings and passed to the `AgentExtension` to enable Copilot Studio to securely invoke your agent.","severity":"gotcha","affected_versions":"All"},{"fix":"Refer to the official Microsoft Copilot Studio documentation for detailed deployment and connection instructions for custom agent extensions.","message":"Deploying and connecting your agent extension to Copilot Studio involves configuration steps outside this library, including setting up the public endpoint URL for your hosted agent and linking it within the Copilot Studio portal.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}