Skip to content

Add AGUIStreamOptions.IncludeRawEvents - #2298

Open
halllo wants to merge 1 commit into
ag-ui-protocol:mainfrom
halllo:exclude_raw_events
Open

Add AGUIStreamOptions.IncludeRawEvents#2298
halllo wants to merge 1 commit into
ag-ui-protocol:mainfrom
halllo:exclude_raw_events

Conversation

@halllo

@halllo halllo commented Aug 2, 2026

Copy link
Copy Markdown

Closes #2297.

.NET servers attach the serialized originating ChatResponseUpdate as rawEvent to every TEXT_MESSAGE_*, TOOL_CALL_*, and REASONING_ENCRYPTED_VALUE event, with no way to opt out. On this repo's own Step* baselines that field is 66% of the wire. Nothing reads it, and neither the TS nor the Python server side emits it — so it is a .NET-only divergence from the canonical wire format.

This adds an init-only bool IncludeRawEvents (default true) to AGUIStreamOptions. The guard sits on the serialization rather than the assignment, so opting out also recovers the per-update CPU and allocations:

JsonElement? raw = options.IncludeRawEvents
    ? JsonSerializer.SerializeToElement(chatResponse, jsonSerializerOptions.GetTypeInfo(typeof(ChatResponseUpdate)))
    : null;

The default is true deliberately. false is arguably the parity-correct long-term default, but flipping it breaks anyone reading the field and moves every recorded baseline — better as its own deliberate change. This one is purely additive.

Every Create already took JsonElement?, so one internal signature widened (ReasoningMessageTracker.EmitEncryptedValue). Caller-supplied events (RawRepresentation or a Map* mapping) keep their own RawEvent. The event sequence is identical either way, so this is not a protocol change.

Tests

Six unit tests: default true; the field drops from text, tool-call, and REASONING_ENCRYPTED_VALUE events; caller-supplied rawEvent survives; identical event sequence either way. Plus RawEventSuppressionIntegrationTest, asserting the SSE body contains "rawEvent" only when the flag is on.

AGUI.Server.UnitTests 120/120 on net8.0/9.0/10.0, solution builds with 0 warnings, other suites pass. Two pre-existing failures are unaffected and reproduce on a clean checkout: cross-language needs a running TS server, and Step08_MultimodalMessagesTest reads an unfetched git-lfs pointer as its PNG.

Docs

New IncludeRawEvents section in hosting/extensibility.mdx, plus pointers from abstractions/events.mdx and sdks/dotnet/docs/architecture.md.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Add AGUIStreamOptions.IncludeRawEvents to make rawEvent attachment opt-out (.NET)

1 participant