Share via

Azure Bot Framework SDK to Agents SDK migration guidance

The Microsoft 365 Agents SDK provides developers the ability to create and tailor agents using the AI stack of their choice. Developers can create a custom engine agent (CEA) and deploy it to Microsoft 365 Copilot. Developers can get started with the Microsoft 365 Agents Toolkit for Visual Studio and Visual Studio Code to get started quickly with scaffolding and templates. Developers can add their chosen models and orchestrator from Azure Foundry and Semantic Kernel, OpenAI Agents, LangChain, or even a custom built orchestrator. Developers can even choose to bring multiple agents built with different technologies, and surface the agents through Microsoft 365 Copilot.

Using the Microsoft 365 Agents SDK, we want you to be able to build an agent quickly and surface it on any channel, including Microsoft 365 Copilot and Microsoft Teams.

The SDK is designed to be un-opinionated about the AI you use. You can implement agentic patterns without being locked into a tech stack.

The SDK takes advantage of specific client channel behavior, such as Microsoft 365 Copilot, Teams, and other non-Microsoft channels, to allow you to tailor your agent to client channels, including specific events or actions.

Unsupported and deprecated packages

The Microsoft 365 Agents SDK is the evolution of the Azure Bot Framework SDK. The Azure Bot Framework was previously the way for a developer to build bots with a primary focus on conversational AI around topics, dialogs, and messages. The industry norm is now to use generative AI functionality, grounded on knowledge located across the enterprise. Companies need to be able to orchestrate actions, and answer questions, from within a conversational experience. The Microsoft 365 Agents SDK provides capabilities for modern agent development, bringing together the creation of conversational agents with conversation management and orchestration. Agents built with the SDK can connect to numerous AI services and clients, including agents created with non-Microsoft software or technology.

This article is written to provide guidance and awareness if you're considering, or in the process of, migrating from the Azure Bot Framework to the Agents SDK. With this information, you can stay informed and make more informed decisions.

The functionalities in the following list aren't supported in Agents SDK. Bots requiring these functionalities won't be able to migrate without implementing alternatives:

  1. Adaptive Dialogs: The Adaptive Dialog System (implemented in C# in the Bot Framework) is no longer directly relevant. We don't plan to move this system into the Agents SDK
  2. AdaptiveExpressions: This includes Microsoft.Bot.AdaptiveExpressions.Core. However, these packages are still available for use from the .NET BotBuilder packages. These packages don't take dependencies on SDK packages, and can be used if you wish with Agents SDK. The AdaptiveExpressions functionality, however, isn't actively supported.
  3. Bot FrameworkComposer Artifacts: Artifacts from Composer (adaptive dialogs, adaptive expressions, and so on, implemented in C# in the Bot Framework) are no longer required and aren't being brought forward.
  4. Previous Generation AI Tooling: Tools such as LUIS, Orchestrator, and QnA Maker are no longer needed. The online services for these tools are already disabled. Existing bots that depend on these services need to migrate to different tooling.
  5. Language Understanding: This includes Microsoft.Bot.Builder.Parsers.LU.
  6. Language Generation: LG tooling, template tooling, and related parsers aren't needed. General purpose LLMs replace these tools.
  7. TemplateManager
  8. ASP.Net WebAPI: ASP.NET WebAPI and similar older technologies are no longer needed. This impacts only C#, where only the current generation of ASP.NET Core (ironically called "ASP.NET Core Web API") is supported.
  9. Application Insights
  10. Streaming Connections
  11. QueueStorage
  12. Inspection
  13. BotFrameworkAdapter: Replaced by CloudAdapter in Bot Framework, and removed from the Agents SDK.
  14. Deprecated Activities. Older activities are deprecated, such as payments activities.
  15. Generators. The legacy generators for each of the languages (Yeoman, and so on), aren't being brought forward.
  16. CLI All commands in the Bot Framework CLI ("bf") are deprecated.

DotNet SDK Code changes

  • Startup
    • Token Authentication
      • Must be set up in host (for example ASP.NET web app)
    • Acquiring tokens (for outgoing requests)
      • Includes manual AppCredentials creation, which no longer exists
      • Replaced with IAccessTokenProvider and Microsoft.Agents.Authentication.Msal
    • ConfigurationBotFrameworkAuthentication replaced with RestChannelServiceClientFactory
  • Packages & Namespaces
  • Teams
    • Some TeamsActivityHandler methods required JObject arguments. Replaced with JsonElement
  • Interface/Type name changes
    • IAttachments.GetAttachmentInfo renamed to GetAttachmentInfoAsync
    • IBotFrameworkHttpAdapter renamed to IBotHttpAdapter
    • OAuthPromptSettings.ConnectionName renamed to OAuthPromptSettings.AzureBotOAuthConnectionName
    • BotAdapter renamed to ChannelAdapter
    • CloudAdapterBase renamed to ChannelServiceAdapterBase

Skills

  • Skills functionality exists in Microsoft.Agents.Client
    • SkillConversationIdFactoryBase replaced with IConversationIdFactory
    • SkillConversationIdFactory replaced with ConversationIdFactory
    • SkillConversationIdFactoryOptions replaced with ConversationIdFactoryOptions
    • SkillsConfiguration replaced with IChannelHost & ConfigurationChannelHost
    • CloudSkillHandler replaced with HttpBotChannel and associated HttpBotChannelFactory
    • Response handling now handled by IChannelApiHandler
    • The expected Bot Framework Skill handling is in ProxyChannelApiHandler
    • Different configuration naming and format

Startup

  • Startup.cs and Program.cs are different, including updating the old "Microsoft*" properties and creating the new settings structure.

    "Connections": {
  "BotServiceConnection": {
    "Assembly": "Microsoft.Agents.Authentication.Msal",
    "Type": "MsalAuth",
    "Settings": {
      "AuthType": "{{AuthType}}",
      "AuthorityEndpoint": "https://login.microsoftonline.com/{{TenantId} | "botframework.com"}",
      "ClientId": "{{AppId}}",
      "ClientSecret": "{{MicrosoftAppPassword}}",
      "Scopes": [
        "https://api.botframework.com/.default"
      ]
    }
  }
},
"ConnectionsMap": [
  {
    "ServiceUrl": "*",
    "Connection": "BotServiceConnection"
  }
],

  • Cases where you create any AppCredentials based object for auth is now done through IConnections.

  • Bot Framework SDK uses NewtonSoft for serialization. Agents SDK uses System.Text.Json.

Application replacements

Make the following replacements in your code:

  • .TurnState.Get<IConnectorClient> to .Services.Get<IConnectorClient>
  • .TurnState.Get<IUserTokenClient> to .Services.Get<IUserTokenClient>
  • .TurnState. to .StackState.
  • .StackState.Add to .StackState.Set
  • (RegEx): ApplicationOptions<TState>*.where TState : TurnState, new() to AgentApplicationOptions
  • (RegEx): Application<TState>*.where TState : TurnState, new() to AgentApplication
  • Application to AgentApplication
  • ApplicationOptions to AgentApplicationOptions
  • TState turnState to ITurnState turnState
  • <TState> to {empty}
  • where TState : TurnState to {empty}
  • using Microsoft.Bot.Builder to using Microsoft.Agents.BotBuilder
  • using Microsoft.Bot.Schema; to using Microsoft.Agents.Core.Models; using Microsoft.Agents.Core.Serialization;
  • using Microsoft.Bot.Builder.Integration.AspNet.Core; to using Microsoft.Agents.Hosting.AspNetCore;
  • using Microsoft.Bot.Connector.Authentication; to {remove-line}
  • IAttachments.GetAttachmentInfo renamed to IAttachments.GetAttachmentInfoAsync
  • IBotFrameworkHttpAdapter to IBotHttpAdapter

Related Content

For the fundamentals of how the Microsoft 365 Agents SDK works, check out the official documentation: