[Feat]: Add QuerySkill() operation for runtime skill capability introspection

[Srinivasoo7]

Description

This PR addresses the need for dynamic capability discovery in the A2A protocol. Currently, orchestrators rely on the static AgentCard, which cannot represent multidimensional or runtime-specific constraints (e.g., "Can you process a 500MB audio file right now?").

Several active discussions confirm real community pain - #883 , #773 , #921, #166 all describing the same root cause: no protocol-level mechanism exists for a client to probe whether a remote agent can handle a specific skill at runtime.

This PR introduces the QuerySkill RPC to establish a proactive capability declaration standard prior to task execution.

Changes:

• Added QuerySkill RPC to A2AService in a2a.proto for dynamic skill introspection.
• Added skill_query boolean flag to AgentCapabilities so agents can explicitly declare support for this feature.
• Added SkillQueryRequest and SkillQueryResult messages, including a SkillSupportLevel enum (SUPPORTED, PARTIAL, UNSUPPORTED).
• Added ADR-002 (adr-002-queryskill.md) detailing the context, decision, consequences, and rejected alternatives.

Details:

• Supports negotiation via a constraints map for PARTIAL support levels.
• Includes a confidence float and reason string for probabilistic routing.
• Returns a cache_ttl_seconds to allow orchestrators to cache results (and utilize stale-if-error semantics), preventing the QuerySkill RPC from becoming a performance bottleneck.

[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 introduces a significant enhancement to the A2A protocol by enabling dynamic skill introspection through a new QuerySkill RPC. This addresses the limitations of static AgentCard discovery, which cannot account for real-time variations in agent capabilities due to factors like load or configuration. The new mechanism allows orchestrator agents to proactively determine if another agent can handle a specific task with given parameters, thereby preventing over- or under-delegation and supporting partial capability negotiation.

Highlights

• Introduced QuerySkill RPC: A new RPC QuerySkill has been added to the A2AService to allow dynamic introspection of agent capabilities, moving beyond static AgentCard discovery.
• Defined new Protobuf messages: SkillQueryRequest, SkillQueryResult, and the SkillSupportLevel enum were added to support the dynamic skill querying mechanism.
• Established protocol bindings and caching: The QuerySkill RPC includes bindings for JSON-RPC, gRPC, and HTTP/REST, along with defined caching and stale-if-error semantics for SkillQueryResult.
• Added agent opt-in for skill querying: A new skill_query boolean field was added to AgentCapabilities to allow agents to explicitly declare support for dynamic skill querying.

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.

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. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new QuerySkill RPC to allow for dynamic capability discovery between agents. The changes include a new ADR documenting the feature and the necessary additions to the a2a.proto file, such as the new RPC, messages, and an enum.

My review focuses on improving the clarity of the ADR and enhancing the flexibility and consistency of the new protobuf messages. I've emphasized using full context for enum values in the ADR for better clarity, aligning with documentation best practices. I've also suggested adopting google.protobuf.Struct for map-like fields to align with existing patterns in the protocol and support more complex data structures, and proposed making the new enum values in the proto more concise for better readability in JSON payloads.

[Srinivasoo7]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a QuerySkill RPC to enable dynamic capability discovery in the A2A protocol, a significant improvement over relying on the static AgentCard. The changes include a new ADR, and updates to the a2a.proto file to define the new RPC, messages, and a capability flag. The implementation is well-structured and the ADR provides clear context. My feedback includes a suggestion to align a new protobuf enum with project conventions, and a reminder to update the main specification document to reflect these new changes.

[gemini-code-assist]

This ADR is a great addition for documenting the new QuerySkill RPC. However, the main protocol specification document (docs/specification.md) also needs to be updated to reflect this change. Please ensure the new RPC is added to the list of core operations and the method mapping reference table to keep the documentation complete and discoverable for implementers.

[gemini-code-assist]

The enum values mentioned here (SKILL_SUPPORT_LEVEL_SUPPORTED, etc.) are inconsistent with the current implementation in a2a.proto, which uses short names like SUPPORTED. While the names in this ADR correctly follow the project's enum naming convention (e.g., TASK_STATE_...), the implementation does not. This should be reconciled for consistency. I've added a suggestion on a2a.proto to align the implementation with this ADR and the project's conventions.