microsoft-teams-graph 2.0.0

The Graph package for a Microsoft Teams agent

Microsoft Teams Graph Integration

This package provides seamless access to Microsoft Graph APIs from Teams bots and agents built with the Microsoft Teams SDK for Python.

Key Features

• Token Integration: Unified token handling using the Token type from microsoft-teams-common
• Flexible Token Sources: Supports strings, StringLike objects, callables, async callables, or None
• Automatic Token Resolution: Leverages common resolve_token utility for consistent handling

Requirements

• Teams SDK for Python
• Microsoft Graph SDK for Python (msgraph-sdk)
• Azure Core library (azure-core)
• Microsoft Teams Common library (microsoft-teams-common)

Quick Start

Basic Usage with Teams Bot

from microsoft_teams.graph import get_graph_client
from microsoft_teams.apps import App, ActivityContext
from microsoft_teams.api import MessageActivity

app = App()

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    if not ctx.is_signed_in:
        await ctx.sign_in()
        return

    # Create Graph client using user's token
    graph = get_graph_client(ctx.user_token)

    # Get user profile
    me = await graph.me.get()
    await ctx.send(f"Hello {me.display_name}!")

    # Get user's Teams
    teams = await graph.me.joined_teams.get()
    if teams and teams.value:
        team_names = [team.display_name for team in teams.value]
        await ctx.send(f"You're in {len(team_names)} teams: {', '.join(team_names)}")

Token Integration

from microsoft_teams.common.http.client_token import Token

def create_token_callable(ctx: ActivityContext) -> Token:
    """Create a callable token that refreshes automatically."""
    def get_fresh_token():
        # This is called on each Graph API request
        return ctx.user_token  # Always returns current valid token

    return get_fresh_token

# Use with Graph client
graph = get_graph_client(create_token_callable(ctx))

# Or, use the user token that's already available in the context
graph = get_graph_client(ctx.user_token)

Token Type Usage

The package uses the Token type from microsoft-teams-common for flexible token handling. You can provide tokens in several formats:

String Token (Simplest)

# Direct string token
graph = get_graph_client("eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...")

Callable Token (Dynamic)

def get_token():
    """Callable that returns a string token."""
    # Get your access token from wherever (Teams API, cache, etc.)
    return get_access_token_from_somewhere()

# Use the callable with get_graph_client
graph = get_graph_client(get_token)

Async Callable Token

async def get_token_async():
    """Async callable that returns a string token."""
    # Fetch token asynchronously
    token_response = await some_api_call()
    return token_response.access_token

graph = get_graph_client(get_token_async)

Dynamic Token Retrieval

def get_fresh_token():
    """Callable that fetches a fresh token on each invocation."""
    # This will be called each time the Graph client needs a token
    fresh_token = fetch_latest_token_from_api()
    return fresh_token

graph = get_graph_client(get_fresh_token)

Authentication

The package uses Token-based authentication with automatic resolution through the common library. Teams tokens are pre-authorized through the OAuth connection configured in your Azure Bot registration.

API Usage Examples

# Get user profile
me = await graph.me.get()

# Get recent emails with specific fields
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
    select=["subject", "from", "receivedDateTime"],
    top=5
)
request_config = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
    query_parameters=query_params
)
messages = await graph.me.messages.get(request_configuration=request_config)