Universal.Operative.Sdk 2.0.0

About

Universal.Operative.Sdk is a provider-neutral framework for building long-running, agentic LLM-driven applications. It defines the domain model (Conversation, Message, content Blocks), the extension seams (IModel, ITool, ITransformer), and two complementary building blocks that sit on top of them: an Engine, which drives a single agentic turn end-to-end (stream a model response, dispatch any tool calls, feed results back, loop until the model stops), and an Operative, which wraps an Engine around one ongoing Conversation and decides whether a new inbound message starts a fresh turn or steers into one already running. Pair it with Universal.Operative.Sdk.Anthropic or Universal.Operative.Sdk.OpenAI for a concrete IModel.

How to Use

Installation

dotnet add package Universal.Operative.Sdk

Quick start: a single turn

Use Engine directly when there's no ongoing session to manage — a one-shot request/response, a batch job, a single CLI invocation.

using Universal.Operative.Sdk;

IModel model = /* an IModel, e.g. from Universal.Operative.Sdk.Anthropic or .OpenAI */;

IEngine engine = EngineBuilder.FromDefaults(model)
    .AddBaselineTools()
    .Build();

var conversation = new Conversation
{
    System = new List<Block> { new TextBlock("You are a helpful assistant.") },
    Messages = { new Message { Role = MessageRoles.User, Content = { new TextBlock("List the files in this repo.") } } },
};

await foreach (EngineEvent e in engine.ExecuteAsync(conversation))
{
    switch (e)
    {
        case ModelStreamEvent s: break;
        case AssistantMessageEvent a: Console.WriteLine(a.Message.Content); break;
        case ToolCallStartedEvent t: Console.WriteLine($"Running {t.Call.Name}..."); break;
        case TurnCompletedEvent done: Console.WriteLine($"Done: {done.Reason}"); break;
    }
}

AddBaselineTools() registers Read, Write, Edit, Glob, Grep, a shell (Bash and/or PowerShell, by availability), TodoWrite, and NotebookEdit. EngineBuilder.FromDefaults wires a pre-transformer stack (boundary-aware history windowing, tool-result budgeting, history snipping, auto-compaction) so long-running conversations don't blow the model's context window; use new EngineBuilder() instead to opt into transformers individually. conversation.Messages holds the full transcript once the turn ends, including tool calls and results.

Quick start: a long-running session

Use IOperative when something outside your control — a chat UI, a Slack app, a webhook — can send a new message while a turn is already running, and you want that message to steer the in-progress turn instead of queuing behind it.

IOperative bot = OperativeBuilder.Create(engine, conversation).Build();

SubmitResult result = await bot.SubmitAsync(
    new Message { Role = MessageRoles.User, Content = { new TextBlock("hi") } });

await foreach (OperativeEvent e in result.Events)
{
    if (e is EngineEventOccurred occurred)
    {
        // same EngineEvent types as the IEngine example above
    }
}

Whether this call started the turn (result.Outcome == SubmitOutcome.StartedTurn) or steered a message into one already running (SubmitOutcome.Injected), result.Events is the same live remainder of that turn either way — one shared consciousness: every caller who touched a turn sees its real outcome, not just whoever happened to start it. Call bot.ResumeAsync() to continue the conversation with no new input at all — e.g. after a restart, when the loaded conversation already ends in an unanswered message; if a turn is already running this joins it too (SubmitOutcome.AlreadyRunning) rather than starting a redundant second one.

Two OperativeBuilder options worth knowing:

• .WithReloadBeforeStart(reload) — reload the conversation from durable storage immediately before each turn starts, so a previous turn that crashed mid-flight self-heals instead of wedging every future one. Runs only once a turn has actually been claimed, so it can't race a turn already in flight.
• .WithFrameInjectedMessage(frame) — customize (or disable) the note prefixed to a message before it's steered into someone else's in-progress turn.

Core concepts

• Conversation / Message / Block — the provider-neutral transcript. Message.Content is a list of Blocks (TextBlock, ToolCallBlock, ToolResultBlock, …); round-tripping a Conversation through JSON is enough to resume it later.
• IModel — the seam to a concrete provider. Implement StreamAsync to translate a Conversation into a provider request and its response stream into StreamEvents; CompleteAsync is provided for free as a fold over the stream.
• ITool / Tool<TArgs> — a callable the model can invoke. Subclass Tool<TArgs> with a typed argument record and a hand-authored JSON-Schema Definition; the base class handles (de)serialization and turns malformed arguments into a model-readable error instead of an exception. See Tools/BaselineTools.cs and Tools/FileSystem/GlobTool.cs for worked examples.
• ITransformer — rewrites the conversation (or shared IContext) around a model call — compaction, tool-result pruning, history snipping. Engine runs four stages: BeforeTurnTransformers once before the turn's first iteration, BeforeIterationTransformers before each model call, AfterIterationTransformers after the assistant message lands but before tools run, and AfterTurnTransformers once after the loop ends.
• Engine / IEngine — drives one turn to completion, exactly as shown above. Every step is a protected virtual method, so subclass to override one piece (tool-result formatting, dispatch policy, timeouts) without reimplementing the whole turn. An Engine holds no session state of its own — one Engine (one model/tool/transformer configuration) is meant to be reused across many independent IOperative sessions, the same way one IModel is reused across many engines.
• OperativeBuilder / Operative / IOperative — owns one ongoing Conversation and single-flight-serialises turns against it through an Engine. SubmitAsync starts a fresh turn if none is running, or steers a new message into the turn already in flight if one is; ResumeAsync continues the conversation with no new input. Build one through OperativeBuilder, not the Operative constructor directly.
• EngineEvent — the observable channel for one turn, as driven directly by IEngine.ExecuteAsync: model stream events, the settled assistant message, tool start/complete/error events, the synthesized tool-result message, transformer applications, and a terminal TurnCompletedEvent.
• OperativeEvent — what IOperative.SubmitAsync/ResumeAsync's SubmitResult.Events actually yields. EngineEventOccurred relays an underlying EngineEvent as-is; MessageQueuedForNextTurnEvent is IOperative-only — it fires when a message arrives too late for the engine's own mid-turn drain to catch, so IOperative appends it directly instead of losing it, ready for the next turn to answer. Kept separate from EngineEvent because IEngine has no notion of IOperative and is fully usable without one.
• Session isolation — one IOperative is one conversation; every message submitted to it shares that same history and turn. If two channels or two users need to stay unaware of each other, give each its own IOperative (e.g. a Dictionary<string, IOperative> keyed by user/channel/thread) rather than routing everyone through one — the same IEngine (and its model/tools) can safely back any number of them at once, since IEngine holds no session state of its own.

Writing a custom tool

using System.Text.Json;
using System.Text.Json.Serialization;
using Universal.Operative.Sdk.Tools;

public sealed class WeatherTool : Tool<WeatherTool.Args>
{
    public override string Name => "get_weather";
    public override bool IsConcurrencySafe => true;

    public override ToolDefinition Definition { get; } = new()
    {
        Name = "get_weather",
        Description = "Get the current weather for a city.",
        Parameters = JsonDocument.Parse("""
            { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
            """).RootElement.Clone(),
    };

    public sealed record Args
    {
        [JsonPropertyName("city")] public string City { get; init; } = string.Empty;
    }

    protected override async Task<ToolResult> ExecuteAsync(Args args, CancellationToken cancellationToken)
        => ToolResult.Json(new { city = args.City, tempF = 72 });
}

IsConcurrencySafe = true marks a read-only tool as safe to run in parallel with other calls in the same turn; mutating tools default to false and run serially in call order. Register a tool with builder.AddTool(new WeatherTool()) and the harness auto-publishes its Definition on outbound messages and dispatches calls to it by name.

Background tool execution

A tool whose work can outlive a single call implements IBackgroundTool (most conveniently via BackgroundTool<TArgs>, which mirrors Tool<TArgs>'s typed-argument split). ShellTool (and so BashTool/PowerShellTool) already does this — pass run_in_background: true in a call's arguments and it hands back a handle instead of running to completion inline.

IEngine engine = new EngineBuilder()
    .WithModel(model)
    .AddBaselineTools()
    .WithBackgroundTasks(new InMemoryBackgroundTaskRegistry())
    .Build();

WithBackgroundTasks does two things: it wires Engine.Options.BackgroundDispatch to route any run_in_background: true call on an IBackgroundTool through the given IBackgroundTaskRegistry instead of running it inline, and it registers TaskOutputTool/TaskStopTool against that same registry so the model can poll or stop what it started, by the task id the initial call returns. Without a registry wired in, run_in_background is simply ignored and every tool runs the ordinary way.

Subagents

AgentTool spawns a subagent — a fresh IEngine run against its own scratch Conversation seeded with a prompt — and returns its final answer, modeled on Claude Code's own subagent tool. It's an IBackgroundTool, so run_in_background: true works the same way as any other background tool.

IEngine SubagentEngineFactory() => new EngineBuilder()
    .WithModel(subagentModel)
    .AddBaselineTools()
    .Build();

builder.AddTool(new AgentTool(SubagentEngineFactory));

A fresh IEngine is requested from the factory for every spawn rather than one shared instance being reused, because transformers that track per-conversation state (a persistence transformer tracking which file it's writing to, for instance) would get confused mixing multiple unrelated spawns through the same instance. The factory is also where an audit trail gets wired up — give the returned engine its own FileSystemConversationPersistenceTransformer pointed at a per-spawn directory to leave an independently reviewable transcript for every subagent run.

License

Free for noncommercial use under the Universal.Operative Noncommercial License. Source is closed; commercial use requires a separate license from Andrew Ong.