Hotdry.

Article

企业级 AI 助手入口设计：Teams 自定义 Agent 集成与对话流编排工程实践

深度解析微软 Teams 平台的 BYO Agent 集成方案，提供企业级 AI 助手的入口配置参数、对话流编排与可落地的工程实现细节。

2026-04-23ai-systems

在企业协作场景中，将自研 AI 助手接入 Microsoft Teams 已成为构建统一工作入口的关键路径。微软 Teams SDK 提供的 HTTP Server Adapter 模式，使得企业无需重构现有 Agent 逻辑即可实现平滑接入。本文从工程实践角度，系统阐述企业级 AI 助手在 Teams 平台上的入口设计、对话流编排与关键配置参数。

一、入口架构：HTTP Server Adapter 模式解析

Teams SDK 的核心设计理念是「你的服务器始终归你所有」，通过适配器模式在现有 HTTP 服务器与 Teams 消息通道之间建立桥梁。该模式的工程价值在于：企业可以保留现有的 LangChain 链、Azure Foundry 部署或自研 Agent 服务，仅需添加 Teams 消息端点即可完成集成。

技术实现的三步核心流程如下。首先，使用 ExpressAdapter（或 FastAPIAdapter）包装现有 Express/FastAPI 服务器实例，使 Teams SDK 获得请求路由能力。其次，创建 TeamsApp 实例并挂载到适配器上，注册消息处理句柄。最后，调用 initialize 方法将 POST /api/messages 端点注入现有服务器，该端点正是 Teams 平台向 Bot 投递消息的标准化入口。

import { App as TeamsApp, ExpressAdapter } from '@microsoft/teams.apps';

const expressApp = express();                              // 现有服务器
const adapter = new ExpressAdapter(expressApp);            // 包装服务器
const teamsApp = new TeamsApp({ httpServerAdapter: adapter }); // 创建应用

teamsApp.on('message', async ({ send, activity }) => {
  await send(`收到消息: ${activity.text}`);
});

await teamsApp.initialize();  // 注册 /api/messages 端点

从企业集成视角看，这种架构的优势在于：现有 Agent 逻辑完全独立于 Teams 集成层，两者通过标准化的消息格式进行解耦通信。这意味着同一套 Agent 逻辑可以同时服务于 Slack、Discord 或其他平台，仅需为每个平台添加对应的适配器层。

二、入口配置关键参数

企业级部署需要关注以下核心配置参数，这些参数直接影响 Agent 的可用性、安全性与用户体验。

2.1 服务器暴露与隧道配置

Teams 要求 Bot 服务必须通过 HTTPS 公开访问。在开发阶段，推荐使用 Azure Dev Tunnels 替代传统的 ngrok，因为前者与 VS Code 和 Azure CLI 深度集成，可通过以下命令创建持久化隧道：

# 创建开发隧道，端口 3978 为 Teams SDK 默认监听端口
az devtunnel service create --peer-addr 3978
az devtunnel host create --peer-addr 3978

生成的公网 URL 格式为 https://abc123.devtunnels.ms，该 URL 将作为 Bot 的消息接收端点。生产环境则需要配置正式的 HTTPS 端点，推荐使用 Azure App Service 或 Azure Kubernetes Service 并配置自定义域名。

2.2 应用注册与认证配置

通过 Teams SDK CLI 完成 Azure AD 应用注册是首个关键步骤：

npm install -g @microsoft/teams.cli@preview
teams login
teams app create --name "Enterprise Assistant" \
  --endpoint https://your-tunnel-url/api/messages \
  --env .env

此命令自动完成以下操作：创建 Azure AD 应用注册、生成客户端密钥、生成 Bot 应用 ID、创建 Teams 应用清单。生成的 .env 文件包含 CLIENT_ID、CLIENT_SECRET 和 TENANT_ID 三个核心凭证，生产部署时需将其安全存储在 Azure Key Vault 中。

2.3 消息端点验证

Teams 平台对每个 inbound 请求进行签名验证，确保消息确实来自 Microsoft 服务器。Teams SDK 的适配器自动处理此验证逻辑，但企业需要在服务器启动时确保正确加载环境变量。对于高并发场景，建议配置请求超时参数：

const adapter = new ExpressAdapter(expressApp, {
  verifySignature: true,
  requestTimeout: 30000,  // 消息处理超时 30 秒
  enableCompression: true
});

三、对话流编排工程实践

3.1 消息处理管道设计

在企业级场景中，对话流编排需要处理多种消息类型与复杂交互逻辑。推荐采用分层架构：将消息接收、意图识别、Agent 调用、响应组装分别置于不同层次。

teamsApp.on('message', async ({ send, activity }) => {
  // 第一层：立即响应，避免超时
  await send({ type: 'typing' });
  
  // 第二层：提取用户意图（可替换为自研 NLU 组件）
  const intent = await classifyIntent(activity.text || '');
  
  // 第三层：路由到对应的 Agent 或处理逻辑
  const response = await routeToAgent(intent, activity.text);
  
  // 第四层：响应组装与发送
  await send(formatResponse(response));
});

3.2 与 LangChain 链的集成模式

对于已采用 LangChain 构建的企业，集成过程仅需在消息处理层调用现有 Chain 实例：

import { getChain } from './chain';

teamsApp.on('message', async ({ send, activity }) => {
  await send({ type: 'typing' });
  
  const chain = getChain();
  const result = await chain.invoke({ 
    input: activity.text || '',
    context: {
      platform: 'teams',
      userId: activity.from.id,
      channelId: activity.conversation.id
    }
  });
  
  await send(result);
});

关键工程考量点包括：Chain 实例应采用单例模式避免重复初始化；建议为 Teams 用户添加系统提示词变体以适应协作场景的简洁性要求；流式响应可通过 send 方法的分块发送实现。

3.3 Azure Foundry Agent 中继模式

对于部署在 Azure AI Foundry 的企业自研 Agent，Teams SDK 充当消息代理角色：

import { AIProjectClient } from '@azure/ai-projects';
import { DefaultAzureCredential } from '@azure/identity';

const client = AIProjectClient.fromEndpoint(
  process.env.AZURE_AI_FOUNDRY_ENDPOINT!,
  new DefaultAzureCredential()
);

teamsApp.on('message', async ({ send, activity }) => {
  const thread = await client.agents.threads.create();
  await client.agents.messages.create(thread.id, 'user', activity.text || '');
  
  const run = await client.agents.runs.createAndPoll(
    thread.id,
    process.env.AZURE_AGENT_ID!,
    { timeout: 60000 }
  );
  
  if (run.status === 'completed') {
    const messages = await client.agents.messages.list(thread.id);
    const assistantMsg = messages.find(m => m.role === 'assistant');
    await send(assistantMsg?.content[0]?.text?.value || '处理完成');
  }
});

此模式的核心优势在于：企业 Agent 无需任何修改即可接入 Teams，Foundry 负责模型推理和状态管理，Teams SDK 仅负责消息路由。

3.4 多平台共存架构

企业通常需要同时支持 Slack 与 Teams 两个平台。Teams SDK 与 Slack Bolt 框架可以共存于同一 Express 服务器：

// 共享的业务逻辑提取为独立函数
import { processUserMessage } from './business-logic';

// Slack 端
const slackApp = new BoltApp({ /* config */ });
slackApp.message('hello', async ({ say }) => {
  const result = await processUserMessage('hello');
  await say(result);
});

// Teams 端
const teamsApp = new TeamsApp({ httpServerAdapter: adapter });
teamsApp.on('message', async ({ send, activity }) => {
  const result = await processUserMessage(activity.text || '');
  await send(result);
});

这种架构避免了代码重复，业务逻辑统一维护在 processUserMessage 函数中，两个平台的差异仅体现在消息格式转换层。

四、生产部署关键检查清单

企业在将 Agent 投入生产环境前，应确认以下配置已就绪。

身份验证层面，需验证 Azure AD 应用注册的 redirect URI 配置正确，且拥有调用 Microsoft Graph API 的适当权限范围。若 Agent 需要读取用户日历或邮件，建议配置 delegated 权限而非 application 权限以遵循最小权限原则。

监控告警层面，需为消息端点配置应用洞察（Application Insights）跟踪，重点监控指标包括：消息接收延迟（目标 < 500ms）、Agent 响应时间（目标 < 5s）、错误率（目标 < 0.1%）。建议为 teamsApp.on('message') 处理器添加统一的异常捕获逻辑。

弹性设计层面，需实现消息处理的幂等性设计，因为 Teams 平台可能因网络重试而投递重复消息。建议在业务逻辑层添加消息去重机制，基于 activity.id 进行判断。

多租户支持层面，若企业希望将 Agent 供多个租户使用，需要在应用清单中声明 staticTabs 或配置按需安装流程，并妥善管理租户级别的数据隔离。

五、技术选型建议

根据企业现有技术栈与集成需求，推荐以下技术选型路径。

若企业仅需支持 Teams 一个平台，且希望完全控制 Bot 行为，推荐使用 Teams SDK 直接构建。该方案提供最完整的 Teams 原生能力，包括 Adaptive Cards、会议集成、主动消息推送等特性。

若企业需要在 Teams、Microsoft 365 Copilot、自定义 Web 应用等多个渠道部署同一 Agent，推荐使用 Microsoft 365 Agents SDK。该 SDK 提供跨渠道的统一抽象层，一次开发即可覆盖多个出口。

若企业已在 Microsoft Foundry 中部署 Agent，推荐使用 Foundry + Teams SDK 的中继模式。该方案对现有 Foundry 部署零侵入，仅需部署轻量级的消息路由服务。

若企业偏好低代码方案且需求相对简单，可选择 Copilot Studio 进行配置式集成，但其定制灵活性受限。

资料来源

ai-systems