
关于
Microsoft 365 Agents SDK(TypeScript/Node.js 版本)
name: m365-agents-ts description: Microsoft 365 Agents SDK,适用于 TypeScript/Node.js。 risk: unknown source: community date_added: '2026-02-27'
Microsoft 365 Agents SDK (TypeScript)
使用 Microsoft 365 Agents SDK 构建企业级代理,适用于 Microsoft 365、Teams 和 Copilot Studio,支持 Express 托管、AgentApplication 路由、流式响应以及 Copilot Studio 客户端集成。
实施前准备
- 使用 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 Activity 处理
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")!);
最佳实践
- 使用 AgentApplication 进行路由,保持处理程序专注于单一职责。
- 对长时间运行的补全优先使用 streamingResponse,并在 finally 块中调用 endStream。
- 将密钥保存在源代码之外;从环境变量或安全存储中加载 token。
- 复用 CopilotStudioClient 实例,并在 token provider 中缓存 token。
- 在处理之前验证 invoke 负载。
兼容工具
Claude CodeCursor
标签
后端开发
