Load with: base.md
Purpose: Build AI-powered agents and apps for Microsoft Teams. Create conversational bots, message extensions, and intelligent assistants that integrate with LLMs like OpenAI and Claude.
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐
│ TEAMS APP TYPES │
│ ───────────────────────────────────────────────────────────── │
│ │
│ 1. AI AGENTS (Bots) │
│ Conversational apps powered by LLMs │
│ Handle messages, commands, and actions │
│ │
│ 2. MESSAGE EXTENSIONS │
│ Search external systems, insert cards into messages │
│ Action commands with modal dialogs │
│ │
│ 3. TABS │
│ Embedded web applications inside Teams │
│ Personal, channel, or meeting tabs │
│ │
│ 4. WEBHOOKS & CONNECTORS │
│ Incoming: Post messages to channels │
│ Outgoing: Respond to @mentions │
├─────────────────────────────────────────────────────────────────┤
│ SDK LANDSCAPE (2025) │
│ ───────────────────────────────────────────────────────────── │
│ Teams SDK v2: Primary SDK for Teams-only apps │
│ M365 Agents SDK: Multi-channel (Teams, Outlook, Copilot) │
│ Teams Toolkit: VS Code extension for development │
└─────────────────────────────────────────────────────────────────┘
Quick Start
Install Teams CLI
npm install -g @microsoft/teams.cli
Create New Project
# TypeScript (Recommended)
npx @microsoft/teams.cli new typescript my-agent --template echo
# Python
npx @microsoft/teams.cli new python my-agent --template echo
# C#
npx @microsoft/teams.cli new csharp my-agent --template echo
Project Structure
my-agent/
├── src/
│ ├── index.ts # Entry point
│ ├── app.ts # App configuration
│ └── handlers/
│ ├── message.ts # Message handlers
│ └── commands.ts # Command handlers
├── appPackage/
│ ├── manifest.json # App manifest
│ ├── color.png # App icon (192x192)
│ └── outline.png # Outline icon (32x32)
├── .env # Environment variables
├── teamsapp.yml # Teams Toolkit config
└── package.json
App Manifest
Basic Manifest Structure
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
"manifestVersion": "1.17",
"version": "1.0.0",
"id": "{{APP_ID}}",
"developer": {
"name": "Your Company",
"websiteUrl": "https://yourcompany.com",
"privacyUrl": "https://yourcompany.com/privacy",
"termsOfUseUrl": "https://yourcompany.com/terms"
},
"name": {
"short": "AI Assistant",
"full": "AI Assistant for Teams"
},
"description": {
"short": "Your AI-powered assistant",
"full": "An intelligent assistant that helps you with tasks using AI."
},
"icons": {
"color": "color.png",
"outline": "outline.png"
},
"accentColor": "#5558AF",
"bots": [
{
"botId": "{{BOT_ID}}",
"scopes": ["personal", "team", "groupChat"],
"supportsFiles": false,
"isNotificationOnly": false,
"commandLists": [
{
"scopes": ["personal", "team", "groupChat"],
"commands": [
{
"title": "help",
"description": "Show available commands"
},
{
"title": "ask",
"description": "Ask the AI a question"
}
]
}
]
}
],
"permissions": ["identity", "messageTeamMembers"],
"validDomains": ["*.azurewebsites.net"]
}
Manifest with Message Extensions
{
"composeExtensions": [
{
"botId": "{{BOT_ID}}",
"commands": [
{
"id": "searchQuery",
"type": "query",
"title": "Search",
"description": "Search for information",
"initialRun": true,
"parameters": [
{
"name": "query",
"title": "Search query",
"description": "Enter your search terms",
"inputType": "text"
}
]
},
{
"id": "createTask",
"type": "action",
"title": "Create Task",
"description": "Create a new task",
"fetchTask": true,
"context": ["compose", "commandBox", "message"]
}
]
}
]
}
AI Agent Development
Basic Bot with Teams SDK v2
// src/app.ts
import { App, HttpPlugin, DevtoolsPlugin } from '@microsoft/teams.ai';
import { OpenAIModel, ActionPlanner, PromptManager } from '@microsoft/teams.ai';
// Configure the AI model
const model = new OpenAIModel({
azureApiKey: process.env.AZURE_OPENAI_API_KEY!,
azureDefaultDeployment: process.env.AZURE_OPENAI_DEPLOYMENT!,
azureEndpoint: process.env.AZURE_OPENAI_ENDPOINT!,
// Or use OpenAI directly:
// apiKey: process.env.OPENAI_API_KEY!,
// defaultModel: 'gpt-4'
});
// Configure prompts
const prompts = new PromptManager({
promptsFolder: './src/prompts'
});
// Create action planner
const planner = new ActionPlanner({
model,
prompts,
defaultPrompt: 'chat'
});
// Create the app
const app = new App({
plugins: [
new HttpPlugin(),
new DevtoolsPlugin()
],
ai: {
planner
}
});
// Handle messages
app.on('message', async (context, state) => {
// AI automatically handles the conversation
// The planner uses the 'chat' prompt to generate responses
});
// Handle specific commands
app.message('/help', async (context, state) => {
await context.sendActivity({
type: 'message',
text: 'Available commands:\n- /help - Show this message\n- /ask [question] - Ask me anything'
});
});
// Start the app
app.start();
Prompt Configuration
# src/prompts/chat/config.json
{
"schema": 1.1,
"description": "AI Assistant for Teams",
"type": "completion",
"completion": {
"model": "gpt-4",
"max_tokens": 1000,
"temperature": 0.7,
"top_p": 1
}
}
# src/prompts/chat/skprompt.txt
You are an AI assistant for Microsoft Teams. You help users with their questions and tasks.
Current conversation:
{{$history}}
User: {{$input}}
Assistant:
Integrating Claude/Anthropic
Claude-Powered Teams Bot
// src/claude-bot.ts
import { App, HttpPlugin } from '@microsoft/teams.ai';
import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY!
});
const app = new App({
plugins: [new HttpPlugin()]
});
// Conversation history store
const conversations = new Map<string, Anthropic.MessageParam[]>();
app.on('message', async (context, state) => {
const userId = context.activity.from.id;
const userMessage = context.activity.text;
// Get or initialize conversation history
if (!conversations.has(userId)) {
conversations.set(userId, []);
}
const history = conversations.get(userId)!;
// Add user message to history
history.push({ role: 'user', content: userMessage });
// Show typing indicator
await context.sendActivity({ type: 'typing' });
try {
// Call Claude API
const response = await anthropic.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
system: `You are an AI assistant integrated into Microsoft Teams.
Help users with their questions and tasks.
Be concise and helpful. Use markdown formatting when appropriate.
Current user: ${context.activity.from.name}`,
messages: history
});
const assistantMessage = response.content[0].type === 'text'
? response.content[0].text
: '';
// Add assistant response to history
history.push({ role: 'assistant', content: assistantMessage });
// Keep history manageable (last 20 messages)
if (history.length > 20) {
history.splice(0, history.length - 20);
}
// Send response
await context.sendActivity({
type: 'message',
text: assistantMessage
});
} catch (error) {
console.error('Claude API error:', error);
await context.sendActivity({
type: 'message',
text: 'Sorry, I encountered an error processing your request.'
});
}
});
// Clear conversation command
app.message('/clear', async (context, state) => {
const userId = context.activity.from.id;
conversations.delete(userId);
await context.sendActivity('Conversation cleared. Starting fresh!');
});
app.start();
Claude with Tools/Function Calling
// src/claude-agent.ts
import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic();
// Define tools the agent can use
const tools: Anthropic.Tool[] = [
{
name: 'search_knowledge_base',
description: 'Search the company knowledge base for information',
input_schema: {
type: 'object' as const,
properties: {
query: {
type: 'string',
description: 'The search query'
}
},
required: ['query']
}
},
{
name: 'create_task',
description: 'Create a new task in the task management system',
input_schema: {
type: 'object' as const,
properties: {
title: { type: 'string', description: 'Task title' },
description: { type: 'string', description: 'Task description' },
assignee: { type: 'string', description: 'Person to assign the task to' },
due_date: { type: 'string', description: 'Due date in YYYY-MM-DD format' }
},
required: ['title']
}
},
{
name: 'get_calendar',
description: 'Get calendar events for a user',
input_schema: {
type: 'object' as const,
properties: {
user: { type: 'string', description: 'User email or name' },
days: { type: 'number', description: 'Number of days to look ahead' }
},
required: ['user']
}
}
];
// Tool implementations
async function executeTools(toolName: string, toolInput: any): Promise<string> {
switch (toolName) {
case 'search_knowledge_base':
// Implement your search logic
return `Found 3 results for "${toolInput.query}":\n1. Document A\n2. Document B\n3. Document C`;
case 'create_task':
// Implement task creation (e.g., call Microsoft Graph API)
return `Task created: "${toolInput.title}"`;
case 'get_calendar':
// Implement calendar lookup
return `Calendar for ${toolInput.user}: 2 meetings today`;
default:
return 'Unknown tool';
}
}
// Agent loop with tool use
async function runAgent(userMessage: string): Promise<string> {
let messages: Anthropic.MessageParam[] = [
{ role: 'user', content: userMessage }
];
while (true) {
const response = await anthropic.messages.create({
model: 'claude-sonnet-4-20250514',
max_tokens: 1024,
system: 'You are a helpful Teams assistant. Use tools when needed to help users.',
tools,
messages
});
// Check if we need to use tools
if (response.stop_reason === 'tool_use') {
const toolResults: Anthropic.MessageParam[] = [];
for (const content of response.content) {
if (content.type === 'tool_use') {
const result = await executeTools(content.name, content.input);
toolResults.push({
role: 'user',
content: [{
type: 'tool_result',
tool_use_id: content.id,
content: result
}]
});
}
}
messages.push({ role: 'assistant', content: response.content });
messages.push(...toolResults);
continue;
}
// Return final text response
const textContent = response.content.find(c => c.type === 'text');
return textContent?.text || 'No response';
}
}
Adaptive Cards
Basic Adaptive Card
// src/cards/welcome-card.ts
import { CardFactory } from 'botbuilder';
export function createWelcomeCard(userName: string) {
return CardFactory.adaptiveCard({
type: 'AdaptiveCard',
$schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
version: '1.5',
body: [
{
type: 'TextBlock',
text: `Welcome, ${userName}!`,
size: 'Large',
weight: 'Bolder'
},
{
type: 'TextBlock',
text: 'I\'m your AI assistant. How can I help you today?',
wrap: true
},
{
type: 'ActionSet',
actions: [
{
type: 'Action.Submit',
title: 'Get Started',
data: { action: 'getStarted' }
},
{
type: 'Action.Submit',
title: 'View Help',
data: { action: 'help' }
}
]
}
]
});
}
AI Response Card with Actions
// src/cards/ai-response-card.ts
export function createAIResponseCard(
question: string,
answer: string,
sources?: string[]
) {
return {
type: 'AdaptiveCard',
$schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
version: '1.5',
body: [
{
type: 'Container',
style: 'emphasis',
items: [
{
type: 'TextBlock',
text: 'Your Question',
size: 'Small',
weight: 'Bolder'
},
{
type: 'TextBlock',
text: question,
wrap: true
}
]
},
{
type: 'Container',
items: [
{
type: 'TextBlock',
text: 'AI Response',
size: 'Small',
weight: 'Bolder'
},
{
type: 'TextBlock',
text: answer,
wrap: true
}
]
},
...(sources && sources.length > 0 ? [{
type: 'Container',
items: [
{
type: 'TextBlock',
text: 'Sources',
size: 'Small',
weight: 'Bolder'
},
...sources.map(source => ({
type: 'TextBlock',
text: `• ${source}`,
size: 'Small'
}))
]
}] : [])
],
actions: [
{
type: 'Action.Submit',
title: '👍 Helpful',
data: { action: 'feedback', value: 'positive' }
},
{
type: 'Action.Submit',
title: '👎 Not Helpful',
data: { action: 'feedback', value: 'negative' }
},
{
type: 'Action.Submit',
title: 'Ask Follow-up',
data: { action: 'followUp' }
}
]
};
}
Form Card for User Input
// src/cards/task-form-card.ts
export function createTaskFormCard() {
return {
type: 'AdaptiveCard',
$schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
version: '1.5',
body: [
{
type: 'TextBlock',
text: 'Create New Task',
size: 'Large',
weight: 'Bolder'
},
{
type: 'Input.Text',
id: 'taskTitle',
label: 'Task Title',
isRequired: true,
placeholder: 'Enter task title'
},
{
type: 'Input.Text',
id: 'taskDescription',
label: 'Description',
isMultiline: true,
placeholder: 'Enter task description'
},
{
type: 'Input.ChoiceSet',
id: 'priority',
label: 'Priority',
choices: [
{ title: 'High', value: 'high' },
{ title: 'Medium', value: 'medium' },
{ title: 'Low', value: 'low' }
],
value: 'medium'
},
{
type: 'Input.Date',
id: 'dueDate',
label: 'Due Date'
}
],
actions: [
{
type: 'Action.Submit',
title: 'Create Task',
data: { action: 'createTask' }
},
{
type: 'Action.Submit',
title: 'Cancel',
data: { action: 'cancel' }
}
]
};
}
Microsoft Graph Integration
Setup Graph Client
// src/graph/client.ts
import { Client } from '@microsoft/microsoft-graph-client';
import { TokenCredentialAuthenticationProvider } from '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials';
import { ClientSecretCredential } from '@azure/identity';
export function createGraphClient() {
const credential = new ClientSecretCredential(
process.env.AZURE_TENANT_ID!,
process.env.AZURE_CLIENT_ID!,
process.env.AZURE_CLIENT_SECRET!
);
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
scopes: ['https://graph.microsoft.com/.default']
});
return Client.initWithMiddleware({ authProvider });
}
Common Graph Operations
// src/graph/operations.ts import <sp