feat(spec): A2A API Extensions

docs/specification.md

@@ -170,6 +170,7 @@ Agent Cards themselves might contain information that is considered sensitive.
 | `defaultInputModes`                 | `string[]`                                                         | Yes      | Input MIME types accepted by the agent.                                                                                                     |
 | `defaultOutputModes`                | `string[]`                                                         | Yes      | Output MIME types produced by the agent.                                                                                                    |
 | `skills`                            | [`AgentSkill[]`](#554-agentskill-object)                           | Yes      | Array of skills. Must have at least one if the agent performs actions.                                                                      |
+| `extensions`                        | [`AgentExtension[]`](#555-agentextension-object)                   | No       | Array of custom API extensions available for this agent.                                                                                    |
 | `supportsAuthenticatedExtendedCard` | `boolean`                                                          | No       | Indicates support for retrieving a more detailed Agent Card via an authenticated endpoint.                                                  |
 
 #### 5.5.1. `AgentProvider` Object
@@ -225,6 +226,26 @@ Describes a specific capability, function, or area of expertise the agent can pe
 | `inputModes`  | `string[]` | No       | Overrides `defaultInputModes` for this specific skill. Accepted MIME types.    |
 | `outputModes` | `string[]` | No       | Overrides `defaultOutputModes` for this specific skill. Produced MIME types.   |
 
+#### 5.5.5. `AgentExtension` Object
+
+Describes an API extension that provides additional methods on top of the core functionality of the A2A protocol.
+
+Note that, unlike agent ["skills"](#554-agentskill-object) and ["capabilities"](#552-agentcapabilities-object), **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 impl
+ications.
+
+```ts { .no-copy }
+--8<-- "types/src/types.ts:AgentExtension"
+```
+
+| Field Name    | Type                  | Required | Description                                                                    |
+| :------------ | :-------------------- | :------- | :----------------------------------------------------------------------------- |
+| `id`          | `string`              | Yes      | Unique identifier of the API extension.                                        |
+| `name`        | `string`              | Yes      | Human-readable name of the API extension.                                      |
+| `description` | `string`              | No       | Description of the API extension.                                              |
+| `prefix`      | `string`              | Yes      | 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/`. |
+| `methods`     | `string[]`            | Yes      | The list of method names (without prefix) provided by the API extension.       |
+| `metadata`    | `Record<string, any>` | No       | Metadata can be used to supply API-extension-specific docs, request-response schemas, and other relevant information. |
+
 ### 5.6. Sample Agent Card
 
 ```json

specification/json/a2a.json

@@ -143,6 +143,13 @@
                     "description": "A URL to documentation for the agent.",
                     "type": "string"
                 },
+                "extensions": {
+                    "description": "Custom API extensions available for this agent.",
+                    "items": {
+                        "$ref": "#/definitions/AgentExtension"
+                    },
+                    "type": "array"
+                },
                 "name": {
                     "description": "Human readable name of the agent.",
                     "type": "string"
@@ -203,6 +210,46 @@
             ],
             "type": "object"
         },
+        "AgentExtension": {
+            "description": "Describes an API extension that an agent enpoint supports.",
+            "properties": {
+                "description": {
+                    "description": "Description of the API extension.",
+                    "type": "string"
+                },
+                "id": {
+                    "description": "Unique identifier of the API extension.",
+                    "type": "string"
+                },
+                "metadata": {
+                    "additionalProperties": {},
+                    "description": "Metadata can be used to supply API-extension-specific docs, request-response schemas, and\nother relevant information.",
+                    "type": "object"
+                },
+                "methods": {
+                    "description": "The list of method names (without prefix) provided by the API extension.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
+                "name": {
+                    "description": "Human-readable name of the API extension.",
+                    "type": "string"
+                },
+                "prefix": {
+                    "description": "Prefix added in front of the extension's JSON-RPC methods. `prefix` SHOULD NOT start with\n\"message\" or \"tasks\". It is recommended to put all extensions under a common prefix, for\nexample `extensions/first/`, `extensions/second/`.\n\nExamples:\nWith `prefix=extensions/taskHistory/`, an API extension method listed as `clearRecent` would\nmatch an RPC method registered at `extensions/taskHistory/clearRecent` on the A2A server. This\nallows supplying multiple versions of an extension.",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "id",
+                "methods",
+                "name",
+                "prefix"
+            ],
+            "type": "object"
+        },
         "AgentProvider": {
             "description": "Represents the service provider of an agent.",
             "properties": {

types/src/types.ts

@@ -28,6 +28,40 @@ export interface AgentCapabilities {
 }
 // --8<-- [end:AgentCapabilities]
 
+// --8<-- [start:AgentExtension]
+/**
+ * Describes an API extension that an agent enpoint supports.
+ */
+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;
+  };
+}
+// --8<-- [end:AgentExtension]
+
 // --8<-- [start:AgentSkill]
 /**
  * Represents a unit of capability that an agent can perform.
@@ -110,6 +144,8 @@ export interface AgentCard {
   defaultOutputModes: string[];
   /** Skills are a unit of capability that an agent can perform. */
   skills: AgentSkill[];
+  /** Custom API extensions available for this agent. */
+  extensions?: AgentExtension[];
   /**
    * true if the agent supports providing an extended agent card when the user is authenticated.
    * Defaults to false if not specified.