Skip to content

feat: support v0.3 agent card parsing in A2ACardResolver #417

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
darrelmiller wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: support v0.3 agent card parsing in A2ACardResolver #417

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 146 additions & 3 deletions src/A2A/Client/A2ACardResolver.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,10 +68,24 @@ public async Task<AgentCard> GetAgentCardAsync(CancellationToken cancellationTok

response.EnsureSuccessStatusCode();

using var responseStream = await response.Content.ReadAsStreamAsync(cancellationToken).ConfigureAwait(false);
// Buffer the response so we can attempt multiple deserialization strategies
var bytes = await response.Content.ReadAsByteArrayAsync(cancellationToken).ConfigureAwait(false);

return await JsonSerializer.DeserializeAsync(responseStream, A2AJsonUtilities.JsonContext.Default.AgentCard, cancellationToken).ConfigureAwait(false) ??
throw new A2AException("Failed to parse agent card JSON.");
try
{
return JsonSerializer.Deserialize(bytes, A2AJsonUtilities.JsonContext.Default.AgentCard)
?? throw new A2AException("Failed to parse agent card JSON.");
}
catch (JsonException ex) when (ex.Message.Contains("supportedInterfaces") ||
ex.Message.Contains("skills") ||
ex.Message.Contains("defaultInputModes") ||
ex.Message.Contains("defaultOutputModes"))
{
// The card is missing v1.0 required properties — attempt v0.3 upcast
_logger.AttemptingV03AgentCardUpcast(ex);
return UpcastV03AgentCard(bytes)
?? throw new A2AException($"Failed to parse JSON: {ex.Message}");
}
Comment on lines +79 to +88

@gemini-code-assist gemini-code-assist Bot Jun 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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;
            }

}
catch (JsonException ex)
{
Expand All @@ -88,4 +102,133 @@ public async Task<AgentCard> GetAgentCardAsync(CancellationToken cancellationTok
throw new A2AException("HTTP request failed", ex);
}
}

/// <summary>
/// Attempts to parse a v0.3 agent card and upcast it to a v1.0 <see cref="AgentCard"/>.
/// A v0.3 card has a top-level "url" and optional "preferredTransport" instead of "supportedInterfaces".
/// </summary>
/// <param name="bytes">The raw JSON bytes of the agent card response.</param>
/// <returns>An upcast v1.0 <see cref="AgentCard"/> if the JSON is a valid v0.3 card; otherwise <c>null</c>.</returns>
private static AgentCard? UpcastV03AgentCard(byte[] bytes)
{
using var doc = JsonDocument.Parse(bytes);
var root = doc.RootElement;

// v0.3 cards MUST have a "url" property
if (!root.TryGetProperty("url", out var urlElement) || urlElement.ValueKind != JsonValueKind.String)
{
return null;
}

var url = urlElement.GetString();
if (string.IsNullOrEmpty(url))
{
return null;
}

// Determine the protocol binding from preferredTransport (defaults to JSONRPC)
var protocolBinding = ProtocolBindingNames.JsonRpc;
if (root.TryGetProperty("preferredTransport", out var transportElement))
{
var transport = transportElement.ValueKind == JsonValueKind.String
? transportElement.GetString()
: transportElement.ValueKind == JsonValueKind.Object && transportElement.TryGetProperty("value", out var val)
? val.GetString()
: null;

if (!string.IsNullOrEmpty(transport))
{
protocolBinding = transport.ToUpperInvariant() switch
{
"JSONRPC" or "JSON-RPC" => ProtocolBindingNames.JsonRpc,
"HTTP+JSON" or "HTTP_JSON" or "REST" => ProtocolBindingNames.HttpJson,
"GRPC" => ProtocolBindingNames.Grpc,
_ => transport
};
}
}

// Build the supportedInterfaces list from the v0.3 url + preferredTransport
var interfaces = new List<AgentInterface>
{
new()
{
ProtocolBinding = protocolBinding,
Url = url,
ProtocolVersion = root.TryGetProperty("protocolVersion", out var pv) ? pv.GetString() ?? "0.3" : "0.3",
}
};

// Also include additionalInterfaces if present (a v0.3 extension)
if (root.TryGetProperty("additionalInterfaces", out var addlInterfaces) && addlInterfaces.ValueKind == JsonValueKind.Array)
{
foreach (var iface in addlInterfaces.EnumerateArray())
{
var ai = JsonSerializer.Deserialize(iface.GetRawText(), A2AJsonUtilities.JsonContext.Default.AgentInterface);
if (ai is not null)
{
interfaces.Add(ai);
}
}
}

// Extract common fields
var card = new AgentCard
{
Name = root.TryGetProperty("name", out var name) ? name.GetString() ?? "" : "",
Description = root.TryGetProperty("description", out var desc) ? desc.GetString() ?? "" : "",
Version = root.TryGetProperty("version", out var ver) ? ver.GetString() ?? "0.3" : "0.3",
Comment on lines +178 to +180

@gemini-code-assist gemini-code-assist Bot Jun 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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",

SupportedInterfaces = interfaces,
Capabilities = new AgentCapabilities(),
DefaultInputModes = ["text/plain"],
DefaultOutputModes = ["text/plain"],
Skills = [],
};

// Parse capabilities
if (root.TryGetProperty("capabilities", out var caps) && caps.ValueKind == JsonValueKind.Object)
{
if (caps.TryGetProperty("streaming", out var streaming))
card.Capabilities.Streaming = streaming.ValueKind == JsonValueKind.True;
if (caps.TryGetProperty("pushNotifications", out var push))
card.Capabilities.PushNotifications = push.ValueKind == JsonValueKind.True;
}

// Parse default modes if present
if (root.TryGetProperty("defaultInputModes", out var inputModes) && inputModes.ValueKind == JsonValueKind.Array)
{
card.DefaultInputModes = inputModes.EnumerateArray()
.Where(e => e.ValueKind == JsonValueKind.String)
.Select(e => e.GetString()!)
.ToList();
}

if (root.TryGetProperty("defaultOutputModes", out var outputModes) && outputModes.ValueKind == JsonValueKind.Array)
{
card.DefaultOutputModes = outputModes.EnumerateArray()
.Where(e => e.ValueKind == JsonValueKind.String)
.Select(e => e.GetString()!)
.ToList();
}

// Parse skills if present
if (root.TryGetProperty("skills", out var skills) && skills.ValueKind == JsonValueKind.Array)
{
foreach (var skillElement in skills.EnumerateArray())
{
var skill = JsonSerializer.Deserialize(skillElement.GetRawText(), A2AJsonUtilities.JsonContext.Default.AgentSkill);
if (skill is not null)
{
card.Skills.Add(skill);
}
}
}

if (root.TryGetProperty("documentationUrl", out var docUrl))
card.DocumentationUrl = docUrl.GetString();
if (root.TryGetProperty("iconUrl", out var iconUrl))
card.IconUrl = iconUrl.GetString();

return card;
}
}
3 changes: 3 additions & 0 deletions src/A2A/Log.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ static partial class Log
[LoggerMessage(2, LogLevel.Error, "HTTP request failed with status code {StatusCode}")]
internal static partial void HttpRequestFailedWithStatusCode(this ILogger logger, Exception exception, System.Net.HttpStatusCode StatusCode);

[LoggerMessage(5, LogLevel.Information, "Agent card missing v1.0 required properties, attempting v0.3 upcast")]
internal static partial void AttemptingV03AgentCardUpcast(this ILogger logger, Exception exception);

[LoggerMessage(3, LogLevel.Error, "Background event processing failed for task {TaskId}")]
internal static partial void BackgroundEventProcessingFailed(this ILogger logger, Exception exception, string TaskId);

Expand Down