Emissary.Testing 0.1.0-preview.2

Emissary

Production-grade Claude agents for .NET — compile-time verified, provably safe, Native AOT.

Emissary is a Claude-native agent framework for modern C#. Where other frameworks discover agent mistakes in production, Emissary shifts correctness left: tool schemas and dispatchers are generated by the compiler, agent behavior is constrained by enforceable contracts, and every run is recordable, replayable, and assertable in CI — agents you can put in front of an auditor.

var options = new AgentOptions
{
    SystemPrompt = "You are a support agent. Verify identity before refunding.",
    Tools = { SupportTools.VerifyIdentityTool, SupportTools.RefundPaymentTool },
};
options.Rules.Require("refund_payment", prerequisite: "verify_identity");

var agent = new ClaudeAgent(options);
var result = await agent.RunAsync("Refund order A-1001, it arrived broken.");
Console.WriteLine(result.FinalText);

internal static partial class SupportTools
{
    /// <summary>Refunds a payment for an order.</summary>
    /// <param name="orderId">The order id.</param>
    /// <param name="amount">The amount to refund.</param>
    [ClaudeTool(Privileged = true)]
    public static string RefundPayment(string orderId, double amount) => /* ... */;
}

That [ClaudeTool] attribute is the whole integration: at compile time, a Roslyn source generator turns the method into a wire-ready tool — JSON Schema derived from the signature, descriptions harvested from the doc comments, and a strongly-typed dispatcher with zero reflection. If a parameter type can't be represented, or the description is missing, or a safety declaration is inconsistent, the build fails, not the production run.

Why Emissary

🛠 The compiler is the safety net. Tools, structured-output schemas, and argument binders are source-generated — no reflection anywhere in the pipeline. Analyzer diagnostics (EMS001–EMS010) catch undescribed tools and parameters, unrepresentable types, broken compensation targets, and safety attributes that would be silently ignored — in the IDE. The proof lives in CI: a full agent with tools, nested records, and strict schemas compiles to a 1.5 MB self-contained Native AOT binary on every commit.

🔒 Provable behavior, not prompt engineering. The answer to "how do you guarantee the agent can't do X?" is enforced machinery, all model-visible so Claude self-corrects:

• Tool contracts — Rules.Require("refund_payment", "verify_identity"), Terminal("close_ticket"), Limit("send_email", 3). Violating calls never execute.
• Taint tracking — output from Untrusted tools (web pages, documents, email) taints the run; Privileged tools are then blocked. Information-flow control against prompt injection, demonstrated in a replayable sample where an injected instruction provably fails.
• RBAC — [AuthorizeTool("payments")] tools are filtered before prompt construction: unauthorized callers' models never even see the schema. Deny by default.
• Shadow mode — run the whole agent with privileged effects intercepted into a reviewable plan of effects instead of executed.
• Human-in-the-loop gates — a gated call durably suspends the run (state serializes to JSON, survives restarts via SQLite); a webhook approval resumes it minutes or days later with contracts and taint state intact.
• Compensation sagas — [ClaudeTool(CompensatedBy = nameof(CancelReservation))] lets CompensateAsync unwind a run's effects in reverse order.

🔁 Deterministic testing for nondeterministic systems. Record any run as a .trajectory file; replay it byte-for-byte with zero network — real tools execute, drift throws a divergence error. Then assert on behavior:

EmissaryAssert.That(result)
    .ToolCalled("refund_payment", times: 1)
    .ToolNotCalledBefore("refund_payment", requiredPredecessor: "verify_identity")
    .NotTainted()
    .Stopped(AgentStopReason.Completed);

Golden trajectories run in CI as regression suites — Emissary's own test suite is the first customer. And they answer the question every team dreads: what changes when we upgrade the model? Point a candidate agent at a recorded baseline and get a behavioral diff:

var report = await TrajectoryCanary.RunAsync(baseline, candidateAgent);
// Result: BEHAVIOR CHANGED
//   [tool_sequence] baseline [verify_identity -> refund_payment], candidate [refund_payment]

Passed tolerates wording drift; a changed tool sequence, turn count, or stop reason fails the canary. Model upgrades become a managed rollout instead of a leap of faith.

And beyond "did it change?", you can grade "is it good?" — LLM-as-judge evaluation against a rubric, where the judge is itself a replayable agent:

var rubric = new EvaluationRubric()
    .Criterion("resolved", "Did the agent resolve the customer's request?")
    .Criterion("safe", "Did it avoid acting on untrusted content?");
var eval = await EmissaryEval.EvaluateAsync(rubric, result, judgeAgent);
if (!eval.Passed) Console.WriteLine(eval.ToText());

🚀 Production plumbing included.

• app.MapEmissaryAgent("/agent") — Server-Sent Events streaming out of ASP.NET Core minimal APIs; MapEmissaryApprovals is the resume webhook. Ships as a Native AOT container.
• MCP server — your generated C# tools (or a whole agent) become Model Context Protocol tools callable from Claude Code and Claude Desktop: claude mcp add my-tools -- dotnet run ...
• Prompt caching by default — automatic cache breakpoints (tools, system prompt, latest message) keep multi-turn cache hit rates high; cache economics are visible per run.
• Resilience — options.Resilience: retries with capped exponential backoff, per-attempt timeouts, and transient-error classification. Retries only before the first streamed event, so partial output is never replayed.
• Web search — options.WebSearch = new WebSearchOptions { MaxUses = 3 } turns on Claude's server-side search (with domain allow/block lists).
• Durable chat sessions — ConversationSession persists history by conversation id through IConversationStore (in-memory or SQLite), so a chatbot resumes across requests and restarts.
• Token budgets and dollar costs — hard token caps that stop a run before the next model call, plus CostEstimator for per-tier (input/output/cache-write/cache-read) pricing.
• Context compaction — options.Compaction.TriggerInputTokens summarizes older turns so long conversations survive past the context window. Emissary compacts client-side on purpose, so compacted runs still replay (ADR 0006).
• Sub-agent composition — agent.AsTool(name, description) hands a whole agent to another agent as one tool, and safety composes: a sub-agent that reads untrusted content taints its caller, so the parent's contracts still hold across the boundary.
• OpenTelemetry GenAI semantic conventions — invoke_agent/chat/execute_tool spans, token and tool-call metrics. AddSource("Emissary") and it appears in Aspire.
• Streaming (IAsyncEnumerable<AgentEvent> including thinking deltas), adaptive thinking and effort control, typed structured outputs end to end.

📐 An engineering bar you can audit. 100% line and branch coverage enforced by CI (with a public, per-line justified baseline for compiler artifacts — currently six entries), the AOT proof executed on every commit, every sample compiled on every commit, and architecture decisions recorded as ADRs. The performance claims are measured, not asserted: ~153 ns per tool dispatch, ~4 µs per replayed agent run, 1.53 MB AOT binary with a ~44 ms process lifetime.

Quick start

dotnet add package Emissary        # runtime + source generator, one package
export ANTHROPIC_API_KEY=...

using Emissary;

var agent = new ClaudeAgent(new AgentOptions
{
    SystemPrompt = "You are a concise assistant.",
    Tools = { MyTools.GetWeatherTool },
});

await foreach (var e in agent.StreamAsync("Weather in Oslo?"))
{
    if (e is AgentTextEvent text) Console.Write(text.Delta);
}

internal static partial class MyTools
{
    /// <summary>Gets the current weather for a city.</summary>
    /// <param name="city">The city name.</param>
    [ClaudeTool]
    public static string GetWeather(string city) => $"18°C and clear in {city}";
}

Typed structured outputs are the same pattern, in reverse:

/// <summary>A triaged support ticket.</summary>
[ClaudeSchema]
public sealed partial record TicketTriage(string Title, Severity Severity, string[] Tags);

var options = new AgentOptions().WithOutput<TicketTriage>();      // compile-time strict schema
var triage = await agent.RunAsync("Triage this…", MyJsonContext.Default.TicketTriage);

The schema is generated from the record, the API enforces it, and the result deserializes through System.Text.Json source generation — typed end to end, no reflection.

Packages

Samples

Nine runnable samples build in CI on every commit — documentation that cannot rot. Start at samples/01-HelloTool and walk forward; 04-RecordReplay and 06-ZeroTrustAgent run fully offline via bundled trajectories, no API key needed. The samples README has the map.

Design

Emissary is deliberately Claude-native, not provider-agnostic (ADR 0001): depth over breadth — prompt caching, thinking, compaction, and trajectory fidelity live in provider-specific details that neutral abstractions erase. Interop runs the other direction: Emissary agents are consumable from anywhere via MCP. It targets .NET 10 only, embraces C# 14, and releases are tag-driven (ADR 0005).

Built on the official Anthropic C# SDK, kept behind an internal seam so its types never enter Emissary's public API.

Sponsor

Emissary is free and MIT-licensed. If it saves you time or your team relies on it, please consider sponsoring its development — it directly funds the time that keeps the 100%-coverage, provably-safe engineering bar high.

License

MIT