[Bug]: The requirement for "activating an extension" with the X-A2A-Extension header is not in the specification

[darrelmiller]

What happened?

The requirement is documented under topics but is not included in the specification.
https://a2a-protocol.org/latest/topics/extensions/#extension-activation

Any HTTP extension such as a new HTTP header field should be described in the specification using the template defined in RFC9110. Also, new fields should not be prefixed with x- as per https://www.rfc-editor.org/rfc/rfc6648

It needs to be made clear when activating an extension is a MUST as this currently is not clear and seems unnecessary considering an agent can inspect a message for the presence of extensions.

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[mikeas1]

Thanks for the feedback, Darrel. I think you're one of the first people to actually look at this doc with a critical eye, so thanks for pointing out where I'm getting it wrong.

The requirement is documented under topics but is not included in the specification

This is semi-intentional since we're still working through the details of how extensions should look. That said, it's not a good look to have a topic document on extensions but not have them described in the specification document. I do plan to add it to the specification.

Any HTTP extension such as a new HTTP header field should be described in the specification using the template defined in RFC9110.

Ok, good call out. I will write the specification for this, if we keep the header.

Also, new fields should not be prefixed with x- as per https://www.rfc-editor.org/rfc/rfc6648

I was torn on using X- for this since I'm aware it's no longer recommended, yet it seems to still be extremely prevalent. Recent protocols continue to use it, which had me feeling like it would be the most familiar thing for consumers, despite the fact it is no longer necessary or recommended. If we keep this as a header, we can remove the X- prefix.

It needs to be made clear when activating an extension is a MUST as this currently is not clear and seems unnecessary considering an agent can inspect a message for the presence of extensions.

Very fair call out.

I'd be interested in hearing your take on how this process should work: I added the concept of "activation" after having some conversations with Google-internal folks who expressed concern that an agent would return a bunch of inscrutable, extension-specific data even when a client doesn't support an extension. The intention was that this is the explicit signal from the client to indicate "I know about this extension, let's use it". This also works for cases when a client doesn't need to send any extension-specific information, so it wouldn't need to add anything to the Message by default. And if we're requesting a set of extensions be used, it seems natural that you may want to know which actually got used -- though it's not actually clear to me if this is needed (this is relevant below, since I think it has a strong impact on the right way to communicate this).

As I see it, the ways we could send that indication are:

1. Leave it up to the extension. The extension author defines the means for negotiating whether to use the extension or not. This might actually be fine, but it does mean reinventing the wheel for every extension. For something so relatively straightforward, this seems a little lackluster. On the upside, it's the most flexible option.

2. Put it in the request message object(s) a client sends to an agent, and the responses from the agent. The main question is where. In particular, the awkward part is in response messages. Does the server need to include the list of extensions in every response object it streams back, just the first, any, etc. Hence my note earlier that I'm not even sure we need this: without it, there's a clear and simple answer to how the client indicates the requested extensions: MessageSendConfiguration. This object already exists to configure how the agent processes the incoming message, so it semantically works well. Message.extensions is also a candidate, but the original intention of that was to mark a specific message as "this contains extension-related data'". Just indicating that you'd like to use an extension doesn't necessarily modify a message.

3. Put it somewhere cross-cutting. This has to be in the transport layer, since it's about communicating data that's "annotating" the core request+response. HTTP headers are a natural fit, and gRPC has Metadata as the equivalent. It's independent of the specific request structure, the "scope" is clear (the entire request, the entire response), and it doesn't require sprinkling an extensions field across all of our request/response values. The downside is that it's transport-specific.

Hence why I ended up with an HTTP header. I don't love it, but felt it was the best option given the circumstances. I'm certainly open to changing it, and I don't feel it's too late for this yet -- extensions are so new that I believe we still have some leeway to make this kind of fundamental change.

What do you think? After writing this out I'm actually leaning towards removing a protocol-level concept of activation and leaving it up to extension authors to define how and when an extension is used. Many will already have some form of this, since I expect some extensions will require information from the client -- the presence of that information is sufficient to indicate that the client wants to use the extension.