Microsoft Agents Copilot Studio Client

0.8.0 · active · verified Wed Apr 15

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.

Warnings

breaking 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.
Fix: Pin your dependency to a specific minor version and thoroughly test when upgrading, reviewing the official documentation for migration guides.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
Fix: Refer to the official Microsoft Copilot Studio documentation for detailed deployment and connection instructions for custom agent extensions.

Install

pip install microsoft-agents-copilotstudio-client uvicorn Install library and a web server

Imports

Agent

from microsoft.copilotstudio.agents import Agent

AgentExtension

from microsoft.copilotstudio.agents.extension import AgentExtension

AgentActivity

from microsoft.copilotstudio.agents.models import AgentActivity

UserMessage

from microsoft.copilotstudio.agents.models import UserMessage

TurnContext

from microsoft.copilotstudio.agents.turn_context import TurnContext

Quickstart

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.

import os
from microsoft.copilotstudio.agents import Agent
from microsoft.copilotstudio.agents.extension import AgentExtension
from microsoft.copilotstudio.agents.models import AgentActivity, UserMessage
from microsoft.copilotstudio.agents.turn_context import TurnContext

# Define your agent
agent = Agent()

# Define an initial message handler
@agent.on_message("initial_message")
async def initial_message_handler(turn_context: TurnContext):
    user_message = turn_context.activity.value
    if user_message and isinstance(user_message, UserMessage):
        print(f"Received initial message: {user_message.text}")
        await turn_context.send_activity(
            AgentActivity(value="Hello! I'm your Copilot Studio Agent.")
        )
    else:
        print("Received activity is not a UserMessage for initial_message.")

# Define a follow-up message handler
@agent.on_message("follow_up_message")
async def follow_up_message_handler(turn_context: TurnContext):
    user_message = turn_context.activity.value
    if user_message and isinstance(user_message, UserMessage):
        print(f"Received follow-up message: {user_message.text}")
        await turn_context.send_activity(
            AgentActivity(value=f"You said: '{user_message.text}'. How can I help further?")
        )
    else:
        print("Received activity is not a UserMessage for follow_up_message.")

# Create the AgentExtension application
# APP_ID and APP_PASSWORD are required for Copilot Studio to authenticate and connect.
# For local testing, you might leave them empty, but they are critical for deployment.
app = AgentExtension(agent, app_id=os.environ.get("COPILOT_STUDIO_APP_ID", ""),
                     app_password=os.environ.get("COPILOT_STUDIO_APP_PASSWORD", ""))

# To run this agent locally:
# 1. Save this code as `app.py`.
# 2. Ensure `uvicorn` is installed (`pip install uvicorn`).
# 3. From your terminal, execute: `uvicorn app:app --host 0.0.0.0 --port 3978`
# This will start a web server for your agent, accessible at http://localhost:3978

view raw JSON →