HPD-Agent.Framework 0.9.1

HPD-Agent.Framework

A middleware-driven agentic AI framework built on Microsoft.Extensions.AI for building intelligent, tool-using agents.

Thread-scoped event subscriptions

Subscriptions without a thread key observe only events owned by that Agent instance. They include the agent's per-run coordinators, but exclude events originating in independently owned subagents:

using var local = agent.Subscribe<TextDeltaEvent>(evt => Console.Write(evt.Text));

Use the complete (SessionId, ThreadId) key to observe one concrete child invocation:

var child = new ThreadKey(childSessionId, childThreadId);
using var exact = agent.Subscribe<TextDeltaEvent>(child, evt => Console.Write(evt.Text));

Request hierarchy explicitly to supervise an entire branch at every depth. Sibling branches are excluded, and each delivery retains its root-to-origin route:

using var subtree = agent.SubscribeAny(
    child,
    AgentEventHierarchy.ThreadAndDescendants,
    evt => Observe(evt));

Thread-keyed subscriptions exclude threadless events. Live descendant delivery multiplexes events from independent thread journals; it does not merge their journal cursors. Callbacks run on the subscription's mailbox pump, publication does not wait for callback completion, and disposal stops observation without stopping execution or event bubbling. Framework infrastructure that truly needs every owner must opt into global observation explicitly.

Install

dotnet add package HPD-Agent.Framework

Use When

Use this package when you need this HPD Agent capability in an agent application.

Event composition

Agent events need one immutable application schema so live events, durable thread journals, replay, and source-generated Native AOT metadata agree. Applications usually do not configure this manually:

• An executable or a project with HpdAgentApplication=true generates and auto-registers one complete application composition.
• A library generates and auto-registers its own event module. When no full application composition is present, AgentBuilder composes the loaded generated modules automatically.
• Select with WithEventApplicationIdentity(...) only when multiple generated applications are loaded into one process.
• Supply WithEventComposition(...) for a custom or intentionally core-only event surface.

Use the builder's session-store helpers, such as WithInMemorySessionStore() or WithFileSessionStore(path), so the store is created with the selected composition's codec. A manually created store must use that same codec.

Pre-1.0 API Evolution

HPD-Agent is still pre-1.0. Until 1.0.0, minor and patch releases may refine public APIs, persistence shapes, and hosting contracts as the framework settles. The current conversation model is session-owned threads with event-sourced thread history.

Session Fork Graph

Use ThreadForkGraph.BuildVisibleForkGroups(...) when rendering thread/fork navigation. Thread.ForkedFrom is direct lineage; fork groups are semantic choice points derived from the shared conversation boundary.

See Session/THREAD_FORK_GRAPH.md.