M365 Agents Py

1---
2name: m365-agents-py
3description: |
4  Microsoft 365 Agents SDK for Python. Build multichannel agents for Teams/M365/Copilot Studio with aiohttp hosting, AgentApplication routing, streaming responses, and MSAL-based auth. Triggers: "Microsoft 365 Agents SDK", "microsoft_agents", "AgentApplication", "start_agent_process", "TurnContext", "Copilot Studio client", "CloudAdapter".
5package: microsoft-agents-hosting-core, microsoft-agents-hosting-aiohttp, microsoft-agents-activity, microsoft-agents-authentication-msal, microsoft-agents-copilotstudio-client
6---
7 
8# Microsoft 365 Agents SDK (Python)
9 
10Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft Agents SDK with aiohttp hosting, AgentApplication routing, streaming responses, and MSAL-based authentication.
11 
12## Before implementation
13- Use the microsoft-docs MCP to verify the latest API signatures for AgentApplication, start_agent_process, and authentication options.
14- Confirm package versions on PyPI for the microsoft-agents-* packages you plan to use.
15 
16## Important Notice - Import Changes
17 
18> **⚠️ Breaking Change**: Recent updates have changed the Python import structure from `microsoft.agents` to `microsoft_agents` (using underscores instead of dots).
19 
20## Installation
21 
22```bash
23pip install microsoft-agents-hosting-core
24pip install microsoft-agents-hosting-aiohttp
25pip install microsoft-agents-activity
26pip install microsoft-agents-authentication-msal
27pip install microsoft-agents-copilotstudio-client
28pip install python-dotenv aiohttp
29```
30 
31## Environment Variables (.env)
32 
33```bash
34CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<client-id>
35CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<client-secret>
36CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<tenant-id>
37 
38# Optional: OAuth handlers for auto sign-in
39AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__GRAPH__SETTINGS__AZUREBOTOAUTHCONNECTIONNAME=<connection-name>
40 
41# Optional: Azure OpenAI for streaming
42AZURE_OPENAI_ENDPOINT=<endpoint>
43AZURE_OPENAI_API_VERSION=<version>
44AZURE_OPENAI_API_KEY=<key>
45 
46# Optional: Copilot Studio client
47COPILOTSTUDIOAGENT__ENVIRONMENTID=<environment-id>
48COPILOTSTUDIOAGENT__SCHEMANAME=<schema-name>
49COPILOTSTUDIOAGENT__TENANTID=<tenant-id>
50COPILOTSTUDIOAGENT__AGENTAPPID=<app-id>
51```
52 
53## Core Workflow: aiohttp-hosted AgentApplication
54 
55```python
56import logging
57from os import environ
58 
59from dotenv import load_dotenv
60from aiohttp.web import Request, Response, Application, run_app
61 
62from microsoft_agents.activity import load_configuration_from_env
63from microsoft_agents.hosting.core import (
64    Authorization,
65    AgentApplication,
66    TurnState,
67    TurnContext,
68    MemoryStorage,
69)
70from microsoft_agents.hosting.aiohttp import (
71    CloudAdapter,
72    start_agent_process,
73    jwt_authorization_middleware,
74)
75from microsoft_agents.authentication.msal import MsalConnectionManager
76 
77# Enable logging
78ms_agents_logger = logging.getLogger("microsoft_agents")
79ms_agents_logger.addHandler(logging.StreamHandler())
80ms_agents_logger.setLevel(logging.INFO)
81 
82# Load configuration
83load_dotenv()
84agents_sdk_config = load_configuration_from_env(environ)
85 
86# Create storage and connection manager
87STORAGE = MemoryStorage()
88CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
89ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
90AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)
91 
92# Create AgentApplication
93AGENT_APP = AgentApplication[TurnState](
94    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
95)
96 
97 
98@AGENT_APP.conversation_update("membersAdded")
99async def on_members_added(context: TurnContext, _state: TurnState):
100    await context.send_activity("Welcome to the agent!")
101 
102 
103@AGENT_APP.activity("message")
104async def on_message(context: TurnContext, _state: TurnState):
105    await context.send_activity(f"You said: {context.activity.text}")
106 
107 
108@AGENT_APP.error
109async def on_error(context: TurnContext, error: Exception):
110    await context.send_activity("The agent encountered an error.")
111 
112 
113# Server setup
114async def entry_point(req: Request) -> Response:
115    agent: AgentApplication = req.app["agent_app"]
116    adapter: CloudAdapter = req.app["adapter"]
117    return await start_agent_process(req, agent, adapter)
118 
119 
120APP = Application(middlewares=[jwt_authorization_middleware])
121APP.router.add_post("/api/messages", entry_point)
122APP["agent_configuration"] = CONNECTION_MANAGER.get_default_connection_configuration()
123APP["agent_app"] = AGENT_APP
124APP["adapter"] = AGENT_APP.adapter
125 
126if __name__ == "__main__":
127    run_app(APP, host="localhost", port=environ.get("PORT", 3978))
128```
129 
130## AgentApplication Routing
131 
132```python
133import re
134from microsoft_agents.hosting.core import (
135    AgentApplication, TurnState, TurnContext, MessageFactory
136)
137from microsoft_agents.activity import ActivityTypes
138 
139AGENT_APP = AgentApplication[TurnState](
140    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
141)
142 
143# Welcome handler
144@AGENT_APP.conversation_update("membersAdded")
145async def on_members_added(context: TurnContext, _state: TurnState):
146    await context.send_activity("Welcome!")
147 
148# Regex-based message handler
149@AGENT_APP.message(re.compile(r"^hello$", re.IGNORECASE))
150async def on_hello(context: TurnContext, _state: TurnState):
151    await context.send_activity("Hello!")
152 
153# Simple string message handler
154@AGENT_APP.message("/status")
155async def on_status(context: TurnContext, _state: TurnState):
156    await context.send_activity("Status: OK")
157 
158# Auth-protected message handler
159@AGENT_APP.message("/me", auth_handlers=["GRAPH"])
160async def on_profile(context: TurnContext, state: TurnState):
161    token_response = await AGENT_APP.auth.get_token(context, "GRAPH")
162    if token_response and token_response.token:
163        # Use token to call Graph API
164        await context.send_activity("Profile retrieved")
165 
166# Invoke activity handler
167@AGENT_APP.activity(ActivityTypes.invoke)
168async def on_invoke(context: TurnContext, _state: TurnState):
169    invoke_response = Activity(
170        type=ActivityTypes.invoke_response, value={"status": 200}
171    )
172    await context.send_activity(invoke_response)
173 
174# Fallback message handler
175@AGENT_APP.activity("message")
176async def on_message(context: TurnContext, _state: TurnState):
177    await context.send_activity(f"Echo: {context.activity.text}")
178 
179# Error handler
180@AGENT_APP.error
181async def on_error(context: TurnContext, error: Exception):
182    await context.send_activity("An error occurred.")
183```
184 
185## Streaming Responses with Azure OpenAI
186 
187```python
188from openai import AsyncAzureOpenAI
189from microsoft_agents.activity import SensitivityUsageInfo
190 
191CLIENT = AsyncAzureOpenAI(
192    api_version=environ["AZURE_OPENAI_API_VERSION"],
193    azure_endpoint=environ["AZURE_OPENAI_ENDPOINT"],
194    api_key=environ["AZURE_OPENAI_API_KEY"]
195)
196 
197@AGENT_APP.message("poem")
198async def on_poem_message(context: TurnContext, _state: TurnState):
199    # Configure streaming response
200    context.streaming_response.set_feedback_loop(True)
201    context.streaming_response.set_generated_by_ai_label(True)
202    context.streaming_response.set_sensitivity_label(
203        SensitivityUsageInfo(
204            type="https://schema.org/Message",
205            schema_type="CreativeWork",
206            name="Internal",
207        )
208    )
209    context.streaming_response.queue_informative_update("Starting a poem...\n")
210 
211    # Stream from Azure OpenAI
212    streamed_response = await CLIENT.chat.completions.create(
213        model="gpt-4o",
214        messages=[
215            {"role": "system", "content": "You are a creative assistant."},
216            {"role": "user", "content": "Write a poem about Python."}
217        ],
218        stream=True,
219    )
220    
221    try:
222        async for chunk in streamed_response:
223            if chunk.choices and chunk.choices[0].delta.content:
224                context.streaming_response.queue_text_chunk(
225                    chunk.choices[0].delta.content
226                )
227    finally:
228        await context.streaming_response.end_stream()
229```
230 
231## OAuth / Auto Sign-In
232 
233```python
234@AGENT_APP.message("/logout")
235async def logout(context: TurnContext, state: TurnState):
236    await AGENT_APP.auth.sign_out(context, "GRAPH")
237    await context.send_activity(MessageFactory.text("You have been logged out."))
238 
239 
240@AGENT_APP.message("/me", auth_handlers=["GRAPH"])
241async def profile_request(context: TurnContext, state: TurnState):
242    user_token_response = await AGENT_APP.auth.get_token(context, "GRAPH")
243    if user_token_response and user_token_response.token:
244        # Use token to call Microsoft Graph
245        async with aiohttp.ClientSession() as session:
246            headers = {
247                "Authorization": f"Bearer {user_token_response.token}",
248                "Content-Type": "application/json",
249            }
250            async with session.get(
251                "https://graph.microsoft.com/v1.0/me", headers=headers
252            ) as response:
253                if response.status == 200:
254                    user_info = await response.json()
255                    await context.send_activity(f"Hello, {user_info['displayName']}!")
256```
257 
258## Copilot Studio Client (Direct to Engine)
259 
260```python
261import asyncio
262from msal import PublicClientApplication
263from microsoft_agents.activity import ActivityTypes, load_configuration_from_env
264from microsoft_agents.copilotstudio.client import (
265    ConnectionSettings,
266    CopilotClient,
267)
268 
269# Token cache (local file for interactive flows)
270class LocalTokenCache:
271    # See samples for full implementation
272    pass
273 
274def acquire_token(settings, app_client_id, tenant_id):
275    pca = PublicClientApplication(
276        client_id=app_client_id,
277        authority=f"https://login.microsoftonline.com/{tenant_id}",
278    )
279    
280    token_request = {"scopes": ["https://api.powerplatform.com/.default"]}
281    accounts = pca.get_accounts()
282    
283    if accounts:
284        response = pca.acquire_token_silent(token_request["scopes"], account=accounts[0])
285        return response.get("access_token")
286    else:
287        response = pca.acquire_token_interactive(**token_request)
288        return response.get("access_token")
289 
290 
291async def main():
292    settings = ConnectionSettings(
293        environment_id=environ.get("COPILOTSTUDIOAGENT__ENVIRONMENTID"),
294        agent_identifier=environ.get("COPILOTSTUDIOAGENT__SCHEMANAME"),
295    )
296    
297    token = acquire_token(
298        settings,
299        app_client_id=environ.get("COPILOTSTUDIOAGENT__AGENTAPPID"),
300        tenant_id=environ.get("COPILOTSTUDIOAGENT__TENANTID"),
301    )
302    
303    copilot_client = CopilotClient(settings, token)
304    
305    # Start conversation
306    act = copilot_client.start_conversation(True)
307    async for action in act:
308        if action.text:
309            print(action.text)
310    
311    # Ask question
312    replies = copilot_client.ask_question("Hello!", action.conversation.id)
313    async for reply in replies:
314        if reply.type == ActivityTypes.message:
315            print(reply.text)
316 
317 
318asyncio.run(main())
319```
320 
321## Best Practices
322 
3231. Use `microsoft_agents` import prefix (underscores, not dots).
3242. Use `MemoryStorage` only for development; use BlobStorage or CosmosDB in production.
3253. Always use `load_configuration_from_env(environ)` to load SDK configuration.
3264. Include `jwt_authorization_middleware` in aiohttp Application middlewares.
3275. Use `MsalConnectionManager` for MSAL-based authentication.
3286. Call `end_stream()` in finally blocks when using streaming responses.
3297. Use `auth_handlers` parameter on message decorators for OAuth-protected routes.
3308. Keep secrets in environment variables, not in source code.
331 
332## Reference Files
333 
334| File | Contents |
335| --- | --- |
336| [references/acceptance-criteria.md](references/acceptance-criteria.md) | Import paths, hosting pipeline, streaming, OAuth, and Copilot Studio patterns |
337 
338## Reference Links
339 
340| Resource | URL |
341| --- | --- |
342| Microsoft 365 Agents SDK | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/ |
343| GitHub samples (Python) | https://github.com/microsoft/Agents-for-python |
344| PyPI packages | https://pypi.org/search/?q=microsoft-agents |
345| Integrate with Copilot Studio | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/integrate-with-mcs |
346