fix: support proto-based AgentCard in AgentCardResolver

[ishymko]

Description

Fixes an issue where the SDK fails to resolve Agent Cards served in Protobuf JSON format.

In the v0.3.0 specification, there was a structural drift between the JSON Schema data model and the Protobuf data model:

• JSON Schema: Uses a "type" discriminator (e.g., {"type": "openIdConnect"}). Source
• Protobuf: Uses the oneof field name as the discriminator (e.g., {"oauth2SecurityScheme": {...}}). Source

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request resolves a critical compatibility issue within the SDK's AgentCardResolver by enabling it to seamlessly handle Agent Cards formatted according to the Protobuf JSON specification. Previously, the SDK would fail to resolve these cards due to structural differences in their security scheme definitions compared to the expected JSON Schema. The changes introduce robust detection and normalization logic, ensuring that all valid Agent Card formats are correctly parsed and integrated into the SDK's internal data model, thereby enhancing the SDK's resilience and interoperability with diverse A2A implementations.

Highlights

• Support for Protobuf JSON Agent Cards: The AgentCardResolver now correctly processes Agent Cards served in Protobuf JSON format, addressing a previous failure due to structural differences.
• Normalization Logic Implemented: A new normalizeAgentCard method was added to convert Protobuf JSON structures into the SDK's expected JSON Schema format, ensuring consistent internal representation.
• Robust Detection Mechanism: Introduced isProtoAgentCard and hasProtoSecurity helper methods to intelligently detect Protobuf JSON based on the structure of security schemes and skills within the card.

Changelog

• src/client/card-resolver.ts
  • Implemented normalizeAgentCard to convert Protobuf JSON Agent Cards to the internal JSON Schema format.
  • Added isProtoAgentCard and hasProtoSecurity methods for detecting Protobuf JSON structures.
  • Modified resolve method to use the new normalization logic.
• test/client/card-resolver.spec.ts
  • Introduced new test cases to validate the AgentCardResolver's ability to correctly parse and normalize both JSON Schema and Protobuf JSON formatted Agent Cards.
  • Defined expectedAgentCard, v03AgentCard, and v1ProtoAgentCard test data for comprehensive testing.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

🧪 Code Coverage

⬇️ Download Full Report

	Main	PR	Delta
src/client/card-resolver.ts	95.23%	96.82%	🟢 +1.59%
src/types/converters/from_proto.ts	64.08%	71.59%	🟢 +7.51%
Total	80.2%	80.99%	🟢 +0.79%

Generated by coverage-comment.yml

[gemini-code-assist]

Code Review

This pull request introduces support for resolving Agent Cards that are served in Protobuf JSON format, which has a different structure from the JSON Schema format the SDK internally uses. The changes correctly detect the protobuf format and normalize it. The implementation is clean and is accompanied by good tests covering both formats. I have one suggestion to enhance the error handling within the new normalization logic to make it more robust against potential detection errors.