What Is the Microsoft 365 Agents SDK?
The Microsoft 365 Agents SDK is the part of an agent that nobody sees: it takes a message from Microsoft Teams, Microsoft 365 Copilot, a website or Slack, hands it to your code, and carries your answer back. This page explains what it does, what it leaves to you, what it costs to run, and where this course teaches each of its capabilities in C#.
What the Agents SDK Does
Microsoft describes the Agents SDK as a development framework for building conversational agents: software that receives a message, works out an answer and replies. It's the plumbing between a person typing in Teams or Copilot and the code you wrote to answer them.
It solves three problems you'd otherwise solve yourself:
- Your agent has to work in more than one place. People talk to agents in Microsoft Teams, Microsoft 365 Copilot, a company website, Slack and more, and every one of those has its own message format, sign-in rules and connection protocol. The SDK turns every incoming message into one common shape, so you write your agent's logic once and add channels without rewriting it.
- You don't want to be locked into one AI service. The SDK is AI-agnostic. It receives messages, keeps state and routes events, but it never decides what the agent says. You plug in Microsoft Foundry, Azure OpenAI, Microsoft Agent Framework or plain code of your own, and you can swap them later.
- Conversations need memory. A person asks a follow-up question, or comes back tomorrow. The SDK tracks state per conversation and per user between messages, so you don't build your own persistence layer for it.
It's available for C# (.NET), JavaScript (Node.js) and Python. This course uses C# on .NET 10, the current long-term support release of .NET.
What It Isn't
The Agents SDK isn't an AI model, it isn't an orchestration engine, and it isn't a no-code builder. In Microsoft's words, the Agents SDK doesn't decide what an agent says. Whatever answers the question — a call to a large language model, an Agent Framework agent with tools, a database lookup or a simple if statement — is your code. The SDK's job is to get messages to that code and the answers back, reliably, on every channel, with the conversation's state intact.
That's why the first agent in this course doesn't use AI at all: Building an Echo Agent in C# answers with whatever you typed, and every piece of the SDK is already there. The weather agent then puts an AI model behind the same plumbing.
How a Message Travels
Every message, button click or "someone joined the chat" event arrives as an activity: a JSON document in the Activity Protocol, the format Teams, Copilot, Copilot Studio and the SDK all share. When one arrives, the SDK does three things:
- Receives it at your agent's web endpoint,
POST /api/messages, and, once you turn authentication on, checks that it really came from the channel. - Routes it to the handler you registered for that kind of activity: one handler for messages, another for people joining, another for card buttons.
- Sends your reply back through the channel that sent the message. Normally your agent doesn't answer in the HTTP response: it posts the reply to the channel's own service address, which the activity tells it.
In C#, the class that receives and routes activities is AgentApplication. A complete agent that greets people and repeats what they type is about twenty lines:
public class MyAgent : AgentApplication
{
public MyAgent(AgentApplicationOptions options) : base(options)
{
OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync);
OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
}
private async Task WelcomeMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
foreach (ChannelAccount member in turnContext.Activity.MembersAdded)
{
if (member.Id != turnContext.Activity.Recipient.Id)
{
await turnContext.SendActivityAsync(MessageFactory.Text("Hello and Welcome!"), cancellationToken);
}
}
}
private async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
await turnContext.SendActivityAsync($"You said: {turnContext.Activity.Text}", cancellationToken: cancellationToken);
}
}
One incoming activity and everything your agent does in response is called a turn. ITurnContext is that turn: the activity that arrived, and the methods that send replies. ITurnState holds the conversation's and the user's saved state. Both appear in every handler you'll write.
Which Microsoft Tool Should You Use?
Microsoft has several products with "agent" in the name, and they solve different problems. This is how they fit together:
| Product | What it is | Use it when |
|---|---|---|
| Microsoft 365 Agents SDK | A framework that connects your code to channels and keeps conversation state | You write the agent in code and want it in Teams, Microsoft 365 Copilot, a website, Slack or several of them at once |
| Teams SDK | Microsoft's SDK for agents and apps built specifically for Microsoft Teams | Your agent lives only in Teams and works with people there; Microsoft points Teams-only collaborative agents to it |
| Microsoft Copilot Studio | A low-code, hosted agent builder | You'd rather build and host an agent without writing a service; your code can still call it, and it can call yours |
| Declarative agents | Agents that run on Microsoft 365 Copilot's own model and orchestrator, described in a manifest | Copilot's model and knowledge are enough and you add instructions, knowledge and actions; no hosting |
| Microsoft Agent Framework | A framework for the agent's brain: models, tools, memory and workflows | You need the AI part; it runs inside an Agents SDK agent, and the weather agent uses it |
| Microsoft Agent 365 SDK | Adds enterprise identity, governed Microsoft 365 tools and notifications to an agent you already have | Your organization manages agents with Agent 365; Microsoft says it doesn't build agents and works alongside the Agents SDK |
| Bot Framework SDK | The Agents SDK's predecessor | Not for new work: it's archived and support ended on December 31, 2025 (what happened) |
An agent you build with the Agents SDK and use in Microsoft 365 Copilot is called a custom engine agent: it brings its own engine, meaning its own model and orchestration, and you host it. A declarative agent uses Copilot's engine and needs no hosting. Microsoft's own comparison puts it plainly: custom engine agents require additional hosting outside of Microsoft 365, at your cost, and in return you control the model, the tools and the data.
Channels Your Agent Can Reach
A channel is the place where people talk to your agent. You register your agent once and switch channels on; your code doesn't change per channel, except where a channel can't show something.
| Channel | What people use | What it costs on Azure Bot Service |
|---|---|---|
| Microsoft Teams | Personal chats, group chats, channels and meetings | Free: a standard channel, unlimited messages on the free F0 tier |
| Microsoft 365 Copilot | Copilot Chat, as a custom engine agent | Not listed on the Azure Bot Service pricing page; see the note below the table |
| Web Chat and Direct Line | A chat window on your own website, or your own app | A premium channel: up to 10,000 messages a month on the free F0 tier; $0.50 per 1,000 messages on the S1 tier |
| Slack | Your Slack workspace | Free: a standard channel |
Microsoft 365 Copilot needs a closer look, because the rules depend on licences. Microsoft's extensibility documentation lists custom engine agents as available in Copilot Chat for people without a Microsoft 365 Copilot licence (usage limits apply), and Microsoft's admin documentation lists agent messages on pay-as-you-go billing at $0.01 each. The Microsoft 365 Copilot APIs that an agent can call, such as the Retrieval API, are different: they need a Microsoft 365 Copilot licence for each user. This course tests what actually works without a Copilot licence when it brings an agent to Copilot.
Some things don't work the same everywhere. Microsoft 365 Copilot, for example, requires streaming responses, has limited Adaptive Card support and doesn't show typing indicators; Teams supports nearly everything. The SDK tells your code which channel a message came from, so you can adapt.
How Your Agent Gets an Identity
Before Teams or Copilot will talk to your agent, the agent needs a registration with Microsoft's Agent Communication Service, the service agents use to talk to Teams. There are two kinds:
| Registration | Where you create it | Needs an Azure subscription | Sign-in (SSO, OAuth) |
|---|---|---|---|
| Teams-managed | The Teams Developer Portal, or a toolkit | No | Not supported |
| Azure-managed | An Azure Bot resource in Azure | Yes | Fully supported |
Microsoft recommends starting with a Teams-managed registration and moving to an Azure-managed one when your agent needs to sign people in. Either way, the agent's identity is a Microsoft Entra ID app registration, and the agent proves who it is with one of these:
- a client secret, which is the simplest;
- a certificate (a secret or a certificate is what you use while you test through a tunnel on your own machine);
- a federated identity credential backed by a user-assigned managed identity, which means no secret exists at all once the agent runs in Azure.
Whether people in other organizations can install your agent depends on the app registration's supported account types, not on the bot resource: Microsoft now creates every new bot with the Single Tenant bot type and says that type fully supports agents operating in multiple tenants. Creating new multi-tenant bot types ended on July 31, 2025.
The Packages
In C#, the SDK is a set of NuGet packages that share one version number. This course uses 1.9.205, the newest generally available release.
| Package | What it gives you |
|---|---|
Microsoft.Agents.Hosting.AspNetCore | Hosts your agent in ASP.NET Core: the /api/messages endpoint and request checks. Installing it also installs Builder, Core, Connector, Authentication and Storage |
Microsoft.Agents.Builder | AgentApplication, routing, turn state, streaming responses, proactive messages and user sign-in |
Microsoft.Agents.Core | The Activity Protocol: activities, cards, attachments and channel names |
Microsoft.Agents.Authentication.Msal | Lets your agent prove its identity with a secret, a certificate or a managed identity |
Microsoft.Agents.Storage, .Storage.Blobs, .Storage.CosmosDb | Where state is kept: in memory, in Azure Blob Storage or in Azure Cosmos DB |
Microsoft.Agents.Extensions.MSTeams | Teams features: message extensions, dialogs, meetings, files and more |
Microsoft.Agents.CopilotStudio.Client | Calls a Copilot Studio agent from your code |
Microsoft.Agents.Client | Lets one agent talk to another over the Activity Protocol |
Microsoft.Agents.M365Copilot (1.11.0) | The Microsoft 365 Copilot APIs, such as Retrieval |
Two more exist only as previews: Microsoft.Agents.Extensions.A2A.Preview, for the Agent2Agent (A2A) protocol, and the Slack extension Microsoft.Agents.Extensions.Slack, whose own sample calls it a preview. The older Microsoft.Agents.Extensions.Teams package is still published, but its main classes are marked obsolete in favor of Microsoft.Agents.Extensions.MSTeams.
Every Capability, and Where This Course Teaches It
This course covers the SDK capability by capability. The basics come first, each on a small example. Then four enterprise projects each add a group of capabilities to a real application, one part at a time, and finish deployed to Azure. Pages that aren't published yet are marked coming soon.
| Capability | What it does | Where you'll learn it |
|---|---|---|
| Hosting and your first agent | Run an agent in ASP.NET Core and talk to it locally | Building an Echo Agent in C# |
| AI with Microsoft Agent Framework | Answer with a model and tools, keylessly, with streaming | Building a Weather Forecast Agent in C# |
| Activities and the Activity Protocol | What every message looks like, per channel | Fundamentals, Part 1 (coming soon) |
Routing with AgentApplication | Messages, events, ranks, errors and middleware | Fundamentals, Part 2 (coming soon) |
| Conversation and user state | Remember things between messages | Fundamentals, Part 3 (coming soon) |
| Teams registration and dev tunnels | Run your local agent in real Teams | Fundamentals, Part 4 (coming soon) |
| Adaptive Cards and Universal Actions | Forms and approval cards that update for each person | Leave Requests & Approvals (coming soon) |
| Dialogs (task modules) | Pop-up forms in Teams | Leave Requests & Approvals (coming soon) |
| Proactive messages | Message people without them messaging first | Leave Requests & Approvals (coming soon) |
| Slash commands, suggested actions, targeted messages | Teams messaging features | Leave Requests & Approvals (coming soon) |
| Single sign-on and OAuth | Sign people in and call Microsoft Graph for them | Leave Requests & Approvals (coming soon) |
| Azure Cosmos DB storage | Keep state in a database, keylessly | Leave Requests & Approvals (coming soon) |
| Microsoft 365 Copilot channel | Use the agent in Copilot Chat | Leave Requests & Approvals (coming soon) |
| Lifecycle events and rosters | React to teams and channels; know who's there | Meeting Assistant (coming soon) |
| Meeting events | Meeting start and end; people joining and leaving | Meeting Assistant (coming soon) |
| Streaming, AI labels, citations, feedback | Trustworthy AI answers in Teams | Meeting Assistant (coming soon) |
| Files and file consent | Send and receive files | Meeting Assistant (coming soon) |
| Telemetry | Traces and metrics with OpenTelemetry | Meeting Assistant (coming soon) |
| Grounded answers in Copilot | Answer from company documents the person may read | Company Policy Agent (coming soon) |
| Message extensions and link previews | Search and share from any chat | Company Policy Agent (coming soon) |
| Web Chat and Direct Line | Put the agent on your own website | Customer Support Agent (coming soon) |
| Copilot Studio integration | Call a Copilot Studio agent, and be called by one | Customer Support Agent (coming soon) |
| Slack | Reach people in Slack | Customer Support Agent (coming soon) |
| Transcripts and agent-to-agent | Keep conversation records; let agents call each other | Customer Support Agent (coming soon) |
| Production readiness and deployment | Secure, observable agents in Azure | Every project's last part (coming soon) |
The Four Projects
Each project is a complete application that a business would actually use. Each one is built from an empty folder to a deployed agent, and each one is published to an organization's app catalog at the end:
- Leave Requests & Approvals — employees ask for time off in Teams, managers approve on a card that updates for everyone, and nobody chases anybody.
- Meeting Assistant — an agent that joins a team's meetings, keeps attendance, writes minutes and follows up on action items.
- Company Policy Agent — answers questions about company policies in Microsoft 365 Copilot and Teams, from documents the person is allowed to read, and shows its sources.
- Customer Support Agent — one agent on your website and in Slack that hands a conversation to a human in a Teams channel when it should.
What Building an Agent Costs
- On your own machine: nothing. The SDK, .NET, the Agents Playground and the Agents Toolkit are free, and an agent runs locally without Azure.
- AI models: you pay your model provider for the tokens your agent sends and receives.
- Azure Bot Service: the F0 tier is free, with unlimited messages on standard channels such as Teams and Slack and 10,000 messages a month on premium channels such as Web Chat.
- Hosting: when an agent leaves your machine, Azure App Service, Azure Container Apps and Azure Cosmos DB charge by size and use. Each project states its own costs before you create anything, and shows you how to delete it all afterwards.
- Microsoft 365 Copilot: see Channels Your Agent Can Reach.
Tools You'll Use
| Tool | What it's for |
|---|---|
| .NET 10 SDK | Builds and runs C# agents |
| Visual Studio Code or Visual Studio 2026 | Your editor; every step works in both |
| Microsoft 365 Agents Toolkit | Creates projects and registers, provisions and deploys agents; its command-line version can create C# projects, which its VS Code extension can't |
| Microsoft 365 Agents Playground | A chat window on your machine that talks to your local agent, no account needed |
| Dev tunnels | A public address for your local agent, so real Teams can reach it |
| Azure CLI | Signs your code in to Azure without keys, and manages resources |
The development environment pages set each of them up.
Frequently Asked Questions
Is the Microsoft 365 Agents SDK free?
Yes. The SDK is free and open source, and the Agents Toolkit and the Agents Playground are free to use. You pay for the services your agent uses: an AI model, Azure hosting once it leaves your machine, and premium channels beyond the free tier.
Do I need an Azure subscription to start?
No. You can build and test an agent on your own machine with the Agents Playground, and even run it in Teams with a Teams-managed registration. You need Azure for sign-in (SSO and OAuth), Azure-hosted AI models and hosting your agent in the cloud.
Is the Bot Framework SDK dead?
It's archived and no longer maintained, and Microsoft stopped servicing support tickets for it on December 31, 2025. Existing bots keep working, and Microsoft publishes a migration guide to the Agents SDK. End of Microsoft Bot Framework SDK has the details.
Should I use the Agents SDK or the Teams SDK?
If your agent lives only in Teams and collaborates with people there, Microsoft points you to the Teams SDK. If it has to reach Microsoft 365 Copilot, a website or Slack as well, or you want one codebase for several channels, use the Agents SDK. It also has a Teams extension for Teams-only features such as meetings and message extensions.
Can I use any AI model?
Yes. The SDK doesn't call a model itself. This course uses Microsoft Agent Framework with a model deployed in Microsoft Foundry, signed in with Microsoft Entra ID instead of API keys, but any model or library you can call from .NET works.
Can I use JavaScript or Python instead of C#?
The SDK supports both. This course uses C# throughout, so every code sample, command and output on these pages is .NET.
Conclusion
The Microsoft 365 Agents SDK is the layer between your agent's logic and the places people talk to it: it turns every message into an activity, routes it to your code, keeps the conversation's state and sends your answer back through the right channel. You bring the brain — your own code, or a model through Microsoft Agent Framework — and you choose the channels.
Next: build your first agent in Building an Echo Agent in C#, after setting up the development environment.
Additional Resources
- What is the Microsoft 365 Agents SDK — Microsoft's overview and the three problems it solves.
- Choose an Agent Communication Service registration type — Teams-managed and Azure-managed registrations.
- Agent tenancy — single-tenant and multi-tenant agents.
- Custom engine agents for Microsoft 365 Copilot — what a custom engine agent is and where it runs.
- Azure AI Bot Service pricing — standard and premium channels.
- Microsoft 365 Agents SDK samples for .NET — Microsoft's sample agents.