teams-sdk-to-agents-sdk-dotnet-migration

Teams SDK (teams.net) to Agents SDK Migration (.NET)

Overview

When an automation caller supplies validation tools instead of shell access, use those tools to perform the build, tests, and startup checks required below. A current passing tool result is equivalent evidence; do not request unavailable shell access or claim validation from source inspection alone. Follow the caller's read-only role when reviewing.

Migrates a Teams SDK (teams.net, https://github.com/microsoft/teams.net) bot to a Microsoft 365 Agents SDK AgentApplication. The Teams SDK registers fluent event delegates (teamsApp.OnMessage(async context => ...)) on an IContext<T>; the Agents SDK routes activities to handler methods on an AgentApplication subclass using ITurnContext.

This is NOT the Bot Framework migration. If the project depends on Microsoft.Bot.Builder*, use bf-to-agents-sdk-dotnet-migration instead. Trigger this skill only for teams.net projects (Microsoft.Teams.Plugins.AspNetCore, Microsoft.Teams.Apps, Microsoft.Teams.Api).

Agents SDK repository: https://github.com/microsoft/agents-for-net Teams SDK repository: https://github.com/microsoft/teams.net

Core Rules

• Preserve behavior. Keep the same commands, text matching, and responses except for user-facing references to the migrated runtime, which should say "agent" instead of "bot". Make other response changes only when required to run on the Agents SDK.
• Describe the migrated runtime as an agent in README text, catalog descriptions, and user-facing messages. Keep platform terms such as Azure Bot, bot ID, and manifest bots[], and preserve source-derived paths and identifiers unless the caller requests a rename.
• After source migration is stable, use the standalone teams-app-manifest skill to generate, complete, or audit the Teams app manifest from source evidence and explicit product intent. Do not embed manifest feature rules in this migration skill.
• Use stable Agents SDK packages. A caller's minimum Agents SDK version is a floor, not the version to copy into the project. In automated sample sync, use the selectedAgentsSdkVersion in the frozen sync context. Respect a customer's explicitly selected release line. Otherwise, read the Agents SDK release history JSON (follow later pages when needed) and select the newest stable release within the permitted major, then confirm a common major.minor release line for Microsoft.Agents.Hosting.AspNetCore, Microsoft.Agents.Authentication.Msal, and Microsoft.Agents.Extensions.MSTeams from the Hosting, Authentication, and MSTeams JSON version feeds. Use the newest compatible stable line available for all three, without assuming their patch numbers match. Do not select a prerelease or a new major version without explicit policy.
• If the project defines the AgentApplication during DI (typically in Program.cs), ask the customer whether to keep it inline or move it to an AgentApplication subclass with Teams route attributes. In the automated Teams sample sync, do not ask a user. Apply an applicable migration policy or return needs-policy with evidence and a recommended policy.
• If creating a subclass, always use [TeamsExtension], mark it partial, use Teams route attributes, and take ITeamsTurnContext in route handlers.
• After restoring packages, verify route attributes, handler delegate signatures, payload models, and response types against the installed configured-version XML documentation or current Agents SDK source. Do not infer an API shape from a similarly named Teams SDK API.
• Preserve the original registration and if/else precedence. Use explicit route rank values whenever multiple text or invoke routes can match the same activity.
• Prefer SendActivityAsync("text", cancellationToken: ct) for plain text. When a reply needs entities, attachments, or other activity fields, build an activity with Activity.CreateMessageActivity() and fluent methods such as .WithText(...), then set the extra fields. Keep a factory when it adds value for a structured response.
• Use the agent's logger for diagnostics instead of Console.WriteLine; pass exceptions to structured logging rather than logging only their messages.