agui-dotnet-wire-types

name

agui-dotnet-wire-types

description

Add or modify a wire/protocol type in the AG-UI .NET SDK AGUI.Abstractions package — a new event, message, or content-part type, the AOT source-gen serializer context, or a polymorphic JSON converter, keeping it AOT-safe, JSON-wire-compatible with the TypeScript reference, and PublicAPI-clean. USE FOR: adding an AG-UI event type, adding a message role or input-content type, editing AGUIJsonSerializerContext, editing BaseEventJsonConverter / AGUIMessageJsonConverter / AGUIInputContentJsonConverter, fixing PublicAPI.Unshipped analyzer build failures on protocol types, wire-format round-trip serialization. DO NOT USE FOR: writing integration/SSE tests (use agui-dotnet-integration-tests), server hosting/endpoint code, or non-Abstractions packages.

AG-UI .NET Wire/Protocol Types

Add or change a serialized protocol type in sdks/dotnet/src/AGUI.Abstractions/. These types are the JSON wire format. The TypeScript SDK is the reference — every type must round-trip against its JSON. Add // Keep in sync with sdks/typescript/packages/core/src/{events,types}.ts to each new type.

The 5 source packages are AGUI.Abstractions, AGUI.Formatting, AGUI.Protobuf, AGUI.Client, AGUI.Server. Wire types live in AGUI.Abstractions only. (sdks/dotnet/AGENTS.md is the canonical reference for the serialization rules and conventions.)

Run all commands from sdks/dotnet/.

Hard rules (forgetting any breaks the build or wire compat)

Every change to a polymorphic type touches four coordinated spots. Miss one and either the build fails or the type silently won't deserialize:

1. The concrete class (Events/, Messages/).
2. The discriminator constant (AGUIEventTypes / AGUIRoles / AGUIInputContentTypes).
3. The source-gen context registration (Serialization/AGUIJsonSerializerContext.cs).
4. The hand-written converter Read and Write cases (BaseEventJsonConverter / AGUIMessageJsonConverter / AGUIInputContentJsonConverter).

Plus: PublicAPI.Unshipped.txt (analyzer fails the build) and a round-trip test.

Recipe: new EVENT type

1. Class in Events/{Name}Event.cs, sealed, deriving BaseEvent. Override Type => AGUIEventTypes.{Name}.
2. Constant in Events/AGUIEventTypes.cs: public const string {Name} = "SCREAMING_SNAKE_CASE";.
3. Register [JsonSerializable(typeof({Name}Event))] in AGUIJsonSerializerContext.
4. Converter in BaseEventJsonConverter: add a Read switch arm (AGUIEventTypes.{Name} => jsonElement.Deserialize(options.GetTypeInfo(typeof({Name}Event))) as {Name}Event) and a Write case {Name}Event x: JsonSerializer.Serialize(writer, x, options.GetTypeInfo(typeof({Name}Event))); break;.
5. PublicAPI — add every new public member to src/AGUI.Abstractions/PublicAPI.Unshipped.txt (format below).
6. Test in tests/AGUI.Abstractions.UnitTests/{Name}EventTest.cs (JsonDocument assertions).

[JsonPropertyName("type")]
public override string Type => AGUIEventTypes.RunStarted;

[JsonPropertyName("threadId")]                          // required: init to string.Empty
public string ThreadId { get; set; } = string.Empty;

[JsonPropertyName("parentRunId")]                       // optional: no JsonIgnore needed
public string? ParentRunId { get; set; }

[JsonPropertyName("value")]                             // dynamic payload: JsonElement, never object
public JsonElement? Value { get; set; }

Variation: MESSAGE type

Same shape, but: folder Messages/, derive AGUIMessage, discriminator is role keyed on AGUIRoles constants (lowercase, e.g. "assistant"), and the converter is AGUIMessageJsonConverter (Read + Write switch arms). Sync against types.ts. Most roles serialize directly; AGUIUserMessage is hand-serialized because its content is string | array — follow the existing WriteUserMessage/DeserializeUserMessage pattern if a role needs union content.

Variation: INPUT-CONTENT part

Folder Messages/, derive AGUIInputContent, discriminator is type keyed on AGUIInputContentTypes constants (lowercase, e.g. "image"), converter is AGUIInputContentJsonConverter. Also add the same arm to AGUIMessageJsonConverter.DeserializeUserMessage's inner contentType switch, since user-message arrays inline-dispatch content parts.

Serialization / AOT rules

• [JsonSerializable(typeof(T))] for every new type — non-negotiable for AOT (no runtime reflection serializer).
• [JsonPropertyName("camelCase")] on every serialized property (explicit even though the context sets CamelCase).
• No [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] on optional properties. The context sets DefaultIgnoreCondition = WhenWritingNull once, for every type it knows, and AGUIJsonUtilities.DefaultTypeInfoResolver carries the same rule into caller-owned JsonSerializerOptions. Repeating it per property is what let three nulls onto the wire before anyone noticed the pattern was optional. NullOmissionTest fails if the context-wide setting stops doing the work, so a re-added attribute is not a harmless duplicate — it hides the regression.
• A non-nullable JsonElement that the contract lets a producer leave out does need [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)] (see AGUITool.Parameters): it is never null, so the null rule cannot reach it, and an unset JsonElement throws on write.
• Required strings init to string.Empty; collections init to [].
• Serialize via the generated context: AGUIJsonSerializerContext.Default.{Type} (or options.GetTypeInfo(typeof(T)) inside converters).
• Dynamic/arbitrary payloads are JsonElement / JsonElement?.
• Never JsonSerializer.Serialize<object>(...), never pass raw strings through unparsed, never reflection-based serialization.

Polymorphic converter pattern

Hand-written JsonConverter<TBase>, keyed on a discriminator property. BaseEventJsonConverter is the exemplar: Read deserializes to JsonElement, reads the discriminator, switches to the concrete GetTypeInfo(...), and throws JsonException on unknown/null; Write switches on the runtime type. Both directions must list every concrete type. A new abstract family needs the converter referenced via [JsonConverter(typeof(...))] on the base class.

PublicAPI.Unshipped.txt

The analyzer fails the build if a public member is missing here. Add one line per member, e.g. for an event:

AGUI.Abstractions.RunStartedEvent
AGUI.Abstractions.RunStartedEvent.RunStartedEvent() -> void
AGUI.Abstractions.RunStartedEvent.ThreadId.get -> string!
AGUI.Abstractions.RunStartedEvent.ThreadId.set -> void
override AGUI.Abstractions.RunStartedEvent.Type.get -> string!
AGUI.Abstractions.AGUIJsonSerializerContext.RunStartedEvent.get -> System.Text.Json.Serialization.Metadata.JsonTypeInfo<AGUI.Abstractions.RunStartedEvent>

! = non-null reference, ? = nullable. Don't forget the source-gen context's generated JsonTypeInfo<T> getter line.

Round-trip test (mandatory)

Assert JSON property names by parsing with JsonDocument — asserting the deserialized object alone misses camelCase/discriminator bugs. Don't compare full JSON strings; no reflection.

var json = JsonSerializer.Serialize(evt, AGUIJsonSerializerContext.Default.CustomEvent);
using var doc = JsonDocument.Parse(json);
Assert.Equal("CUSTOM", doc.RootElement.GetProperty("type").GetString());
Assert.Equal("user_preference_updated", doc.RootElement.GetProperty("name").GetString());

Also test dispatch through the base: JsonSerializer.Deserialize(json, AGUIJsonSerializerContext.Default.BaseEvent) then Assert.IsType<CustomEvent>(evt). For wire-format drift, add a fixture under tests/AGUI.Abstractions.UnitTests/Compatibility/ produced by the TypeScript SDK and load it via FixtureLoader ({Category}CompatibilityTest naming).

Code style / naming

• sealed class (no record); one type per file named for the type.
• No tuples in public APIs — define a named type.
• Event classes {Name}Event; event discriminators SCREAMING_SNAKE_CASE (member PascalCase); role/type/outcome discriminators are lowercase string constants in static classes — never enums.
• Braces always; ArgumentNullException.ThrowIfNull(...) for public validation; no /// docs on internal/private.

Validate

dotnet build
dotnet test tests/AGUI.Abstractions.UnitTests/