m365-agents-ts
Microsoft 365 Agents SDK for TypeScript/Node.js.
Documentation
Microsoft 365 Agents SDK (TypeScript)
Build enterprise agents for Microsoft 365, Teams, and Copilot Studio using the Microsoft 365 Agents SDK with Express hosting, AgentApplication routing, streaming responses, and Copilot Studio client integrations.
Before implementation
- Use the microsoft-docs MCP to verify the latest API signatures for AgentApplication, startServer, and CopilotStudioClient.
- Confirm package versions on npm before wiring up samples or templates.
Installation
npm install @microsoft/agents-hosting @microsoft/agents-hosting-express @microsoft/agents-activity
npm install @microsoft/agents-copilotstudio-client
Environment Variables
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>
Core Workflow: Express-hosted 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);
Streaming responses with 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 handling
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 client (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 integration
import { CopilotStudioWebChat } from "@microsoft/agents-copilotstudio-client";
const directLine = CopilotStudioWebChat.createConnection(client, {
showTyping: true,
});
window.WebChat.renderWebChat({
directLine,
}, document.getElementById("webchat")!);
Best Practices
- Use AgentApplication for routing and keep handlers focused on one responsibility.
- Prefer streamingResponse for long-running completions and call endStream in finally blocks.
- Keep secrets out of source code; load tokens from environment variables or secure stores.
- Reuse CopilotStudioClient instances and cache tokens in your token provider.
- Validate invoke payloads before logging or persisting feedback.
Reference Files
| File | Contents |
|---|---|
| references/acceptance-criteria.md | Import paths, hosting p |
Quick Info
- Source
- antigravity
- Category
- AI & Agents
- Repository
- View Repo
- Scraped At
- Feb 26, 2026
Tags
Related Skills
acceptance-orchestrator
Use when a coding task should be driven end-to-end from issue intake through implementation, review, deployment, and acceptance verification with minimal human re-intervention.
accessibility-compliance-accessibility-audit
You are an accessibility expert specializing in WCAG compliance, inclusive design, and assistive technology compatibility. Conduct audits, identify barriers, and provide remediation guidance.
accesslint-diff
Diff a live page's accessibility violations against a baseline — by default compares uncommitted changes (stash-based), or pass --branch [<name>] to diff against a branch. Reports only new violations introduced, violations fixed, and pre-existing count. Use `scan` for a full audit with no diffing.