m365-agents-ts

支持材料可用性

此目录副本包含以下内联指南，但不包含下列支持路径。这些是外部前置条件，并非随附文件：

• <support-root>/references/acceptance-criteria.md

使用依赖这些路径的步骤前，请索取原始支持材料或现有安装；此目录未提供经过验证的下载来源。请相对于该安装解析每个路径，检查其内容，并核实适用的许可证和执行前置条件。所需文件不存在时，请勿运行命令，也不要声称已遵循所引用的流程。请勿编造缺失的脚本，也不要将名称相同但无关的文件视为等效文件。此处完整记录的独立步骤可在用户授权范围内继续；请将任何依赖步骤报告为不可用。

Microsoft 365 Agents SDK（TypeScript）

使用 Microsoft 365 Agents SDK、Express 托管、AgentApplication 路由、流式响应和 Copilot Studio 客户端集成，为 Microsoft 365、Teams 和 Copilot Studio 构建企业级 Agent。

实现前

• 使用 microsoft-docs MCP 验证 AgentApplication、startServer 和 CopilotStudioClient 的最新 API 签名。
• 在接入示例或模板前，确认 npm 上的包版本。

安装

npm install @microsoft/agents-hosting @microsoft/agents-hosting-express @microsoft/agents-activity
npm install @microsoft/agents-copilotstudio-client

环境变量

PORT=3978
AZURE_RESOURCE_NAME=<azure-openai-resource>
AZURE_API_KEY=<azure-openai-key>
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o-mini

TENANT_ID=<tenant-id>
CLIENT_ID=<client-id>
CLIENT_SECRET=<client-secret>

COPILOT_ENVIRONMENT_ID=<environment-id>
COPILOT_SCHEMA_NAME=<schema-name>
COPILOT_CLIENT_ID=<copilot-app-client-id>
COPILOT_BEARER_TOKEN=<copilot-jwt>

核心工作流：Express 托管的 AgentApplication

import { AgentApplication, TurnContext, TurnState } from "@microsoft/agents-hosting";
import { startServer } from "@microsoft/agents-hosting-express";

const agent = new AgentApplication<TurnState>();

agent.onConversationUpdate("membersAdded", async (context: TurnContext) => {
  await context.sendActivity("Welcome to the agent.");
});

agent.onMessage("hello", async (context: TurnContext) => {
  await context.sendActivity(`Echo: ${context.activity.text}`);
});

startServer(agent);

使用 Azure OpenAI 的流式响应

import { azure } from "@ai-sdk/azure";
import { AgentApplication, TurnContext, TurnState } from "@microsoft/agents-hosting";
import { startServer } from "@microsoft/agents-hosting-express";
import { streamText } from "ai";

const agent = new AgentApplication<TurnState>();

agent.onMessage("poem", async (context: TurnContext) => {
  context.streamingResponse.setFeedbackLoop(true);
  context.streamingResponse.setGeneratedByAILabel(true);
  context.streamingResponse.setSensitivityLabel({
    type: "https://schema.org/Message",
    "@type": "CreativeWork",
    name: "Internal",
  });

  await context.streamingResponse.queueInformativeUpdate("starting a poem...");

  const { fullStream } = streamText({
    model: azure(process.env.AZURE_OPENAI_DEPLOYMENT_NAME || "gpt-4o-mini"),
    system: "You are a creative assistant.",
    prompt: "Write a poem about Apollo.",
  });

  try {
    for await (const part of fullStream) {
      if (part.type === "text-delta" && part.text.length > 0) {
        await context.streamingResponse.queueTextChunk(part.text);
      }
      if (part.type === "error") {
        throw new Error(`Streaming error: ${part.error}`);
      }
    }
  } finally {
    await context.streamingResponse.endStream();
  }
});

startServer(agent);

Invoke 活动处理

import { Activity, ActivityTypes } from "@microsoft/agents-activity";
import { AgentApplication, TurnContext, TurnState } from "@microsoft/agents-hosting";

const agent = new AgentApplication<TurnState>();

agent.onActivity("invoke", async (context: TurnContext) => {
  const invokeResponse = Activity.fromObject({
    type: ActivityTypes.InvokeResponse,
    value: { status: 200 },
  });

  await context.sendActivity(invokeResponse);
  await context.sendActivity("Thanks for submitting your feedback.");
});

Copilot Studio 客户端（Direct to Engine）

import { CopilotStudioClient } from "@microsoft/agents-copilotstudio-client";

const settings = {
  environmentId: process.env.COPILOT_ENVIRONMENT_ID!,
  schemaName: process.env.COPILOT_SCHEMA_NAME!,
  clientId: process.env.COPILOT_CLIENT_ID!,
};

const tokenProvider = async (): Promise<string> => {
  return process.env.COPILOT_BEARER_TOKEN!;
};

const client = new CopilotStudioClient(settings, tokenProvider);

const conversation = await client.startConversationAsync();
const reply = await client.askQuestionAsync("Hello!", conversation.id);
console.log(reply);

Copilot Studio WebChat 集成

import { CopilotStudioWebChat } from "@microsoft/agents-copilotstudio-client";

const directLine = CopilotStudioWebChat.createConnection(client, {
  showTyping: true,
});

window.WebChat.renderWebChat({
  directLine,
}, document.getElementById("webchat")!);

最佳实践

1. 使用 AgentApplication 进行路由，并确保每个处理程序只负责一项职责。
2. 对于长时间运行的补全，优先使用 streamingResponse，并在 finally 块中调用 endStream。
3. 不要将密钥写入源代码；请从环境变量或安全存储中加载令牌。
4. 复用 CopilotStudioClient 实例，并在令牌提供程序中缓存令牌。
5. 在记录或持久化反馈前，验证 invoke 负载。

参考文件

文件	内容
references/acceptance-criteria.md	导入路径、托管管道、流式处理和 Copilot Studio 模式

参考链接

资源	URL
Microsoft 365 Agents SDK	https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/
JavaScript SDK 概述	https://learn.microsoft.com/en-us/javascript/api/overview/agents-overview?view=agents-sdk-js-latest
@microsoft/agents-hosting-express	https://learn.microsoft.com/en-us/javascript/api/%40microsoft/agents-hosting-express?view=agents-sdk-js-latest
@microsoft/agents-copilotstudio-client	https://learn.microsoft.com/en-us/javascript/api/%40microsoft/agents-copilotstudio-client?view=agents-sdk-js-latest
与 Copilot Studio 集成	https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/integrate-with-mcs
GitHub 示例	https://github.com/microsoft/Agents/tree/main/samples/nodejs

适用场景

当需要执行概述中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。