HPD-Agent Framework

A full-stack framework for building AI agents — C# backend with tools, middleware, multi-turn conversations, and multi-agent workflows, paired with TypeScript/Svelte UI libraries for building rich, streaming chat interfaces.

Install

dotnet add package HPD-Agent.Framework

Quick Start

using HPD.Agent;

var agent = new AgentBuilder()
    .WithProvider("openai", "gpt-4o")
    .WithSystemInstructions("You are a helpful assistant.")
    .Build();

await foreach (var evt in agent.RunAsync("Hello!"))
{
    if (evt is TextDeltaEvent textDelta)
        Console.Write(textDelta.Text);
}

Core Concepts

Tools

Give your agent capabilities by registering toolkits:

public class CalculatorToolkit
{
    [AIFunction(Description = "Add two numbers")]
    public int Add(int a, int b) => a + b;
}

var agent = new AgentBuilder()
    .WithProvider("openai", "gpt-4o")
    .WithToolkit<CalculatorToolkit>()
    .Build();

Tools can also be loaded from MCP servers, OpenAPI specs, or provided by the client at runtime. See Tools documentation.

Multi-Turn Conversations

Use sessions and branches to maintain conversation history:

var (session, branch) = agent.CreateSession("user-123");

await foreach (var evt in agent.RunAsync("Add 10 and 20", branch)) { }
await foreach (var evt in agent.RunAsync("Now multiply that by 5", branch)) { }
// Agent remembers the previous result

For persistent conversations that survive process restarts:

var agent = new AgentBuilder()
    .WithSessionStore(new JsonSessionStore("./sessions"))
    .Build();

await foreach (var evt in agent.RunAsync("Message", sessionId: "user-123")) { }

See 02 Multi-Turn Conversations.

Middleware

Intercept and customize agent behavior at every stage of execution:

public class LoggingMiddleware : IAgentMiddleware
{
    public Task BeforeFunctionAsync(AgentMiddlewareContext context, CancellationToken ct)
    {
        Console.WriteLine($"Calling: {context.Function?.Name}");
        return Task.CompletedTask;
    }
}

var agent = new AgentBuilder()
    .WithProvider("openai", "gpt-4o")
    .WithMiddleware(new LoggingMiddleware())
    .Build();

Built-in middleware includes: CircuitBreaker, RetryMiddleware, HistoryReduction, PIIMiddleware, FunctionTimeout, Logging, and more. See Middleware documentation.

Agent Configuration

The recommended pattern for production is Builder + Config — define configuration as data, then layer runtime customization on top:

// Define config once (can also be loaded from JSON)
var config = new AgentConfig
{
    Name = "SupportAgent",
    SystemInstructions = "You are a support assistant.",
    Provider = new ProviderConfig { ProviderKey = "openai", ModelName = "gpt-4o" },
    MaxAgenticIterations = 15,
    Toolkits = ["KnowledgeToolkit"],
    Middlewares = ["LoggingMiddleware"]
};

// Layer runtime-only concerns on top
var agent = new AgentBuilder(config)
    .WithServiceProvider(services)
    .WithToolkit<MyCompiledTool>()
    .Build();

Or load directly from a JSON file:

var agent = new AgentBuilder("agent-config.json")
    .WithServiceProvider(services)
    .Build();

See 01 Customizing an Agent.

Multi-Agent Workflows

Compose multiple specialized agents in a directed graph:

using HPD.MultiAgent;

var workflow = await AgentWorkflow.Create()
    .AddAgent("researcher", new AgentConfig
    {
        SystemInstructions = "Research the topic thoroughly."
    })
    .AddAgent("writer", new AgentConfig
    {
        SystemInstructions = "Write a clear, concise answer."
    })
    .From("researcher").To("writer")
    .BuildAsync();

var result = await workflow.RunAsync("Explain quantum entanglement");
Console.WriteLine(result.FinalAnswer);

Edges can be conditional, routing based on agent output fields:

.From("triage")
    .To("billing", when => when.Field("intent").Equals("billing"))
    .To("support", when => when.Field("intent").Equals("support"))
    .To("fallback")

See Multi-Agent documentation.

Event Streaming

Agents stream events as they work — text output, tool calls, turn lifecycle, and more:

await foreach (var evt in agent.RunAsync("Do something", branch))
{
    switch (evt)
    {
        case TextDeltaEvent textDelta:
            Console.Write(textDelta.Text);
            break;
        case ToolCallStartEvent toolCall:
            Console.WriteLine($"\n[Tool: {toolCall.Name}]");
            break;
        case TurnCompletedEvent:
            Console.WriteLine("\n[Done]");
            break;
    }
}

See 05 Event Handling.

Building Apps

Console apps — See 07 Building Console Apps
Web apps (ASP.NET Core) — See 08 Building Web Apps

TypeScript Libraries

Two companion packages for building frontends that connect to an HPD-Agent backend.

`@hpd/hpd-agent-client`

A lightweight, zero-dependency TypeScript client for consuming the agent's event stream. Works in both browser and Node.js.

npm install @hpd/hpd-agent-client

import { AgentClient } from '@hpd/hpd-agent-client';

const client = new AgentClient('https://your-api/agent');

await client.stream('Explain quantum entanglement', {
    onTextDelta: (evt) => process.stdout.write(evt.text),
    onToolCallStart: (evt) => console.log(`Tool: ${evt.name}`),
    onError: (err) => console.error(err),
});

The client supports SSE (default), WebSocket, and Maui transports, and handles bidirectional flows for permissions, clarifications, continuations, and client-side tool invocation. It covers all 71 HPD protocol event types.

`@hpd/hpd-agent-headless-ui`

A Svelte 5 headless component library for building AI chat interfaces. Zero CSS — you control all styling. Designed specifically for AI-specific primitives: streaming text, tool execution, permissions, branching, and voice.

npm install @hpd/hpd-agent-headless-ui

<script>
  import { createMockAgent } from '@hpd/hpd-agent-headless-ui';

  const agent = createMockAgent();
  let input = '';

  async function send() {
    await agent.send(input);
    input = '';
  }
</script>

Key components (not exhaustive — see typescript/ for the full library):

Component	Purpose
`Message` / `MessageList`	Streaming-aware message display with thinking, tool, and reasoning states
`MessageActions`	Edit, retry, and copy buttons attached to messages
`MessageEdit`	Inline message editing with save/cancel
`ChatInput`	Compositional input with leading/trailing/top/bottom accessory slots
`ToolExecution`	Display and track in-progress tool calls
`PermissionDialog`	Handle AI permission requests
`BranchSwitcher`	Navigate sibling conversation branches
`SessionList`	Display and manage conversation sessions
`Artifact`	Teleport rich content (code, documents, charts) into a side panel
`SplitPanel`	Arbitrarily nested resizable layout panels with persistence and undo/redo
`AudioPlayer` / `Transcription`	Voice playback and speech-to-text streaming
`VoiceActivityIndicator`	Visual feedback during voice input
`AudioVisualizer`	Waveform/level visualization for audio streams
`InterruptionIndicator` / `TurnIndicator`	Voice turn and interruption state display
`Input`	Base AI-aware message input primitive

Total bundle: < 20 KB gzipped. Located at typescript/.

Documentation

Topic	Location
Agents overview & first steps	Getting Started/
Agent configuration	01 Customizing an Agent
Multi-turn conversations & sessions	02 Multi-Turn Conversations
Tool calling	03 Tool Calling
Middleware pipeline	Middleware/
Event handling	05 Event Handling
Memory & content store	06 Memory & Content Store
Multi-agent workflows	Multi-Agent/
Per-invocation run config	09 Run Config

HPD-Agent Framework

Install

dotnet add package HPD-Agent.Framework

Quick Start

using HPD.Agent;

var agent = new AgentBuilder()
    .WithProvider("openai", "gpt-4o")
    .WithSystemInstructions("You are a helpful assistant.")
    .Build();

await foreach (var evt in agent.RunAsync("Hello!"))
{
    if (evt is TextDeltaEvent textDelta)
        Console.Write(textDelta.Text);
}

Core Concepts

Tools

Give your agent capabilities by registering toolkits:

public class CalculatorToolkit
{
    [AIFunction(Description = "Add two numbers")]
    public int Add(int a, int b) => a + b;
}

var agent = new AgentBuilder()
    .WithProvider("openai", "gpt-4o")
    .WithToolkit<CalculatorToolkit>()
    .Build();

Tools can also be loaded from MCP servers, OpenAPI specs, or provided by the client at runtime. See Tools documentation.

Multi-Turn Conversations

Use sessions and branches to maintain conversation history:

var (session, branch) = agent.CreateSession("user-123");

await foreach (var evt in agent.RunAsync("Add 10 and 20", branch)) { }
await foreach (var evt in agent.RunAsync("Now multiply that by 5", branch)) { }
// Agent remembers the previous result

For persistent conversations that survive process restarts:

var agent = new AgentBuilder()
    .WithSessionStore(new JsonSessionStore("./sessions"))
    .Build();

await foreach (var evt in agent.RunAsync("Message", sessionId: "user-123")) { }

See 02 Multi-Turn Conversations.

Middleware

Intercept and customize agent behavior at every stage of execution:

public class LoggingMiddleware : IAgentMiddleware
{
    public Task BeforeFunctionAsync(AgentMiddlewareContext context, CancellationToken ct)
    {
        Console.WriteLine($"Calling: {context.Function?.Name}");
        return Task.CompletedTask;
    }
}

var agent = new AgentBuilder()
    .WithProvider("openai", "gpt-4o")
    .WithMiddleware(new LoggingMiddleware())
    .Build();

Built-in middleware includes: CircuitBreaker, RetryMiddleware, HistoryReduction, PIIMiddleware, FunctionTimeout, Logging, and more. See Middleware documentation.

Agent Configuration

The recommended pattern for production is Builder + Config — define configuration as data, then layer runtime customization on top:

// Define config once (can also be loaded from JSON)
var config = new AgentConfig
{
    Name = "SupportAgent",
    SystemInstructions = "You are a support assistant.",
    Provider = new ProviderConfig { ProviderKey = "openai", ModelName = "gpt-4o" },
    MaxAgenticIterations = 15,
    Toolkits = ["KnowledgeToolkit"],
    Middlewares = ["LoggingMiddleware"]
};

// Layer runtime-only concerns on top
var agent = new AgentBuilder(config)
    .WithServiceProvider(services)
    .WithToolkit<MyCompiledTool>()
    .Build();

Or load directly from a JSON file:

var agent = new AgentBuilder("agent-config.json")
    .WithServiceProvider(services)
    .Build();

See 01 Customizing an Agent.

Multi-Agent Workflows

Compose multiple specialized agents in a directed graph:

using HPD.MultiAgent;

var workflow = await AgentWorkflow.Create()
    .AddAgent("researcher", new AgentConfig
    {
        SystemInstructions = "Research the topic thoroughly."
    })
    .AddAgent("writer", new AgentConfig
    {
        SystemInstructions = "Write a clear, concise answer."
    })
    .From("researcher").To("writer")
    .BuildAsync();

var result = await workflow.RunAsync("Explain quantum entanglement");
Console.WriteLine(result.FinalAnswer);

Edges can be conditional, routing based on agent output fields:

.From("triage")
    .To("billing", when => when.Field("intent").Equals("billing"))
    .To("support", when => when.Field("intent").Equals("support"))
    .To("fallback")

See Multi-Agent documentation.

Event Streaming

Agents stream events as they work — text output, tool calls, turn lifecycle, and more:

await foreach (var evt in agent.RunAsync("Do something", branch))
{
    switch (evt)
    {
        case TextDeltaEvent textDelta:
            Console.Write(textDelta.Text);
            break;
        case ToolCallStartEvent toolCall:
            Console.WriteLine($"\n[Tool: {toolCall.Name}]");
            break;
        case TurnCompletedEvent:
            Console.WriteLine("\n[Done]");
            break;
    }
}

See 05 Event Handling.

Building Apps

Console apps — See 07 Building Console Apps
Web apps (ASP.NET Core) — See 08 Building Web Apps

TypeScript Libraries

Two companion packages for building frontends that connect to an HPD-Agent backend.

`@hpd/hpd-agent-client`

A lightweight, zero-dependency TypeScript client for consuming the agent's event stream. Works in both browser and Node.js.

npm install @hpd/hpd-agent-client

import { AgentClient } from '@hpd/hpd-agent-client';

const client = new AgentClient('https://your-api/agent');

await client.stream('Explain quantum entanglement', {
    onTextDelta: (evt) => process.stdout.write(evt.text),
    onToolCallStart: (evt) => console.log(`Tool: ${evt.name}`),
    onError: (err) => console.error(err),
});

`@hpd/hpd-agent-headless-ui`

npm install @hpd/hpd-agent-headless-ui

<script>
  import { createMockAgent } from '@hpd/hpd-agent-headless-ui';

  const agent = createMockAgent();
  let input = '';

  async function send() {
    await agent.send(input);
    input = '';
  }
</script>

Key components (not exhaustive — see typescript/ for the full library):

Component	Purpose
`Message` / `MessageList`	Streaming-aware message display with thinking, tool, and reasoning states
`MessageActions`	Edit, retry, and copy buttons attached to messages
`MessageEdit`	Inline message editing with save/cancel
`ChatInput`	Compositional input with leading/trailing/top/bottom accessory slots
`ToolExecution`	Display and track in-progress tool calls
`PermissionDialog`	Handle AI permission requests
`BranchSwitcher`	Navigate sibling conversation branches
`SessionList`	Display and manage conversation sessions
`Artifact`	Teleport rich content (code, documents, charts) into a side panel
`SplitPanel`	Arbitrarily nested resizable layout panels with persistence and undo/redo
`AudioPlayer` / `Transcription`	Voice playback and speech-to-text streaming
`VoiceActivityIndicator`	Visual feedback during voice input
`AudioVisualizer`	Waveform/level visualization for audio streams
`InterruptionIndicator` / `TurnIndicator`	Voice turn and interruption state display
`Input`	Base AI-aware message input primitive

Total bundle: < 20 KB gzipped. Located at typescript/.

Documentation

Topic	Location
Agents overview & first steps	Getting Started/
Agent configuration	01 Customizing an Agent
Multi-turn conversations & sessions	02 Multi-Turn Conversations
Tool calling	03 Tool Calling
Middleware pipeline	Middleware/
Event handling	05 Event Handling
Memory & content store	06 Memory & Content Store
Multi-agent workflows	Multi-Agent/
Per-invocation run config	09 Run Config

ewoofcoding/HPDAgent.Graph.Corev0.3.0

Get Started

Readme

HPD-Agent Framework

Install

Quick Start

Core Concepts

Tools

Multi-Turn Conversations

Middleware

Agent Configuration

Multi-Agent Workflows

Event Streaming

Building Apps

TypeScript Libraries

`@hpd/hpd-agent-client`

`@hpd/hpd-agent-headless-ui`

Documentation

ewoofcoding/HPDAgent.Graph.Corev0.3.0

Get Started

Readme

HPD-Agent Framework

Install

Quick Start

Core Concepts

Tools

Multi-Turn Conversations

Middleware

Agent Configuration

Multi-Agent Workflows

Event Streaming

Building Apps

TypeScript Libraries

`@hpd/hpd-agent-client`

`@hpd/hpd-agent-headless-ui`

Documentation