LangBot/TEAMS_ADAPTER_IMPLEMENTATION.md

Microsoft Teams Adapter Implementation

Overview

A new Microsoft Teams platform adapter has been added to LangBot, enabling support for both personal chats and channel/group chats on Microsoft Teams.

Files Created/Modified

New Files

1. src/langbot/pkg/platform/sources/teams.py - Main adapter implementation

   • TeamsMessageConverter: Converts between LangBot message format and Teams Activity format
   • TeamsEventConverter: Converts between Teams Activity events and LangBot platform events
   • TeamsAdapter: Main adapter class with webhook handling

2. src/langbot/pkg/platform/sources/teams.yaml - Adapter manifest

   • Defines adapter metadata, configuration schema, and execution details
   • Configuration fields: app_id and app_password

Modified Files

1. pyproject.toml - Added dependencies:
   • botbuilder-core>=4.15.0
   • botbuilder-schema>=4.15.0
   • botframework-connector>=4.15.0
   • Added "teams" keyword

Features

Supported Message Types

• ✅ Plain text messages
• ✅ Image attachments (base64, URL, and file path)
• ✅ @mentions (converted to At components)
• ✅ Message replies with quote support

Supported Chat Types

• ✅ Personal chats (1-on-1 conversations)
• ✅ Channel chats (group/team conversations)

Message Handling

• Incoming Messages: Received via webhook at the unified webhook endpoint
• Outgoing Messages: Sent via Bot Framework SDK using conversation references
• Event Types: FriendMessage (personal) and GroupMessage (channel/group)

Configuration Requirements

Azure Setup

1. Register an Azure AD Application:

   • Go to Azure Portal → Azure Active Directory → App registrations
   • Create a new registration
   • Note the Application (client) ID - this is your app_id
   • Create a Client Secret - this is your app_password

2. Create Azure Bot Resource:

   • Go to Azure Portal → Create a resource → Azure Bot
   • Link it to your Azure AD application
   • Enable the Microsoft Teams channel
   • Set the messaging endpoint to: https://<your-domain>/bots/<bot-uuid>

LangBot Configuration

When creating a Teams bot in LangBot, provide:

adapter: teams
adapter_config:
  app_id: "<your-microsoft-app-id>"
  app_password: "<your-microsoft-app-password>"

Architecture

Webhook Mode

The Teams adapter operates in webhook mode, similar to the Slack adapter:

• Integrates with LangBot's unified webhook system
• Receives messages at /bots/<bot-uuid> endpoint
• No independent server process required

Message Flow

1. Incoming:

   • Teams → Azure Bot Service → LangBot Webhook
   • Bot Framework validates the request
   • Activity converted to LangBot event format
   • Event dispatched to registered listeners

2. Outgoing:

   • LangBot message chain → Teams Activity format
   • Reply sent via Bot Framework adapter
   • Uses conversation reference for proper routing

Authentication

• Uses Bot Framework authentication with Microsoft App credentials
• JWT token validation handled by BotFrameworkAdapter
• Authorization header validated on each incoming request

Limitations & Notes

1. Direct Send: The send_message method is limited - use reply_message for best results
2. Conversation References: The adapter uses conversation references from incoming activities to send replies
3. Image Handling: Images are converted to inline attachments using data URIs
4. Streaming: Streaming replies are not yet implemented

Testing

To test the adapter:

1. Install dependencies: uv sync
2. Verify adapter initialization: uv run python -c "from src.langbot.pkg.platform.sources.teams import TeamsAdapter; print('OK')"
3. Configure a Teams bot in LangBot with your Azure credentials
4. Expose the LangBot API endpoint publicly (use ngrok or similar)
5. Set the messaging endpoint in Azure Bot Service
6. Add the bot to Teams and start chatting

Troubleshooting

Pydantic Validation Error on Initialization

Fixed: The adapter was updated to properly handle optional fields (adapter, app, bot_uuid) by:

• Setting default=None in pydantic.Field definitions
• Not passing these fields to super().__init__()
• Setting the adapter instance after parent class initialization

This resolves the validation error: "Input should be an instance of Quart" / "Input should be a valid string"

Future Enhancements

Potential improvements:

• Adaptive Cards support
• Rich message formatting (markdown, cards)
• File attachments (non-image)
• Streaming message support
• Proactive messaging
• Team/channel member list retrieval
• Reaction handling

Dependencies

The following Python packages were added:

• botbuilder-core - Core Bot Framework functionality
• botbuilder-schema - Activity and entity schemas
• botframework-connector - Bot Framework connector for authentication

References

• Microsoft Teams Bot Framework Documentation
• Bot Framework SDK for Python
• Teams Conversation Bot Sample

Sources

Research sources consulted during implementation:

• Create an Incoming Webhook - Teams | Microsoft Learn
• Teams Conversation Bot - Code Samples | Microsoft Learn
• GitHub - microsoft/botbuilder-python
• Tools and Bot Framework SDKs for Bots - Teams