Universal.Operative.Sdk 5.0.1

About

Universal.Operative.Sdk is the shared kernel for the Universal.Operative.Sdk family: the provider-neutral content model (Block and its subtypes, Source, Citation), the tool-calling contract (ITool, Tool<TArgs>, ToolResult, ToolDefinition, ToolChoice), token accounting (Usage, ITokenEstimator), and cross-cutting infrastructure (IDiagnosticSink). It also ships a baseline tool set (Tools/BaselineTools.cs: Read, Write, Edit, Glob, Grep, a shell, TodoWrite, NotebookEdit) built on those contracts.

None of this assumes a particular execution model — it's reused unchanged by both Universal.Operative.Sdk.Discrete (turn-based: Conversation, Engine, Operative) and Universal.Operative.Sdk.Realtime (live duplex sessions). Install this package alongside whichever of those two matches what you're building; you won't normally install it alone.

How to Use

Installation

dotnet add package Universal.Operative.Sdk
dotnet add package Universal.Operative.Sdk.Discrete   # turn-based agents
# or
dotnet add package Universal.Operative.Sdk.Realtime   # duplex-stream / voice agents

Core concepts

• Block — the provider-neutral content unit (TextBlock, ImageBlock, AudioBlock, DocumentBlock, VideoBlock, ToolCallBlock, ToolResultBlock, ReasoningBlock, RefusalBlock, ServerToolUseBlock/ServerToolResultBlock, RawJsonBlock). Both execution models build their message/event shapes out of these. Source (Base64Source, UrlSource, FileIdSource, TextSource, ContentSource) backs any media-bearing block; Citation (DocumentCitation, UrlCitation) attaches source attribution to a TextBlock.
• ITool / Tool<TArgs> — a callable the model can invoke. Subclass Tool<TArgs> with a typed argument record and a Definition whose Parameters schema is generated straight from that record via BuildParametersSchema(), so the schema the model sees and the type ExecuteAsync deserializes into can't drift apart; 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.
• ToolResult — a tool's output: a Block list plus IsError. Factories Text, Json<T>, Image; implicit conversions from string/Block.
• ToolDefinition — a tool's name, description, and JSON Schema parameters, as sent to a provider; ToolChoice (Auto/Required/None/Tool) controls whether/which tool the model must call.
• Usage — token accounting (InputTokens, OutputTokens, provider-specific Extensions), reused by both a turn-based Message.Usage and a realtime session's usage events. ITokenEstimator (default: CharHeuristicTokenEstimator) estimates the token footprint of a Block/text for budget-aware transformers.
• IDiagnosticSink — a seam for the SDK to surface internal notices (a dropped stream block, an abandoned tool call) without taking a dependency on any particular logging library.

Writing a custom tool

using System.ComponentModel;
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 = BuildParametersSchema(),
    };

    public sealed record Args
    {
        [JsonPropertyName("city")]
        [Description("The city to get the weather for.")]
        public required string City { get; init; }
    }

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

BuildParametersSchema() reflects over Args: [JsonPropertyName] controls each parameter's wire name, [Description] becomes the text the model sees for it, and required string/[Required] marks it mandatory. Use a real C# enum (not a loosely-typed string) for any parameter with a closed set of valid values. Parameters is a Universal.Common.Json.JsonSchema, so a hand-authored schema still works when reflection can't express the shape you need (e.g. oneOf/$ref). IsConcurrencySafe = true marks a read-only tool as safe to run in parallel with other calls in the same turn/session; mutating tools default to false.

A tool whose work can outlive a single call implements IBackgroundTool (most conveniently via BackgroundTool<TArgs>) — see ShellTool for a worked example.

HTTP proxy tools

A tool that just calls an external REST API can subclass HttpProxyTool<TArgs> instead of hand-rolling ExecuteAsync — it owns the build → send → format template; a subclass overrides BuildRequestAsync and, optionally, FormatResponseAsync. HttpClientProxyTool<TArgs> is the plain-HttpClient implementation. Pair this with Universal.Operative.Sdk.Http's HttpServiceClientProxyTool<TServiceClient, TArgs> when the target API already has a Universal.Common.Net.Http.HttpServiceClient.

References

ReferenceTool fetches whatever content a reference URI points to, via a registered IReferenceResolver (InMemoryReferenceResolver is the built-in default). It's deliberately generic — the tool carries no opinion about what a reference is; it only resolves a URI to IReadOnlyList<Block> content.

License

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