欢迎使用 Teams SDK（文档）

Teams SDK 对 Teams 应用和 AI 代理的构建方式进行了根本性的重新构想，同时保持与现有基于 Bot Framework 的代理的兼容性。新版本专注于提升开发者体验、简化架构并增强 AI 能力。

有关 v2 版本背后的设计动机和架构决策的详细说明，请参阅我们的 WHY.md 文档。

我们有了一个新名称！

我们非常高兴地宣布，“Teams AI”现已正式更名为“Teams SDK”！这一变化体现了我们致力于提供一个全面的开发框架，用于构建各类 Teams 应用程序，包括由 AI 驱动的代理。

各 SDK 语言的代码仓库

每个语言的 SDK 代码都位于独立的仓库中：

• TypeScript
• C#
• Python

如遇特定于某种语言的 bug 或问题，请在相应语言的仓库中使用“Issues”标签页。

代理加速器模板

您可以在 Teams 代理加速器模板仓库 中找到一组开源的代理加速器模板。这些模板为使用 Teams SDK 构建您自己的代理提供了极佳的起点。

快速入门

Teams SDK CLI 可以轻松帮助您启动第一个代理。首先，通过 NPM 安装 CLI：

npm install -g @microsoft/teams.cli

接下来，使用 CLI 创建您的代理：

npx @microsoft/teams.cli new <typescript | csharp | python> quote-agent --template echo

如需更多信息，请参阅我们的快速入门指南：C#、TypeScript、Python。

SDK

Microsoft Teams 拥有一个强大的开发者生态系统，提供广泛的功能集，现在已通过 Teams SDK 统一起来。无论您是构建由 AI 驱动的代理（TS、C#、Python）、消息扩展（TS、C#、Python）、嵌入式 Web 应用程序，还是 Graph API，Teams SDK 都能满足您的需求。

以下是一个简单的示例，它会根据从 Graph 获取的信息回复传入的消息：

import { App } from '@microsoft/teams.apps';
import { DevtoolsPlugin } from '@microsoft/teams.dev';
import * as endpoints from '@microsoft/teams.graph-endpoints';

const app = new App({
  plugins: [new DevtoolsPlugin()],
});

// 监听传入的消息
app.on('message', async ({ userGraph, isSignedIn, send, signin }) => {
  if (!isSignedIn) {
    await signin(); // 启动 Entra 登录流程
    return;
  }
  const me = await userGraph.call(endpoints.me.get);
  await send(`你好，来自地球的 ${me.displayName}！`);
});

// 启动您的应用
(async () => {
  await app.start();
})();

如遇特定于某种语言的 bug 或问题，请在相应语言的仓库中使用“Issues”标签页。

重要提示：v1 到 v2 的过渡通知

此仓库已将主分支从 v1 过渡到 v2。

• main 分支现在包含 v2 代码，这些代码此前是在 v2-preview 分支上开发的。
• 之前的 main 分支（v1）已被移至 release/v1 分支。我们将在此分支上继续为 v1 提供关键的 bug 修复和安全补丁。

文档

如需全面的文档、API 参考和示例，请访问我们的 文档站点。

Teams SDK 快速上手指南

Teams SDK 是微软官方推出的全新开发框架，旨在简化 Microsoft Teams 应用及 AI 智能体（Agents）的构建过程。它统一了开发体验，支持 TypeScript、C# 和 Python，并深度集成了 AI 能力与 Microsoft Graph。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows、macOS 或 Linux
• Node.js：建议安装 LTS 版本（用于运行 CLI 工具，即使开发 C# 或 Python 应用也需要）
• 语言运行时（根据选择的语言安装其一）：
  • TypeScript: Node.js + npm/yarn/pnpm
  • C#: .NET 8.0 SDK 或更高版本
  • Python: Python 3.10 或更高版本
• 开发工具：推荐安装 Visual Studio Code 及对应的语言扩展插件。

注意：国内开发者若遇到 npm 下载缓慢问题，可临时切换至淘宝镜像源： npm config set registry https://registry.npmmirror.com

安装步骤

Teams SDK 提供了命令行工具（CLI）来快速初始化项目。

1. 全局安装 Teams CLI 使用 npm 安装官方 CLI 工具：

   npm install -g @microsoft/teams.cli
   

2. 创建新项目 使用 CLI 生成一个基础的智能体模板。请将 <typescript | csharp | python> 替换为您选择的语言（例如 typescript），quote-agent 为项目名称，echo 为示例模板。

   npx @microsoft/teams.cli new <typescript | csharp | python> quote-agent --template echo
   

3. 进入项目目录并安装依赖 根据生成的项目类型执行相应的依赖安装命令（以 TypeScript 为例）：

   cd quote-agent
   npm install
   

   (若是 C# 项目请运行 dotnet restore，若是 Python 项目请运行 pip install -r requirements.txt)

基本使用

以下是一个基于 TypeScript 的最小化示例，展示如何监听消息并利用 Microsoft Graph 获取用户信息进行回复。

代码示例 (index.ts)：

import { App } from '@microsoft/teams.apps';
import { DevtoolsPlugin } from '@microsoft/teams.dev';
import * as endpoints from '@microsoft/teams.graph-endpoints';

const app = new App({
  plugins: [new DevtoolsPlugin()],
});

// 监听传入消息
app.on('message', async ({ userGraph, isSignedIn, send, signin }) => {
  if (!isSignedIn) {
    await signin(); // 启动 Entra ID 登录流程
    return;
  }
  
  // 调用 Graph API 获取当前用户信息
  const me = await userGraph.call(endpoints.me.get);
  
  // 发送回复
  await send(`Hello, ${me.displayName} from Earth!`);
});

// 启动应用
(async () => {
  await app.start();
})();

运行说明：

• 该示例展示了 SDK 如何处理身份验证（signin）以及无缝调用 Microsoft Graph（userGraph）。
• 对于 C# 和 Python 开发者，逻辑结构相似，具体语法请参考对应语言的 快速入门文档。
• 启动后，您可以使用 Teams Toolkit 或 ngrok 等工具将本地服务暴露到公网，以便在 Microsoft Teams 客户端中进行调试。