Proposal: declarative AI agent / chat support — handlers as LLM tools, conversation as saga

[jeremydmiller]

Proposal for a first-class, declarative way to build LLM chat/agent features on Wolverine, so agent workloads get the same durability, observability, and testability as every other message.

Sketch

Handlers as tools. An [AgentTool] attribute on a message type (or handler) generates the LLM tool schema from the message signature — the same reflection/codegen machinery that already builds HTTP endpoint metadata. When the model calls a tool, the call is dispatched as a real Wolverine message through IMessageBus: durable, retried, outbox-enrolled, observable. The agent loop is just another handler chain.

Conversation as a saga. A chat session is stateful, long-lived, and event-driven — exactly what sagas model:

opts.AddAgent<SupportAgent>(a => a
    .Model("claude-sonnet-5")
    .SystemPrompt(...)
    .Tools(typeof(LookupOrder), typeof(IssueRefund)));

Each turn and each tool invocation is a message; the conversation's history is the saga's stream. Streaming deltas ride the existing SignalR transport.

Provider seam. Microsoft.Extensions.AI's IChatClient is the obvious abstraction so Anthropic/OpenAI/local models plug in without Wolverine taking a vendor dependency.

Why in Wolverine rather than app code

• Tool calls that mutate state get the transactional inbox/outbox for free — an agent's side effects stop racing its narration.
• Retries/error policies apply to flaky model calls like any other endpoint.
• Every agent decision is an envelope: correlation/causation chains answer "what did the agent do, what did it see, in what order" with infrastructure that already exists — observability tooling lights up with agent activity with no extra work.
• Handlers-as-tools are unit-testable without a model in the loop, same as handlers-as-handlers.

Open questions

• Loop ownership: does Wolverine run the model-call loop (a built-in agent runtime) or only provide the tool-dispatch + saga plumbing while the app owns the loop?
• Tool-call authorization: per-tool gating analogous to HTTP auth policies.
• Token/streaming ergonomics over SignalR vs. HTTP SSE.
• Whether [AgentTool] schemas should reuse the JSON-schema generation planned/used elsewhere rather than a new generator.

Filed as part of a broader AI-capability planning round; happy to split into smaller issues if the shape survives discussion.

[jeremydmiller]

Design update from planning (2026-09-01) — this issue is now explicitly the tier 2 of a staged design, parked until the tier below it ships:

Tier 1 — WolverineFx.AI, the callout primitive (ships first). An LLM callout is a durable message, not an inline call: LlmCallout.Ask<TResponse>(prompt, context) returned from a handler enqueues an internal message (outbox-enrolled with the triggering write), a Wolverine.AI handler on a dedicated local queue executes it through Microsoft.Extensions.AI's IChatClient.GetResponseAsync<T>(), and the typed response is published as an ordinary cascade. Retries, back-pressure, DLQ, scheduling, and observability are inherited because the callout is an envelope. Decisions of record: publish-only pub/sub all the way down (no request/reply flavour for now); prompts are app-owned; budget enforcement is middleware that DLQs over-budget messages; a stubbed IChatClient + tracked-session assertions ship day one; the core package references nothing beyond Wolverine and the MEAI abstractions package.

Tier 2 — this issue. The agents layer builds on tier 1 and resolves the loop-ownership question via MEAI: FunctionInvokingChatClient owns the model loop; Wolverine owns tool dispatch — [AgentTool] becomes an AIFunction factory over a message type whose invoke is IMessageBus.InvokeAsync, so agent side effects get the inbox/outbox without Wolverine writing a loop. Conversation-as-saga and SignalR streaming stay in scope here. Default home is a separate WolverineFx.AI.Agents package (streaming likely pulls Wolverine.SignalR, and this tier's API will iterate while tier 1 stays stable) — final call when this design settles.

Remaining open here: per-tool authorization, loop termination/budget policy, streaming ergonomics (SignalR vs SSE), schema generation reuse.

[jeremydmiller]

Tier 1 now has its own design issue: #4227 (WolverineFx.AI — LLM callouts as durable messages). This issue stays parked as the tier-2 agents layer on top of it.

[jeremydmiller]

Comparison against Microsoft Agent Framework (2026-09-03) — written while planning Stoat/Wolverine.AI positioning; full note lives at JasperFx/stoat docs/maf-comparison-notes.md. The relevant conclusions for this issue:

The 2026-09-01 tier-2 decision holds up against MAF, and MAF is the strongest argument for it. MAF agents are exactly this layer — model loop + tools + session state — and MAF builds on the same Microsoft.Extensions.AI abstractions this design binds to (IChatClient, AIFunction, AsAIAgent()). So "MEAI's FunctionInvokingChatClient owns the loop, Wolverine owns tool dispatch" lands us one layer below MAF on a shared foundation, rather than beside it on a competing one.

What MAF has under the hood, from its current docs (.NET still --prerelease):

• Workflow execution is in-process (InProcessExecution) — no broker, no cross-node distribution, no back pressure.
• Durability is checkpoint blobs at superstep boundaries (CheckpointManager.CreateInMemory() in the .NET docs; Cosmos for Python, JSON files for Go). No outbox, no transactional tie between an agent's side effects and business data. Executors must hand-implement OnCheckpointingAsync/OnCheckpointRestoredAsync or their state silently isn't in the checkpoint.
• Resume requires identical topology and stable agent Id+Name; the docs' own remedy for a mismatch is "start a new session and checkpoint lineage instead". Python shipped checkpoint-format breaking changes in 1.13.

Three consequences for this design:

1. Don't build on MAF. Preview churn aside, its workflow runtime would be a second orchestration brain in the same process, and its durability story is the thing Wolverine exists to be better at — adopting it trades the outbox for checkpoint blobs.
2. [AgentTool] → AIFunction is already MAF-compatible for free. AIFunction is the currency MAF agents consume, so a MAF ChatClientAgent can be handed Wolverine-dispatched tools as-is — agent side effects get the inbox/outbox even when the loop is MAF's. Their loop, our rails. Worth keeping in mind as tier 2's API settles: nothing extra to build, just don't break the AIFunction shape.
3. A thin adapter (host an AIAgent inside a durable handler) is possible but not worth speculative work — MAF's .NET GA is the trigger to revisit.

Differentiation in one sentence, if the docs ever need it: MAF checkpoints an agent's memory; Wolverine transacts an agent's consequences. Conversation-as-saga is queryable business state in the application's own store; MAF threads are serialized blobs with identity-stability footguns.