feat: support v0.3 agent card parsing in A2ACardResolver

[darrelmiller]

Summary

Adds backward-compatible parsing of v0.3 agent cards in A2ACardResolver.

Problem

v0.3 agents expose agent cards without supportedInterfaces (a required field in v1.0), causing deserialization failures when a v1.0 client resolves a v0.3 agent's card.

Solution

A2ACardResolver now performs two-pass deserialization:

1. First attempts standard v1.0 parsing
2. On JsonException (missing required properties), falls back to UpcastV03AgentCard() which maps v0.3 properties (url, preferredTransport, protocolVersion, additionalInterfaces) into a valid v1.0 AgentCard

The upcast:

• Synthesizes supportedInterfaces from url + preferredTransport
• Preserves additionalInterfaces entries
• Adds sensible defaults for defaultInputModes/defaultOutputModes
• Logs a warning when upcast is triggered

Testing

• All existing tests continue to pass
• ITK interoperability tests pass (4/5 scenarios)

[gemini-code-assist]

Code Review

This pull request introduces a fallback mechanism in A2ACardResolver to support parsing older v0.3 agent cards and upcasting them to v1.0 when v1.0 deserialization fails. It reads the response as a byte array, attempts standard deserialization, and falls back to manual parsing via UpcastV03AgentCard upon encountering specific JsonException errors. Feedback highlights two key areas for improvement: first, relying on ex.Message.Contains(...) for exception filtering is fragile due to localization and runtime changes, and catching any JsonException to attempt the upcast is recommended instead; second, calling GetString() on non-string JSON properties during manual parsing can throw an exception, so verifying ValueKind beforehand is advised.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Relying on ex.Message.Contains(...) to detect missing properties is fragile and error-prone for two main reasons:

1. Localization: Exception messages in .NET can be localized based on the system's UI culture. On non-English systems, the message will not contain these English strings, causing the fallback to be skipped entirely.
2. Runtime Stability: The exact wording of JsonException messages is an implementation detail of the .NET runtime and can change between versions or patches.

Instead, catch any JsonException, attempt the upcast, and if the upcast succeeds, return the upcast card. If it fails (returns null), rethrow the original exception (throw;) to let the outer catch block handle it.

            catch (JsonException ex)
            {
                // The card is missing v1.0 required properties — attempt v0.3 upcast
                var upcastCard = UpcastV03AgentCard(bytes);
                if (upcastCard is not null)
                {
                    _logger.AttemptingV03AgentCardUpcast(ex);
                    return upcastCard;
                }

                throw;
            }

[gemini-code-assist]

If any of these properties exist in the JSON but are not strings (e.g., they are numbers, booleans, or objects), calling GetString() will throw an InvalidOperationException. It is safer to verify that the property value kind is JsonValueKind.String before calling GetString().

            Name = root.TryGetProperty("name", out var name) && name.ValueKind == JsonValueKind.String ? name.GetString() ?? "" : "",
            Description = root.TryGetProperty("description", out var desc) && desc.ValueKind == JsonValueKind.String ? desc.GetString() ?? "" : "",
            Version = root.TryGetProperty("version", out var ver) && ver.ValueKind == JsonValueKind.String ? ver.GetString() ?? "0.3" : "0.3",