Azure.AI.AgentServer.Invocations

Azure AI Agent Server Invocations library for .NET

Azure.AI.AgentServer.Invocations is a .NET library for building ASP.NET Core servers that implement the Azure AI Invocations protocol. Subclass InvocationHandler, register it with the hosting builder, and the library handles routing, session resolution, client header forwarding, and invocation lifecycle management.

Source code | Package (NuGet) | Product documentation

Getting started

Install the package

Install the library for .NET with NuGet:

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

Prerequisites

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

Configure the server

The fastest way to get running:

InvocationsServer.Run<EchoHandler>();

Where EchoHandler implements the Invocations protocol:

public class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request, HttpResponse response,
        InvocationContext context, CancellationToken cancellationToken)
    {
        var input = await new StreamReader(request.Body).ReadToEndAsync(cancellationToken);
        await response.WriteAsync($"You said: {input}", cancellationToken);
    }
}

For more control over the host (adding services, configuring middleware, composing multiple protocols), see Customizing the host below.

Key concepts

InvocationHandler

The abstract base class you subclass. Only HandleAsync is abstract — the remaining operations (GetAsync, CancelAsync, GetOpenApiAsync) return 404 by default and can be overridden as needed.

InvocationContext

Provides request metadata to the handler, including the resolved session ID and forwarded client headers.

Session resolution

The library automatically extracts a session identifier from incoming requests, enabling multi-turn invocation tracking. The resolved session ID is available on InvocationContext.SessionId.

Client header forwarding

Headers prefixed with x-client-* are automatically captured from the incoming request and made available via InvocationContext.ClientHeaders, allowing end-to-end tracing context and client metadata to flow through the server.

Customizing the host

When you need to add services, configure middleware, or compose multiple protocols on a single host, see the hosting tier samples:

• Tier 1 hosting customization
• Tier 2 builder
• Tier 3 self-hosting

Handler lifetime

Handlers registered via AddInvocations<THandler>() or InvocationsServer.Run<THandler>() are resolved per request by default (scoped lifetime). Instance fields on your InvocationHandler subclass will not persist across requests. Store long-lived state in separate services or storage keyed by InvocationContext.SessionId or InvocationContext.InvocationId, or register a singleton handler explicitly if you require a single shared instance.

Examples

You can familiarise yourself with different APIs using Samples.

Troubleshooting

Common errors

• 404 on invocation endpoint: Ensure your handler is registered via AddInvocations<THandler>() on the builder. If you registered on IServiceCollection directly without mapping endpoints, the routes will not be created.
• Handler not found: The Invocations protocol requires Azure.AI.AgentServer.Core for the underlying host. If you see startup errors, verify that you are using AgentHost.CreateBuilder() or InvocationsServer.Run<THandler>().

Logging

The library emits OpenTelemetry traces via the Azure.AI.AgentServer.Invocations activity source. Enable ASP.NET Core logging in your application configuration to diagnose request routing issues.

Next steps

• Samples — Getting started, custom operations
• Azure.AI.AgentServer.Core — Shared hosting foundation
• Azure.AI.AgentServer.Responses — Responses protocol implementation

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 [email protected] with any additional questions or comments.