Agents-for-net copilot-instructions.md

Copilot Instructions for Agents-for-net

Project Overview

This is the Microsoft 365 Agents SDK for .NET — a framework for building enterprise-grade conversational agents that work across M365, Teams, Copilot Studio, and other platforms.

Current State: Generally Available (GA)
Documentation: https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/

Build and Test

# Build entire solution
dotnet build src/Microsoft.Agents.SDK.sln

# Build via top-level project (includes all libraries)
dotnet build AgentSdk.proj

# Restore dependencies
dotnet restore AgentSdk.proj

# Run all tests
dotnet test --no-build -c Debug ./src/

# Run tests for a single project
dotnet test src/tests/Microsoft.Agents.Core.Tests/

# Run a single test
dotnet test --filter "FullyQualifiedName~Namespace.ClassName.MethodName"

# Create NuGet packages
dotnet pack --no-build -c Debug src/Microsoft.Agents.SDK.sln

Architecture

The SDK is organized into layered libraries under src/libraries/. See doc/architecture.md for a architecture overview.

Agent Pattern

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync);
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }
}

ASP.NET Core Startup

builder.AddAgent<MyAgent>();
builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.Services.AddAgentAspNetAuthentication(builder.Configuration);
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

See src/samples/EmptyAgent/Program.cs for the canonical minimal example.

Extensions

Microsoft.Agents.Extensions.MSTeams (src/libraries/Extensions/Microsoft.Agents.Extensions.MSTeams/)

• Full Microsoft Teams extensibility: message extensions, task modules, meeting events, channel/team lifecycle, and file consent
• Aligns its models and public feature surface with the Teams SDK. When the Teams SDK removes a feature, MSTeams removes the corresponding feature rather than maintaining a compatibility implementation. These removals are breaking changes for MSTeams users and may occur in minor or patch releases.
• Depends on teams.net's Microsoft.Teams.Apps NuGet package for Teams schema, API clients, and feature types (e.g. Microsoft.Teams.Apps.Schema.TeamsChannelData, Microsoft.Teams.Apps.Clients.ApiClient, Microsoft.Teams.Apps.MessageExtensions.*); it reimplements only routing on AgentApplication
• Agent 365 lifecycle events are not handled by the Agents SDK or the MSTeams extension. Use the A365 Agent Extension (Microsoft.Agents.A365.Notifications) for these events.
• Enable with [TeamsExtension] attribute on a partial AgentApplication subclass — source generator creates a Teams property of type TeamsAgentExtension
• Two routing styles: fluent builders (Teams.MessageExtensions.OnQuery(...)) or declarative attributes ([TeamsQueryRoute("cmdId")])
• Feature areas exposed as properties on TeamsAgentExtension (accessed via the generated Teams property):
  • Teams.MessageExtensions — search queries, link unfurling, anonymous link unfurling, action commands, compose previews, card button clicks, settings
  • Teams.TaskModules — modal dialogs (fetch + submit), supports string or Regex key matching
  • Teams.Meetings — start/end, participants join/leave
  • Teams.Channels — created/deleted/renamed/restored/shared/unshared; member add/remove
  • Teams.Teams — archived/unarchived/renamed/deleted/restored
  • Teams.FileConsent — file upload consent accept/decline
• TeamsAgentExtension also provides Graph helpers: GetTeamsClient() (teams.net Microsoft.Teams.Apps.Clients.ApiClient), GetGraphClient() (user token), GetAppGraphClient() / GetAppGraphClientForConnection() (app-only)
• App-level Teams route extension methods on AgentApplication (in TeamsAppExtensions): OnTeamsHandoff() (Copilot handoff), OnTeamsFeedbackLoop(), OnTeamsMessageReactionsAdded() / OnTeamsMessageReactionsRemoved(), plus generic OnTeamsActivity() / OnTeamsMessage() / OnTeamsConversationUpdate() / OnTeamsEvent()
• ITeamsTurnContext / TeamsTurnContext — SendTargetedActivityAsync() for sending to specific recipients
• TeamsActivityExtensions — activity helpers: TeamsGetChannelId(), TeamsGetMeetingInfo(), TeamsGetTeamInfo(), TeamsEnableFeedbackLoop(), etc.
• Route builders accept autoSignInHandlers and route attributes accept signInHandlers parameter for per-route OAuth/SSO flows; Teams SSO and OBO via Azure Bot Token Service are supported
• Feedback is the FeedbackLoop feature in AgentApplication; use AgentApplication.OnFeedbackLoop() or [FeedbackLoopRoute] rather than treating it as an MSTeams-specific feature.
• Adaptive Cards support is handled by AgentApplication.AdaptiveCards