Microsoft Agents Activity Protocol Library

0.8.0 · active · verified Tue Apr 14

The `microsoft-agents-activity` library is a fundamental component of the Microsoft 365 Agents SDK for Python. It provides the core types and schemas, implementing the Activity Protocol Specification, which standardizes communication between AI agents, users, and various channels such as Microsoft Teams, M365 Copilot, Copilot Studio, and web chat. This protocol handles diverse interaction types including messages, typing indicators, conversation updates, events, invokes, and end-of-conversation signals. The SDK aims to facilitate the creation of robust, multichannel, and trusted agents for enterprise systems, allowing developers to integrate agents regardless of their underlying provider or technology stack. The current version of this specific library is 0.8.0.

Warnings

gotcha The `microsoft-agents-activity` library defines the protocol (types and schemas) for interactions, but it does not provide agent hosting or core logic. To build a runnable AI agent, you must use additional packages from the Microsoft 365 Agents SDK, such as `microsoft-agents-hosting-aiohttp` for web hosting and `microsoft_agents.hosting.core.AgentApplication` for agent logic.
Fix: Ensure you install and configure a hosting package (e.g., `microsoft-agents-hosting-aiohttp`) and implement your agent logic using `AgentApplication` or similar classes from the broader SDK.
gotcha The `microsoft-agents-hosting` SDK (which works with `microsoft-agents-activity` objects) does not fully support the `updateActivity` pattern commonly found in Bot Framework. Attempts to use `context.updateActivity()` will likely fail with a `TypeError: activity.applyConversationReference is not a function`.
Fix: As a workaround, instead of updating an existing activity (e.g., a 'thinking...' message), send a new activity (e.g., delete the 'thinking' message and send the final response). Monitor official documentation and GitHub issues for future support.
breaking The broader Microsoft Agent Framework, of which `microsoft-agents-activity` is a part, has announced a v1.0 release as of April 2, 2026. Additionally, the Agent registry and Agent collections blades in the Entra admin center are being retired on May 1, 2026, with Agent 365 becoming the unified registry. The existing registry Graph API will be deprecated and replaced.
Fix: While `microsoft-agents-activity` is still at 0.8.0, anticipate potential breaking changes in future minor or major releases to align with the framework's 1.0 status. For agent management, review `Agent 365` documentation for re-registration procedures if you are using the deprecated Entra admin center features.
gotcha Some advanced features and quickstarts related to the Microsoft 365 Agents SDK (e.g., specific Agent 365 capabilities) might require participation in the 'Frontier preview program'. This means not all documented features may be immediately available or stable for general production use.
Fix: Check the prerequisites for any advanced features you plan to use and verify access to preview programs if necessary.

Install

pip install microsoft-agents-activity Install latest version

Imports

Activity

from microsoft_agents.activity import Activity

ActivityTypes

from microsoft_agents.activity import ActivityTypes

Quickstart

This quickstart demonstrates how to create and manipulate `Activity` objects, the core data structure handled by the `microsoft-agents-activity` library. It simulates an incoming message and then shows how to generate a reply activity using built-in methods, showcasing the protocol's core functionality.

import asyncio
from microsoft_agents.activity import Activity, ActivityTypes
import os

async def main():
    # Simulate an incoming message activity (e.g., from a user in Teams)
    incoming_activity = Activity.from_object({
        "type": ActivityTypes.Message,
        "id": "msg123",
        "timestamp": "2026-04-14T18:00:00Z",
        "channelId": os.environ.get('TEST_CHANNEL_ID', 'test_channel'),
        "from": {"id": "user123", "name": "Test User"},
        "conversation": {"id": "conv123", "conversationType": "personal"},
        "recipient": {"id": "bot456", "name": "Test Bot"},
        "text": "Hello bot, how are you?",
        "locale": "en-US"
    })

    print(f"Incoming Activity Text: {incoming_activity.text}")
    print(f"Incoming Activity Sender: {incoming_activity.from_property.name}")

    # Create a reply activity using the incoming activity's context
    reply_activity = incoming_activity.create_reply("Hello there, Test User! I'm doing well, thanks for asking.")

    print(f"\nReply Activity Type: {reply_activity.type}")
    print(f"Reply Activity Text: {reply_activity.text}")
    print(f"Reply Activity Recipient: {reply_activity.recipient.name}")
    print(f"Reply Activity To ID: {reply_activity.reply_to_id}")

if __name__ == "__main__":
    # Example of setting an environment variable for demonstration
    os.environ['TEST_CHANNEL_ID'] = 'mock_channel_001'
    asyncio.run(main())

view raw JSON →