Azure.AI.AgentServer.Activity 1.0.0-beta.1

Azure AI Agent Server Activity library for .NET

Azure.AI.AgentServer.Activity is a .NET library for hosting a Microsoft 365 Agents SDK AgentApplication as an Azure AI Foundry hosted agent that speaks the activity protocol (POST /activity/messages). Your agent is an ordinary Microsoft 365 Agents SDK application; this library adds the Foundry-specific hosting — the outbound-auth connection provider, the activity endpoint, session and correlation resolution, error-source classification, and distributed tracing — on top of the shared Azure.AI.AgentServer.Core host.

Source code | Package (NuGet) | Product documentation

Getting started

Install the package

Install the library for .NET with NuGet:

dotnet add package Azure.AI.AgentServer.Activity --prerelease

Prerequisites

• An Azure subscription
• .NET 8 or later
• The Azure.AI.AgentServer.Core package (installed automatically as a dependency)

Run an agent

The fastest path registers handlers inline on the AgentApplication the host builds for you — no agent class required:

// Build the host (initializes the Microsoft 365 Agents SDK stack from the environment)
// and register handlers inline on the AgentApplication — no agent class required.
ActivityServer.Run(
    (AgentApplication app) =>
    {
        // Echo the user's message back.
        app.OnActivity(ActivityTypes.Message, async (ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken) =>
        {
            var userText = turnContext.Activity.Text ?? string.Empty;
            if (!string.IsNullOrWhiteSpace(userText))
            {
                await turnContext.SendActivityAsync($"Echo: {userText}", cancellationToken: cancellationToken);
            }
        });
    },
    args);

Or host an agent class by type — the standard Microsoft 365 Agents SDK style, where handlers are registered in the constructor:

// A standard Microsoft 365 Agents SDK agent. Its handlers are registered in the constructor,
// so the Tier 1 one-liner can host it by type.
public sealed class EchoAgent : AgentApplication
{
    public EchoAgent(AgentApplicationOptions options) : base(options)
    {
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    private async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        await turnContext.SendActivityAsync($"Echo: {turnContext.Activity.Text}", cancellationToken: cancellationToken);
    }
}

// The fastest path to a running Activity agent — one line.
ActivityServer.Run<EchoAgent>(args);

Key concepts

ActivityServer.Run(...)

The one-line entry point. Each overload creates the Core host builder, registers the Activity protocol, builds, and runs — wiring OpenTelemetry, health probes, and the Foundry middleware for you. Pick the overload that matches how your agent is constructed:

Each Run overload (except the raw-handler one) also accepts configureOptions to configure ActivityServerOptions and configure to further configure the underlying AgentHostBuilder.

ActivityServerOptions

Configuration for the built stack. Every property is optional.

Outbound auth models

Reply delivery supports two identity models, selected via ActivityServerOptions.DigitalWorker:

• Simple (DigitalWorker = false, default) — the agent instance identity (FOUNDRY_AGENT_INSTANCE_CLIENT_ID) mints the Bot Connector token directly, scoped to https://api.botframework.com/.default.
• Digital worker (DigitalWorker = true) — the blueprint identity (FOUNDRY_AGENT_BLUEPRINT_CLIENT_ID) performs a federated-identity (FMI) token exchange to obtain an agentic user token.

Hosting tiers

Three levels of control, from most opinionated to least:

• Tier 1 — one-liner: ActivityServer.Run(...). The library owns the host.
• Tier 2 — builder: AgentHost.CreateBuilder(args).AddActivity<TAgent>() (also AddActivity(agentApp) and AddActivity(factory)). Compose on the Core builder to register your own services and tracing.
• Tier 3 — self-hosted: on your own WebApplication, builder.AddFoundryActivity() + app.MapFoundryActivity() (aliased as AddActivityServer() / MapActivityServer()) add the Activity endpoints alongside your own routes. This is also the two-line conversion path for an existing Microsoft 365 Agents SDK app.

var builder = WebApplication.CreateBuilder(args);

// Your existing agent + storage registration (unchanged Microsoft 365 Agents SDK setup).
builder.AddAgent<EchoAgent>();
builder.Services.AddSingleton<IStorage, MemoryStorage>();

// Add the Activity protocol to your own host. AddActivityServer() is the alias for
// AddFoundryActivity().
builder.AddActivityServer();

var app = builder.Build();

// Your existing endpoints coexist with the Activity endpoints.
app.MapGet("/", () => "My existing app");

// Map the Activity endpoint (/activity/messages) and /readiness.
// MapActivityServer() is the alias for MapFoundryActivity().
app.MapActivityServer();

app.Run();

Endpoints

Inbound message activities are queued to the Microsoft 365 Agents SDK background service and acknowledged with HTTP 202 Accepted; the reply is delivered asynchronously to the caller's serviceUrl. Every response carries the resolved session-id header and correlation baggage.

Examples

Compiled walkthroughs live in the samples directory (getting started, welcome/commands, digital worker, customizing the build, custom request handler, injected application, M365-native hosting, the three hosting tiers, Adaptive Cards, and invoke activities). Deployable projects are in the Foundry hosted-agents sample gallery.

Troubleshooting

• 404 on /activity/messages: Ensure you registered the protocol — via ActivityServer.Run(...), builder.AddActivity(...), or builder.AddFoundryActivity() + app.MapFoundryActivity().
• Replies not delivered: Confirm the inbound activity carries a serviceUrl and conversation id, and that the outbound-auth model (DigitalWorker) and connection environment variables (FOUNDRY_AGENT_INSTANCE_CLIENT_ID / FOUNDRY_AGENT_BLUEPRINT_CLIENT_ID / FOUNDRY_AGENT_TENANT_ID) match your deployment. Outbound managed-identity token acquisition only succeeds when deployed to Azure.

Next steps

• Read the hosting & handler guide for the full hosting-tier and handler reference.
• Review the activity protocol samples.
• Learn about the shared host in Azure.AI.AgentServer.Core.

Contributing

This project welcomes contributions and suggestions. See the repository CONTRIBUTING.md for details.