feat(spec): A2A API Extensions

[darkhaniop]

Add an optional "extensions" property to AgentCard for listing custom API extensions.

Motivation

It is understandable that the A2A protocol specification attempts to be as generic as possible to accommodate many agent interaction use cases. However, by not defining a way of calling custom RPC methods that developers may decide to implement on their A2A servers (to address cases not covered by the specification), the A2A protocol puts some limitations on the agentic app developers.

Of course, if necessary, additional APIs can always be deployed on separate endpoints (and it makes sense for scalability). However, some developers may like the simplicity of single-endpoint deployments for their smaller agentic apps.

While anyone can take an A2A server library and manually add their custom methods, the lack of guiding definitions in the A2A spec means that extensions developed on such forked libraries are not easily shareable with the community. Furthermore, it would add the effort overhead required for maintaining a forked version of the server library.

Description

This PR adds an optional property to AgentCard to allow listing of custom API extensions.

Use Cases

Here are some use case examples:

• Perform actions on multiple tasks.
• Allow clients to adjust their data and artifact retention polices.
• Payment-system integrations.
• Out-of-band account actions, for example, subscription upgrade with the app provider.
• Give the client the ability to adjust agent behavior when processing current and future task(s), e.g., edit context data.
• Run domain-specific procedures on the server.

Details

An extension entry only needs to specify the "what" (unique id, methods) and "where" (prefix), leaving other details up to the extension developers (also allowing them to add more details as metadata).

So, the schema for an extension entry is defined as follows:

export interface AgentExtension {
  /** Unique identifier of the API extension. */
  id: string;
  /** Human-readable name of the API extension. */
  name: string;
  /** Description of the API extension. */
  description?: string;
  /**
   * Prefix added in front of the extension's JSON-RPC methods. `prefix` SHOULD NOT start with
   * "message" or "tasks". It is recommended to put all extensions under a common prefix, for
   * example `extensions/first/`, `extensions/second/`.
   * 
   * Examples:
   * With `prefix=extensions/taskHistory/`, an API extension method listed as `clearRecent` would
   * match an RPC method registered at `extensions/taskHistory/clearRecent` on the A2A server. This
   * allows supplying multiple versions of an extension.
   */
  prefix: string;
  /** The list of method names (without prefix) provided by the API extension. */
  methods: string[];
  /**
   * Metadata can be used to supply API-extension-specific docs, request-response schemas, and
   * other relevant information.
   */
  metadata?: {
    [key: string]: any;
  };
}

Example: Custom Task History Management API

For example, an extension that adds history management methods can be listed as follows:

{
  ...
  "extensions": [
    {
      "id": "TaskHistMgr-v1",
      "name": "Task History Manager",
      "description": "The A2A extension for managing the task history.",
      "methods": [
        "clearAll",
        "clearRecent",
        "search"
      ],
      "prefix": "extensions/taskHistory/",
      "metadata": {
        "links": [
          {"name": "docs", "href": "https://example-com.github.io/docs"}
        ]
      }
    }
  ]
}

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

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

Next Steps

Since the added "extensions" property is optional, this is a non-breaking change to the current A2A protocol. The official SDK can be updated to support his feature at a later time.

Other A2A server libraries that wish to support this option can implement a way of registering additional RPC methods (e.g., similar to how routes are registered in WSGI and ASGI apps). For convenience, the default option for registering an extension can be set to append it to AgentCard(s) automatically. This would help with the deployment consistency for such agentic apps as well.

---

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
• Ensure the tests and linter pass (Run nox -s format from the repository root to format)
• Appropriate docs were updated (if necessary)

Fixes #585 🦕

[darkhaniop]

Updated the spec documentation.

In the section describing the AgentExtensions object, added a note about individual API extensions being external to the core specification:

Note that, unlike agent "skills" and "capabilities", individual extensions are not part of the A2A specification. Therefore, when adding extensions to their A2A servers, developers should carefully consider potential security, performance, and other implications.