Self-host Agent Framework applications

Self-hosting lets you run an Agent Framework agent or workflow in your own ASP.NET Core application, container, service, or runtime. Your application controls routing, identity, authorization, request policy, storage, deployment, and scaling. Add protocol integrations to the host based on the clients you need to support.

Use this option when you need to integrate an agent endpoint with your existing application infrastructure. If you want Microsoft Foundry to run the agent for you, see Foundry Hosted Agents. If you need Azure Functions triggers or durable execution, see Durable Extension.

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

What the hosting helpers provide

The Microsoft.Agents.AI.Hosting package integrates agents and workflows with the .NET generic host:

• AddAIAgent registers a named AIAgent with dependency injection.
• AddWorkflow registers a named workflow. Chain AddAsAIAgent to make the workflow available to protocol integrations through the standard agent interface.
• IHostedAgentBuilder configures hosting services associated with that agent.
• AgentSessionStore optionally loads and saves AgentSession instances by an application- or protocol-supplied continuation ID.

The hosting package isn't an HTTP server or protocol registry. Your application selects the hosted agents and workflows, configures their services, and adds the protocol endpoints it needs.

Persist hosted sessions

Session persistence is opt-in. Without a configured AgentSessionStore, protocol integrations can create a new session for each request but can't recover server-owned session state from an earlier request.

For development or a single-process application, configure the built-in in-memory store:

builder.AddAIAgent("weather-agent", (_, _) => agent)
    .WithInMemorySessionStore(withIsolation: false);

Setting withIsolation to false is appropriate only when one trusted user or process owns the session namespace. InMemoryAgentSessionStore loses all sessions when the process exits and doesn't share state across application instances.

For durable or distributed hosting, implement AgentSessionStore and register it with WithSessionStore. A store implements asynchronous save, get, and delete operations. It receives the owning AIAgent and an opaque session-store ID, and it must return an independent AgentSession instance from each get operation.

AgentSessionStore and history providers serve different purposes. A session store persists the AgentSession selected by a hosted request. A history provider controls where conversation messages are stored. When history is held in session state, persisting the session also persists that history; an external history provider stores messages separately.

Integrate with ASP.NET Core

The shared hosting package uses the .NET generic host and dependency injection. For an HTTP server, create an ASP.NET Core application and add the protocol-specific packages for the endpoints you want to expose. Those packages resolve named AIAgent instances from dependency injection and add ASP.NET Core route mappings.

Your application remains responsible for its middleware pipeline, authentication, authorization, request validation, allowed model options, and durable storage. A non-HTTP host can use the shared hosting services without adding ASP.NET Core protocol endpoints.

Add protocols to your server

Choose the protocol integrations your application needs:

Each protocol defines its own continuation identifier and endpoint behavior. Keep authentication, authorization, session ownership, and durable storage in shared application infrastructure rather than reimplementing them for each endpoint.

Secure session continuation

A continuation ID identifies a session to resume; it doesn't prove that the caller owns that session. Scope persisted sessions by an authenticated user, tenant, or other authorization boundary before accepting client-supplied IDs.

For ASP.NET Core applications that use claims-based authentication, install the prerelease Microsoft.Agents.AI.Hosting.AspNetCore package, register the claims-based isolation provider, and keep isolation enabled on the session store:

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

builder.AddAIAgent("weather-agent", (_, _) => agent)
    .WithInMemorySessionStore();

By default, UseClaimsBasedAgentIsolation uses the ClaimTypes.NameIdentifier claim. Configure another claim only when it is stable and unique across every caller served by the store. The isolation provider doesn't authenticate requests; configure ASP.NET Core authentication and authorization separately. With the default strict isolation behavior, session access fails when the current principal doesn't provide the configured claim.

For a non-HTTP host or another tenancy model, register a custom AgentIsolationKeyProvider. The default WithInMemorySessionStore() and WithSessionStore(...) overloads wrap the configured store in IsolationKeyScopedAgentSessionStore.

Next steps

Go deeper:

• Host agents with A2A
• Build web agent applications with AG-UI
• Foundry Hosted Agents

Self-hosting lets you run an Agent Framework agent or workflow in your own web application, container, service, or runtime. Your application controls routing, identity, authorization, request policy, storage, deployment, and scaling. Add one or more protocol integrations to that server based on the clients you need to support.

Use this option when you need to integrate an agent endpoint with your existing application infrastructure. If you want Microsoft Foundry to run the agent for you, see Foundry Hosted Agents. If you need Azure Functions triggers or durable execution, see Durable Extension.

The design of these packages is such that is allows for maximum flexibility for the developer. This means that if you want to build a host that exposes a agent with the Responses API, and abuse the parameters for other purposes (i.e. map temperature to top_p), you can do that. If you don't want to store sessions, you can do that, if you want to allow the caller to control the full agent run, you can do that too. We will not get in the way, we provide helpers for the common cases, and make you responsible for the rest, to allow you to build the exact host that you need.

pip install --pre agent-framework-hosting

What the hosting helpers provide

The generic hosting package provides shared execution state for an application-owned server:

• AgentState pairs an agent target with a SessionStore and creates sessions when the application selects a new key.
• SessionStore stores, retrieves, and deletes sessions by an application-selected ID. Its default store is process-local and has no eviction policy.
• WorkflowState resolves a workflow target. Your application owns checkpoint storage and any mapping from a client continuation ID to a checkpoint.

AgentState is not a server or protocol registry. Your application selects an authorized session key, resolves the target, and saves the post-run state. It can use the same target and shared application infrastructure for one or several protocol endpoints.

Customize session storage

SessionStore is a small async storage class with get, set, and delete methods. The default implementation keeps sessions in process memory. Subclass it and override those methods to store AgentSession objects in Redis, a database, blob storage, or another application-owned store, then pass the instance to AgentState(session_store=...).

SessionStore and history providers persist separate parts of an agent conversation. A session store saves one session object per session ID, including session metadata and provider state. A dedicated HistoryProvider stores the conversation separately, typically as one record per message. This separation is recommended for durable hosts because appending individual messages is generally more efficient than rewriting a growing session object after every turn. A history provider is defined per agent, by passing the desired history provider class to the context_providers parameter.

Bring your own framework or client library

The hosting packages aren't tied to a web framework or client library. The samples use FastAPI and aiogram because they provide concise runnable examples, not because the helpers require them.

• For HTTP endpoints, use the routing and request/response APIs of your application framework, such as FastAPI, Starlette, Django, Flask, Azure Functions, or another framework.
• For protocol clients such as Telegram, use any client library that can supply a protocol update and execute the operations produced by the helper.

The application selects its framework and client library; the Agent Framework packages only convert protocol data and manage optional execution state. They don't register routes, authenticate callers, authorize access to state, choose allowed model options, or provide durable storage.

Add protocols to your server

Choose one or more protocol integrations:

Each protocol page describes its setup. However they are designed to allow you to build a single host with one or more protocols enabled and a callable target; either an agent or a workflow. Since we do not limit you to one web framework, you can choose the one you want, and setup the host with those protocols with ease.

Secure session continuation

Treat every protocol-provided identifier as untrusted input. Before using an ID to load a session, checkpoint, task, or other state:

1. Authenticate the caller.
2. Authorize the caller to access the referenced state.
3. Partition durable state by the authenticated tenant, user, or workspace.
4. Persist session and checkpoint state only after the run or stream has completed.

This self-hosting pattern lets your application implement only the protocol endpoints and policies it needs; it doesn't attempt to implement the complete API surface of every supported protocol.

Next steps

Go deeper:

• Telegram
• A2A
• MCP
• Foundry Hosted Agents