feat: Unique identifier for an agent in Agent Card

[kthota-g]

• Adds a new id attribute to the agent card which must be a UUID.
• This id must remain same for all versions of an agent.
• id is optional to support backward compatibility.
• Clients can reliably use id as the identifier if set in the agent card.

Fixes #1014

[gemini-code-assist]

Summary of Changes

Hello @kthota-g, 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 new, optional id field to the AgentCard structure, both in the gRPC protocol definition and its TypeScript representation. The primary goal is to provide a stable, universally unique identifier (UUID) for agents, allowing clients to consistently reference them regardless of version changes. This enhancement improves the reliability and consistency of agent identification within the system.

Highlights

• New id field for AgentCard: An optional id field has been introduced to the AgentCard message in the gRPC specification, designed to serve as a unique identifier for an agent.
• UUID Validation: The new id field is strictly validated to ensure it adheres to the UUID format, leveraging buf/validate for this purpose.
• TypeScript Interface Update: The corresponding AgentCard TypeScript interface has been updated to include the optional id property, along with JSDoc comments indicating its UUID format.
• Backward Compatibility and Reliability: The id field is optional to maintain backward compatibility and is intended to provide a stable identifier for clients to reliably reference agents across different versions.

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

[gemini-code-assist]

Code Review

This pull request introduces a new optional id field to the AgentCard in both the protobuf and TypeScript definitions. This ID serves as a stable, unique identifier for an agent across its different versions. The changes are well-implemented, with validation for the UUID format in the protobuf definition and clear JSDoc annotations in the TypeScript type. My feedback includes a couple of minor suggestions to improve the comments to better reflect the stability and purpose of this new identifier, incorporating details from the pull request description. Overall, this is a great addition for client-side agent identification.

[muscariello]

is it an RFC 9562 type?

[darrelmiller]

is it an RFC 9562 type?

Effectively yes. In the registry of formats used in OpenAPI/JSON Schema RFC4122 is referenced https://spec.openapis.org/registry/format/uuid.html and RFC9562 replaces that. We should probably update the OpenAPI format registry.

[ToddSegal]

This seems to have overlap with the concept of an agent identity. I worry there are problems if a "malicious agent" reuses the uuid of a "good agent". Things like DID's or SPIFFE's are useful for preventing impersonation and guaranteeing uniqueness. Should we be waiting for that instead of opening up to random unsecure ids?

[muscariello]

I think @ToddSegal's point is correct. If we use globally unique names they should be secure. In that case an RFC 9562 type must be computed over a security envelope which provides content integrity. This could be achieved by taking the the whole content as security envelope. However this is in conflict with the requirement that the id should not change if the version is changed.
The DID instead does not guarantee content integrity unless there is an additional signature to provide integrity and provenance. In this second case too, changing version would imply changing id.

The actual definition of id should be spelled out including examples of how to compute it.

[kthota-g]

The intent of the id is to provide a stable identifier for an agent that remains same across versions of the same agent. Without an identifier, client applications have to rely on name or url which can change to identify an agent.

id is just another attribute part of the agent card, similar to any other attributes. The contents of an agent card including the id is verifiable for the client applications with signatures.

[darrelmiller]

@ToddSegal @muscariello I worry about trying to attach any kind of security characteristics to this "id". An agent is a web resource (at least it was until we started talking about stdio :-) ). Consumers of the agent should be paying close attention to the AgentURL as the thing that ensures authenticity. We have an entire ecosystem of security capability built around HTTPS. I would really like to avoid reinventing that. As @kthota-g mentioned we have signatures to ensure that agent cards have not been tampered with.

Maybe the solution is to pick a better name than "id" to provide a way to group agent versions together.

[muscariello]

@darrelmiller I am ok with that. I was just asking if we can say how we compute it. It is based on hashing. If hashing is mis-computed you may get frequent collision. It might be just a reference or additional text. And I have no issue to call it id. My comment about secure naming is about integrity not provenance.
For instance, take all fields of the card and zero all fields which are supposed to vary like the version. Hash using RFC 9562, maybe add if you have a default behavior (which hash, or if any). Make sense?