HPD-Agent.Toolkit.FileSystem 0.3.2

HPD-Agent Framework

<picture> <source media="(prefers-color-scheme: dark)" srcset="architecture-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="architecture.svg"> <img alt="HPD-Agent Architecture" src="architecture.svg"> </picture>

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):

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

Documentation