ASP.NET Hosting

ASP.NET Core hosting turns an agent runtime into HTTP endpoints for sessions, branches, content, streaming, middleware responses, and stored agent definitions.

Use hosting when a web app, TypeScript client, TUI, or another process needs to talk to HPD Agent over a boundary.

Create A Web App

dotnet new web -n HpdAgentHost
cd HpdAgentHost
dotnet add package HPD-Agent.AspNetCore --version 0.5.0
dotnet add package HPD-Agent.Providers.OpenAI --version 0.5.0

Set an OpenAI API key:

export OPENAI_API_KEY="..."

Add Program.cs

using HPD.Agent;
using HPD.Agent.AspNetCore;
using HPD.Agent.Hosting.Configuration;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRouting();

builder.Services.AddHPDAgent("getting-started-agent", config =>
{
    var dataRoot = Path.Combine(Directory.GetCurrentDirectory(), ".hpd-hosting");

    config.SessionStorePath = Path.Combine(dataRoot, "sessions");
    config.AgentStore = new JsonAgentStore(Path.Combine(dataRoot, "agents"));
    config.PersistAfterTurn = true;

    config.DefaultAgent = new AgentConfig
    {
        Name = "Getting Started Agent",
        SystemInstructions = "You are a hosted HPD Agent. Be concise and helpful.",
        Clients = new AgentClientConfig
        {
            Chat = new ClientProviderConfig
            {
                ProviderKey = "openai",
                ModelName = "gpt-5-mini"
            }
        }
    };
});

var app = builder.Build();

app.MapGet("/", () => "HPD Agent is hosted.");

app.MapGroup("/hpd").MapHPDAgentApi("getting-started-agent", options =>
{
    options.MapEvals = false;
});

app.Run();

Run it:

dotnet run

Verify the host is listening:

curl http://localhost:5000/

Expected:

HPD Agent is hosted.

Before exposing hosted routes outside local development, decide how your app will handle authentication, authorization, CORS, storage durability, rate limits, and streaming client lifecycle.

What Happens

AddHPDAgent(...) registers a named hosted runtime.

SessionStorePath creates a JsonSessionStore for hosted sessions and branches.

AgentStore stores reusable hosted agent definitions. This sample uses JsonAgentStore.

DefaultAgent is the fallback agent definition used when a client talks to an agent id that does not already exist in the agent store.

MapHPDAgentApi(...) maps the built-in HPD Agent endpoints under /hpd.

The hosting layer owns persistence and passes the configured stores to runtimes as requests arrive. Configure stores through hosting options rather than creating separate stores inside ConfigureAgent.

When a hosted input request arrives, hosting resolves the route agentId, starts the branch runtime if needed, and queues the input into that runtime. That active runtime is what live events, middleware responses, client tools, permissions, interruptions, SSE, and WebSocket streams attach to. For the direct-run versus started-runtime model, see Agent Runtime And Capabilities.

Next

At this point, the first path is complete: build an agent, stream it, add a tool, keep session history, save state, and host the runtime.

Choose a next track:

Track	Start Here
Build a web client	Hosted Streaming API and TypeScript Client Events
Add real tool surfaces	Author A Tool Harness, MCP Tools, and OpenAPI Tools
Add safety and control	Middleware Overview and Permissions Middleware
Add orchestration	Subagents and Multi-Agent Overview
Ship the runtime	ASP.NET Core Hosting, Stored Agent Definitions, and Logging And Telemetry

For a short orchestration tutorial, continue to Build A Multi-Agent Workflow.