.NET: Provide typed access to RunAgentInput.State in .NET AG-UI

[danroth27]

Description

Accessing AG-UI client state currently requires recovering RunAgentInput from ChatOptions, inspecting its JsonElement, and deserializing it manually:

if (chatOptions.TryGetRunAgentInput(out RunAgentInput? input) &&
    input.State is { ValueKind: JsonValueKind.Object } state)
{
    var value = state.Deserialize(
        AppJsonSerializerContext.Default.DocumentState);
}

Provide a typed convenience API:

if (chatOptions.TryGetRunAgentState(
    AppJsonSerializerContext.Default.DocumentState,
    out DocumentState? state))
{
    Validate(state);
}

Proposed signature:

public static bool TryGetRunAgentState<T>(
    this ChatOptions options,
    JsonTypeInfo<T> jsonTypeInfo,
    out T? state);

The method should return false when no state was supplied and throw a clear deserialization exception for malformed state. Requiring JsonTypeInfo<T> keeps the API AOT-safe.

Client state remains untrusted. The application is responsible for validation and deciding whether to use it in tools or model context. This is narrower than #7745 and does not integrate client state with AgentSession.StateBag.

Code Sample

if (chatOptions.TryGetRunAgentState(
    AppJsonSerializerContext.Default.DocumentState,
    out DocumentState? state))
{
    Validate(state);
}

Language/SDK

.NET