Kurrent.Agent.Schema 0.4.1

Kurrent.Agent.Schema

Canonical event schema types for Kurrent agent integrations — schema version 2.

This package is the .NET mirror of the canonical agent event schema shared across Kurrent's agent-framework integrations (Google ADK, Microsoft Agent Framework, Strands, OpenAI Agents, Claude Agent SDK) and Capacitor. The prose specification lives in schema/SCHEMA_v2.md; the Python mirror is kurrent-agent-schema.

Wire format

Backed by Protobuf codegen from schema/proto/. The JSON wire format follows the proto3 canonical mapping with preserve_proto_field_name (snake_case on the wire). The sanctioned JSON entry points are SchemaJsonOptions.ToJson(message) and SchemaJsonOptions.FromJson<T>(src) — direct calls to Google.Protobuf.JsonFormatter are not supported.

What's here

• Canonical event message classes (Kurrent.Agent.Schema.Events, generated from Protobuf): SessionStarted, SessionEnded, SessionContinuedAs, UserMessageReceived, AssistantTextGenerated, AssistantToolCallsGenerated, AssistantThinkingGenerated, ToolResultReceived, InterruptIssued, InterruptResolved, SubagentStarted, SubagentCompleted, FactRetained, ArtifactVersionCreated, EvalRunStarted, TurnScored, EvalRunCompleted.
• Value types: AgentConfig, ToolSpec, ToolCallInfo.
• Usage metadata: TokenUsage + UsageMetadata.Key (the $usage KurrentDB metadata key).
• Stream-name builders: StreamNames.AgentSession, AgentSubsession, AgentMemory, AgentArtifact, EvalRun.
• JSON helpers: SchemaJsonOptions.ToJson(message) / SchemaJsonOptions.FromJson<T>(src) wrap Google.Protobuf.JsonFormatter / JsonParser with preserve_proto_field_name and tolerant-read settings.
• Event-type map: EventTypeMap.GetName(Type) / GetType(string) / All.

What's not here

Framework-specific events (ADK AgentTransferred, AFW WorkflowCheckpoint, Capacitor AgentRunStarted / visibility events) and extensions.{slug} shapes live in their owning integration packages. This package carries only the portable canonical vocabulary.

Usage

using Kurrent.Agent.Schema;
using Kurrent.Agent.Schema.Events;

var evt = new UserMessageReceived {
    Content      = "hello",
    MessageIndex = 0,
    Timestamp    = Google.Protobuf.WellKnownTypes.Timestamp.FromDateTimeOffset(DateTimeOffset.UtcNow),
};

var json = SchemaJsonOptions.ToJson(evt);
var roundTripped = SchemaJsonOptions.FromJson<UserMessageReceived>(json);

var stream = StreamNames.AgentSession("sess-0001"); // "AgentSession-sess-0001"
var eventTypeName = EventTypeMap.GetName(typeof(UserMessageReceived)); // "UserMessageReceived"

Drift guard

Every canonical event has a JSON fixture under schema/fixtures/events/. The test project (Kurrent.Agent.Schema.Tests) runs a round-trip assertion per fixture; an equivalent suite in the Python package runs against the same fixtures. Adding or modifying a canonical field requires a coordinated PR: update both packages and the fixture.

cd schema/dotnet
dotnet test

Version

• Package: 0.4.0 (Protobuf-generated source; see Kurrent.Agent.Schema/CHANGELOG.md for breaking changes).
• Schema: SchemaVersion.Current = 2, stamped on KurrentDB metadata under $schema_version by integration writers.