
Description
Microsoft 365 Agents SDK for TypeScript/Node.js. Build multichannel agents for Teams/M365/Copilot Studio with AgentApplication routing, Express hosting, streaming responses, and Copilot Studio client integration. Triggers: "Microsoft 365 Agents SDK", "@microsoft/agents-hosting", "AgentApplication", "startServer", "streamingResponse", "Copilot Studio client", "@microsoft/agents-copilotstudio-client".
SKILL.md
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 Links
| Resource | URL |
|---|---|
| Microsoft 365 Agents SDK | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/ |
| JavaScript SDK overview | 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 |
| Integrate with Copilot Studio | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/integrate-with-mcs |
| GitHub samples | https://github.com/microsoft/Agents/tree/main/samples/nodejs |
More skills from the skills repository
View all 38 skillsazure-ai-agents-persistent-dotnet
build AI agents with Azure .NET SDK
Jul 3.NETAgentsAzureLLMazure-ai-anomalydetector-java
build anomaly detection applications with Java
May 13AnalyticsAzureData AnalysisJava +2azure-ai-contentsafety-java
build content moderation applications with Azure AI
Jul 7AI InfrastructureAzureJavaSecurityazure-ai-contentsafety-py
detect harmful content with Azure AI Content Safety
Jul 18AzureComplianceLLMMicrosoft +2azure-ai-language-conversations-py
implement conversational language understanding with Python
Jul 31AnalyticsAzureLLMPythonazure-ai-translation-text-py
translate text using Azure AI services
Jul 18API DevelopmentAzureMicrosoftPython
More from Microsoft
View publisherrushstack-best-practices
manage Rush monorepos with best practices
rushstack
Apr 6EngineeringLocal DevelopmentMicrosoftProject Management +1azure-ai-vision-imageanalysis-py
analyze images with Azure AI Vision
skills
Jul 18AzureComputer VisionImagesPythonazure-appconfiguration-java
manage configuration with Azure App Configuration
skills
Jul 3AzureConfigurationFeature FlagsJavaazure-cosmos-rust
build applications with Azure Cosmos DB
skills
Jul 31Cosmos DBDatabaseNoSQLRustazure-cosmos-ts
build applications with Azure Cosmos DB
skills
Jul 3Cosmos DBDatabaseMicrosoftNoSQL +1azure-data-tables-java
build table storage applications with Java
skills
May 13AzureCosmos DBDatabaseJava +1