Azure AI Agent Server Core library for .NET

Azure.AI.AgentServer.Core is a shared hosting foundation for Azure AI Agent Server packages. It provides a library-owned ASP.NET Core host with built-in OpenTelemetry, health checks, graceful shutdown, and multi-protocol composition — so you can go from dotnet add package to a running agent server in minutes.

Source code | Package (NuGet) | Product documentation

Getting started

Install the package

Install the library for .NET with NuGet:

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

Prerequisites

• An Azure subscription
• .NET 8 or later

Upgrading from a version prior to beta.21? The package has been redesigned as a lightweight hosting foundation. Protocol logic has moved to Azure.AI.AgentServer.Responses and Azure.AI.AgentServer.Invocations. See the Migration Guide for details.

Tier 1 — One-liner (recommended)

Each protocol package provides a one-line server that includes Core as a transitive dependency:

// Responses protocol — install Azure.AI.AgentServer.Responses
ResponsesServer.Run<EchoHandler>();

// Invocations protocol — install Azure.AI.AgentServer.Invocations
InvocationsServer.Run<MathHandler>();

This starts a Kestrel server on the PORT environment variable (default 8088) with OpenTelemetry, a /readiness health endpoint, x-request-id request correlation, x-platform-server version header, and inbound request logging — all configured automatically.

Tier 1 supports customization via an Action<AgentHostBuilder> callback for registering additional services, middleware, or configuration. See the protocol-specific README for details.

Tier 2 — Builder pattern

Use AgentHost.CreateBuilder() when you need to compose multiple protocols, register custom services, or customize the host:

var builder = AgentHost.CreateBuilder();

// Register protocol endpoints (protocol packages provide extension methods).
builder.RegisterProtocol("MyProtocol", endpoints =>
{
    endpoints.MapGet("/hello", () => "Hello from the agent server!");
});

var app = builder.Build();
app.Run();

The builder provides all the same defaults as Tier 1 (OpenTelemetry, health endpoint, request correlation, version header, logging). Access the underlying WebApplicationBuilder via builder.WebApplicationBuilder for full ASP.NET Core customization (CORS, authentication, custom middleware, etc.).

Tier 3 — Standalone (existing apps)

If you have an existing ASP.NET Core application, call AddAgentServerCore() and UseAgentServerCore() to opt in to Core middleware, then register protocol endpoints alongside your own:

var builder = WebApplication.CreateBuilder();
builder.Services.AddAgentServerCore();

var app = builder.Build();
app.UseAgentServerCore();
app.MapGet("/hello", () => "Hello!");
app.Run();

This enables request correlation (x-request-id), server version header (x-platform-server), and inbound request logging. See the protocol-specific Tier 3 samples (Responses, Invocations) for complete examples including handler registration, health probes, and OpenTelemetry setup.

Key concepts

AgentHost

The static entry point. AgentHost.CreateBuilder() returns an AgentHostBuilder for composing protocols and configuring the server.

AgentHostBuilder

Configures the underlying ASP.NET Core host with sensible defaults: Kestrel on the PORT environment variable (or 8088), OpenTelemetry traces and metrics, a /readiness health endpoint, and x-platform-server version header. Protocol packages use RegisterProtocol() to add their endpoints — each protocol registers its identity segment with the ServerVersionRegistry.

PlatformHeaders

The PlatformHeaders static class defines all HTTP header name constants used across the AgentServer platform. Using these constants avoids typos and keeps header names consistent across protocol packages.

Request correlation (x-request-id)

RequestIdMiddleware sets the x-request-id response header on every HTTP response. The value is resolved in priority order:

1. OpenTelemetry trace ID (if an Activity is active)
2. Incoming x-request-id request header (if present)
3. New GUID (fallback)

Error source classification

All error responses (4xx/5xx) include the x-platform-error-source header to classify where the error originated:

Platform errors also include x-platform-error-detail with diagnostic context (exception type, message, stack trace). User and upstream errors omit the detail header.

FoundryEnvironment

Reads Azure AI Foundry platform variables (FOUNDRY_*, PORT, SSE_KEEPALIVE_INTERVAL) to resolve agent identity, listening port, and connection strings. Also detects OTEL_EXPORTER_OTLP_ENDPOINT and APPLICATIONINSIGHTS_CONNECTION_STRING for telemetry configuration. Useful when your agent server runs as a hosted agent in AI Foundry.

FoundryAgentRequestContext

On container protocol 2.0.0 a single agent session can serve multiple users. Each request carries x-agent-user-id (the user — partition state by it) and an opaque x-agent-foundry-call-id (the per-request caller identity). Read both via FoundryAgentRequestContext.Current. Register FoundryCallIdHandler on any HttpClient that calls Foundry services so the call ID is echoed automatically on every outbound request — only the call ID is echoed (x-agent-user-id is never forwarded). Forwarding the call ID lets a tool server resolve which user made the request and act on their behalf.

using Azure.AI.AgentServer.Core;

// Any HttpClient with FoundryCallIdHandler echoes the CURRENT request's
// x-agent-foundry-call-id — never bake one call's ID into static DefaultRequestHeaders.
builder.Services.AddHttpClient("foundry", c => c.BaseAddress = new Uri(projectEndpoint))
    .AddHttpMessageHandler<FoundryCallIdHandler>();

// Anywhere during the request:
string? userId = FoundryAgentRequestContext.Current.UserId;   // for the container's own per-user state
string? callId = FoundryAgentRequestContext.Current.CallId;   // per-request caller identity

Telemetry

OpenTelemetry is configured automatically via the Microsoft.OpenTelemetry distro. The Responses and Invocations protocols use dedicated activity source names (Azure.AI.AgentServer.Responses and Azure.AI.AgentServer.Invocations) for distributed tracing. Azure Monitor export is enabled when APPLICATIONINSIGHTS_CONNECTION_STRING is set, and OTLP export is enabled when OTEL_EXPORTER_OTLP_ENDPOINT is set.

Health endpoint

A /readiness endpoint is registered by default, responding to liveness and readiness probes. It reports healthy as soon as the host finishes starting.

Examples

You can familiarise yourself with different APIs using Samples.

Troubleshooting

Common errors

• Port already in use: The server defaults to port 8088 (or the PORT environment variable). If the port is occupied, set PORT to another value or configure Kestrel directly via the builder.
• No protocol registered: If you use AgentHost.CreateBuilder() without calling RegisterProtocol() (or a protocol extension method), the server will start but will have no protocol endpoints mapped.

Logging

The library emits OpenTelemetry traces via the Azure.AI.AgentServer.Responses and Azure.AI.AgentServer.Invocations activity sources. Inbound request logging is enabled automatically for Tier 1 and Tier 2 setups; for Tier 3, call AddAgentServerCore() and UseAgentServerCore() to enable it. Enable ASP.NET Core logging in your application configuration to diagnose startup issues.

Next steps

• Samples — Getting started, multi-protocol composition

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.