FunctionCallContent.Arguments contains string "null" instead of actual null for JSON null values

[nielsbosma]

Description

When an LLM returns a tool call with null argument values (e.g., {"methodName": null}), the FunctionCallContent.Arguments dictionary contains the literal string "null" instead of actual null.

Reproduction Steps

1. Use Microsoft.Extensions.AI.OpenAI package (tested with version 9.4.0-preview.1.25207.5)
2. Define a tool with optional parameters
3. Have the LLM call the tool with null for an optional parameter
4. Inspect FunctionCallContent.Arguments dictionary

Expected Behavior

When JSON contains {"methodName": null}, the Arguments dictionary should have:

• Arguments["methodName"] is null (actual null)
• Or the key should not be present

Actual Behavior

• Arguments["methodName"] is the string "null" (4 characters: n, u, l, l)

Root Cause Analysis

The issue appears to be in OpenAIClientExtensions.ParseCallContent:

internal static FunctionCallContent ParseCallContent(string json, string callId, string name) =>
    FunctionCallContent.CreateFromParsedArguments(json, callId, name,
        static json => JsonSerializer.Deserialize(json, OpenAIJsonContext.Default.IDictionaryStringObject)!);

When System.Text.Json deserializes JSON to IDictionary<string, object>, null values are not properly preserved. The OpenAIJsonContext.Default.IDictionaryStringObject serializer context appears to convert JSON null to the string "null".

Workaround

We're currently working around this by checking for the literal string "null" when extracting values:

if (obj is string strValue && strValue == "null")
{
    value = default!;
    return false;
}

Environment

• Microsoft.Extensions.AI.OpenAI: 9.4.0-preview.1.25207.5
• .NET 9.0
• Using OpenAI-compatible endpoint (LiteLLM proxy to Claude)

Additional Context

This issue affects any code that relies on checking for null values in tool call arguments, which is common for optional parameters.

[nielsbosma]

Suggested Fix

Use JsonElement for parsing, which properly preserves JSON null values:

internal static FunctionCallContent ParseCallContent(string json, string callId, string name)
{
    var arguments = ParseJsonToDictionary(json);
    return new FunctionCallContent(callId, name, arguments);
}

private static IDictionary<string, object?> ParseJsonToDictionary(string json)
{
    using var jsonDoc = JsonDocument.Parse(json);
    var arguments = new Dictionary<string, object?>();
    
    foreach (var property in jsonDoc.RootElement.EnumerateObject())
    {
        arguments[property.Name] = ConvertJsonElement(property.Value);
    }
    
    return arguments;
}

private static object? ConvertJsonElement(JsonElement element) => element.ValueKind switch
{
    JsonValueKind.Null => null,
    JsonValueKind.String => element.GetString(),
    JsonValueKind.Number => element.TryGetInt64(out var l) ? l : element.GetDouble(),
    JsonValueKind.True => true,
    JsonValueKind.False => false,
    JsonValueKind.Array => element.EnumerateArray().Select(ConvertJsonElement).ToList(),
    JsonValueKind.Object => element.EnumerateObject().ToDictionary(p => p.Name, p => ConvertJsonElement(p.Value)),
    _ => element.ToString()
};

This approach:

1. Uses JsonDocument.Parse which properly represents JSON semantics
2. Explicitly handles JsonValueKind.Null by returning actual null
3. Recursively handles nested objects and arrays
4. Avoids the source generator context that may be causing the issue