Skip to main content

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:

  1. 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.
  2. Routes it to the handler you registered for that kind of activity: one handler for messages, another for people joining, another for card buttons.
  3. 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:

MyAgent.cs
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:

ProductWhat it isUse it when
Microsoft 365 Agents SDKA framework that connects your code to channels and keeps conversation stateYou write the agent in code and want it in Teams, Microsoft 365 Copilot, a website, Slack or several of them at once
Teams SDKMicrosoft's SDK for agents and apps built specifically for Microsoft TeamsYour agent lives only in Teams and works with people there; Microsoft points Teams-only collaborative agents to it
Microsoft Copilot StudioA low-code, hosted agent builderYou'd rather build and host an agent without writing a service; your code can still call it, and it can call yours
Declarative agentsAgents that run on Microsoft 365 Copilot's own model and orchestrator, described in a manifestCopilot's model and knowledge are enough and you add instructions, knowledge and actions; no hosting
Microsoft Agent FrameworkA framework for the agent's brain: models, tools, memory and workflowsYou need the AI part; it runs inside an Agents SDK agent, and the weather agent uses it
Microsoft Agent 365 SDKAdds enterprise identity, governed Microsoft 365 tools and notifications to an agent you already haveYour organization manages agents with Agent 365; Microsoft says it doesn't build agents and works alongside the Agents SDK
Bot Framework SDKThe Agents SDK's predecessorNot 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.

ChannelWhat people useWhat it costs on Azure Bot Service
Microsoft TeamsPersonal chats, group chats, channels and meetingsFree: a standard channel, unlimited messages on the free F0 tier
Microsoft 365 CopilotCopilot Chat, as a custom engine agentNot listed on the Azure Bot Service pricing page; see the note below the table
Web Chat and Direct LineA chat window on your own website, or your own appA premium channel: up to 10,000 messages a month on the free F0 tier; $0.50 per 1,000 messages on the S1 tier
SlackYour Slack workspaceFree: 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:

RegistrationWhere you create itNeeds an Azure subscriptionSign-in (SSO, OAuth)
Teams-managedThe Teams Developer Portal, or a toolkitNoNot supported
Azure-managedAn Azure Bot resource in AzureYesFully 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.

PackageWhat it gives you
Microsoft.Agents.Hosting.AspNetCoreHosts 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.BuilderAgentApplication, routing, turn state, streaming responses, proactive messages and user sign-in
Microsoft.Agents.CoreThe Activity Protocol: activities, cards, attachments and channel names
Microsoft.Agents.Authentication.MsalLets your agent prove its identity with a secret, a certificate or a managed identity
Microsoft.Agents.Storage, .Storage.Blobs, .Storage.CosmosDbWhere state is kept: in memory, in Azure Blob Storage or in Azure Cosmos DB
Microsoft.Agents.Extensions.MSTeamsTeams features: message extensions, dialogs, meetings, files and more
Microsoft.Agents.CopilotStudio.ClientCalls a Copilot Studio agent from your code
Microsoft.Agents.ClientLets 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.

CapabilityWhat it doesWhere you'll learn it
Hosting and your first agentRun an agent in ASP.NET Core and talk to it locallyBuilding an Echo Agent in C#
AI with Microsoft Agent FrameworkAnswer with a model and tools, keylessly, with streamingBuilding a Weather Forecast Agent in C#
Activities and the Activity ProtocolWhat every message looks like, per channelFundamentals, Part 1 (coming soon)
Routing with AgentApplicationMessages, events, ranks, errors and middlewareFundamentals, Part 2 (coming soon)
Conversation and user stateRemember things between messagesFundamentals, Part 3 (coming soon)
Teams registration and dev tunnelsRun your local agent in real TeamsFundamentals, Part 4 (coming soon)
Adaptive Cards and Universal ActionsForms and approval cards that update for each personLeave Requests & Approvals (coming soon)
Dialogs (task modules)Pop-up forms in TeamsLeave Requests & Approvals (coming soon)
Proactive messagesMessage people without them messaging firstLeave Requests & Approvals (coming soon)
Slash commands, suggested actions, targeted messagesTeams messaging featuresLeave Requests & Approvals (coming soon)
Single sign-on and OAuthSign people in and call Microsoft Graph for themLeave Requests & Approvals (coming soon)
Azure Cosmos DB storageKeep state in a database, keylesslyLeave Requests & Approvals (coming soon)
Microsoft 365 Copilot channelUse the agent in Copilot ChatLeave Requests & Approvals (coming soon)
Lifecycle events and rostersReact to teams and channels; know who's thereMeeting Assistant (coming soon)
Meeting eventsMeeting start and end; people joining and leavingMeeting Assistant (coming soon)
Streaming, AI labels, citations, feedbackTrustworthy AI answers in TeamsMeeting Assistant (coming soon)
Files and file consentSend and receive filesMeeting Assistant (coming soon)
TelemetryTraces and metrics with OpenTelemetryMeeting Assistant (coming soon)
Grounded answers in CopilotAnswer from company documents the person may readCompany Policy Agent (coming soon)
Message extensions and link previewsSearch and share from any chatCompany Policy Agent (coming soon)
Web Chat and Direct LinePut the agent on your own websiteCustomer Support Agent (coming soon)
Copilot Studio integrationCall a Copilot Studio agent, and be called by oneCustomer Support Agent (coming soon)
SlackReach people in SlackCustomer Support Agent (coming soon)
Transcripts and agent-to-agentKeep conversation records; let agents call each otherCustomer Support Agent (coming soon)
Production readiness and deploymentSecure, observable agents in AzureEvery 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​

ToolWhat it's for
.NET 10 SDKBuilds and runs C# agents
Visual Studio Code or Visual Studio 2026Your editor; every step works in both
Microsoft 365 Agents ToolkitCreates 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 PlaygroundA chat window on your machine that talks to your local agent, no account needed
Dev tunnelsA public address for your local agent, so real Teams can reach it
Azure CLISigns 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​