Add fluent builder helpers to Core.Models (ease-of-use)

[tracyboehrer]

Summary

Adds non-breaking, purely additive fluent/builder helpers to Microsoft.Agents.Core.Models, closing an ergonomics gap identified by comparing the SDK models against microsoft/teams.net (Microsoft.Teams.Api). The Agents SDK models are structurally equivalent, but teams.net offers a fluent, chainable builder style that the Agents SDK lacked. Every addition here is a new method/overload — no signature, type, or serialization changes, so nothing breaks for existing consumers.

What's added

ActivityBuilderExtensions.cs (new) — chainable extensions on IActivity (compose nicely with the existing Activity.Create* factories):

• Setters: WithText, WithSpeak, WithInputHint, WithSummary, WithLocale, WithTextFormat, WithAttachmentLayout, WithDeliveryMode, WithName, WithValue, WithSuggestedActions
• Adders: AddText (append), AddAttachment(params Attachment[]), plus overloads that auto-wrap HeroCard/ThumbnailCard/AnimationCard/AudioCard/VideoCard/ReceiptCard/OAuthCard/SigninCard
• AddEntity, AddMention(account, text, addText) — injects <at> markup + a Mention entity
• Type checks: IsMessage, IsEvent, IsInvoke, IsTyping, IsConversationUpdate, IsEndOfConversation, IsHandoff, IsTrace, IsCommand, IsCommandResult

IActivityExtensions.cs — GetAccountMention(id) and IsRecipientMentioned() (parity with teams.net mention query helpers; complements the existing GetMentions()).

SuggestedActions.cs — fluent AddAction, AddActions, AddRecipients (return this).

CardBuilderExtensions.cs (new) — fluent builders across HeroCard, ThumbnailCard, BasicCard, AnimationCard, AudioCard, VideoCard, MediaCard, ReceiptCard: WithTitle/WithSubtitle/WithText/WithTap, AddImage, AddMedia, AddButton/AddButtons, and receipt-specific WithTotal/WithTax/AddFact/AddItem. Backing collections are created on demand, so these are safe on default-constructed cards.

Examples

Building a message with a card and a mention in one expression:

var activity = Activity.CreateMessageActivity()
    .WithText("Here''s your summary")
    .WithSummary("Weekly report")
    .AddMention(user)
    .AddAttachment(new HeroCard()
        .WithTitle("Weekly Report")
        .WithSubtitle("2026-07-17")
        .AddImage("https://contoso/report.png", "chart")
        .AddButton("Open", type: ActionTypes.OpenUrl, value: "https://contoso/report")
        .AddButton("Dismiss", value: "dismiss"));

Suggested actions, fluently:

var activity = Activity.CreateMessageActivity()
    .WithText("Pick one:")
    .WithSuggestedActions(new SuggestedActions()
        .AddRecipients("user1")
        .AddAction(new CardAction(type: ActionTypes.ImBack, title: "Yes", value: "yes"))
        .AddActions(
            new CardAction(type: ActionTypes.ImBack, title: "No", value: "no"),
            new CardAction(type: ActionTypes.ImBack, title: "Maybe", value: "maybe")));

Mention queries:

if (activity.IsRecipientMentioned())
{
    var mention = activity.GetAccountMention(activity.Recipient.Id);
    // ...
}

Type checks:

if (activity.IsMessage()) { /* ... */ }

Notes / scope

• I intentionally did not add ToAttachment() to MediaCard/BasicCard: those two types have no defined content-type constant in ContentTypes, so a standard attachment can''t be produced. They received fluent builders instead.
• These are extension methods on IActivity (rather than interface members) specifically to avoid a breaking change to interface implementers.

[MattB-msft]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).