[Feat]: A2A API Extensions

[darkhaniop]

Is your feature request related to a problem? Please describe.

Currently, the A2A specification does not provide a way to add custom methods to an A2A server. This limits the possibility of agentic apps to offer additional domain-specific features or alternative approaches to existing, more generic processes on the A2A server endpoint (same host and port).

Use cases

Here are some use-case examples:

• Perform actions on multiple tasks (see a more detailed history management example in the next section).
• Allow clients to adjust their data and artifact retention polices.
• Custom payment implementations (devs deploying agents in different countries/regions may wish to integrate local payment systems into their A2A endpoints that may not work elsewhere).
• Out-of-band account actions, for example, subscription upgrade to resume task execution.
• Give the client the ability to adjust agent behavior when processing future task(s).
• Run domain-specific procedures on the server.

Describe the solution you'd like

I propose adding an option to the A2A specification to register and serve additional API methods that are not part of the core A2A protocol, i.e., A2A API Extensions.

Details with an example

The A2A server libraries that wish to support this option must implement a way of registering additional RPC methods (e.g., similar to how routes are registered in WSGI and ASGI apps). Adding information about the API extensions to AgentCard and/or to its "authenticated" version would be beneficial (except for admin extensions). To enhance convenience, the default option for registering an extension can be set to append it to AgentCard(s) automatically.

For example, an extension named "Task History Manager" can be listed as follows in AgentCard:

{
  ...
  "extensions": [
    {
      "id": "TaskHistMgr-v1",
      "name": "Task History Manager",
      "description": "The A2A extension for managing the task history.",
      "methods": [
        "clearAll",
        "clearRecent",
        "search"
      ],
      "prefix": "extensions/taskHistory/"
    }
  ]
}

With such an extension installed, the client, after running some mock tasks (e.g., checking different travel plans), can clean up these tasks with:

{
  "jsonrpc": "2.0",
  "id": "d4f09e6f3a654c33af9e529d824f6836",
  "method": "extensions/taskHistory/clearRecent",
  "params": {
    "initiatedWithinLast": "1 hour"
  }
}

Advantages of this solution

• Provides a standardized approach to extend A2A server capabilities.
• Developers working on domain-specific methods for their A2A agents would not need to maintain a custom implementation (fork) of the A2A server.
• Since adding such extensions to existing projects would be much easier (akin to importing another library in "pythonspeak"), developers can collaborate more efficiently and easily share their extensions with a broader audience. Also, different teams can iterate on their extensions at their own pace.
• For the A2A maintainers, observing which extensions are more popular within the community would be easier. It could give more confidence in recommending field-tested A2A extensions to new A2A developers. It would also be easier to see the consensus in the community regarding the usefulness of some extensions (for considering adding them into future versions of the core A2A protocol).
• If a security vulnerability or other issues related to an extension are discovered, because individual extensions are not part of the core A2A protocol, it would be easy to update or remove that extension without the need to patch A2A server libraries.

Describe alternatives you've considered

Currently, if developers want to add new API methods, they have two options (the third method in the list below is technically outside of the scope of this issue, but I put it there for completeness).

1. If they deem the feature they are working on reasonably generic, they can try getting PRs with their methods merged into the google/A2A repository.
2. Fork an A2A server implementation, e.g., the official A2A Python SDK, and modify it to meet their custom requirements.
3. Instead of adding new methods, use additional endpoints.

Drawbacks of these alternatives

1. One of the drawbacks of the first method is that iteration on the new feature would be slowed down by the PR review process, which could also limit the possibility for other developers to try it in their projects. Another drawback is that such features may address too specific (or diverging) concerns that may introduce too much complexity to A2A client and server libraries that do not benefit most agentic apps (and may not get widespread approval among A2A devs).
2. While the second method allows the developers to iterate on the new feature at their pace, it has its drawbacks as well: (a) the need to maintain a custom version of the library, (b) difficulty in sharing more useful extensions with other developers, I imagine it would be more challenging if the other developers heavily rely on CI/CD that use officially supported A2A libraries.
3. While more advanced agents may opt to expose additional methods on separate endpoints, some developers may prefer the simplicity of single-unit deployments where the agents and their accompanying methods are served from a single endpoint.

Additional context

Additional considerations

Q: Why introduce a new property instead of, for example, "skills"?
A: As far as I understand, "skills" aims to give an itemized summary of what the agent is configured to do, not meant for listing the API exposed to the clients.
Q: Then why not list extensions in "capabilities?"
A: While functionally, "capabilities" is closer to what the proposed "extensions" property is, currently, "capabilities" describes features of the core A2A protocol. While the "extensions" property is meant to list API developed and maintained outside of the A2A specification. I think it would be better not to mix these two lists.

Code of Conduct

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