feat: Add protocol support for extensions (#716)

mikeas1 · holtskinner · web-flow · commit 70f1e2b0c68a · 2025-06-04T10:17:37.000-06:00
# Description This updates the protocol to support Extensions. Extension profiles are documents that describe modifications or additions to the core A2A profile. AgentCards can declare supported extensions via `capabilities.extensions`. This declaration can include additional information via `capabilities.extensions.params`. Clients can use this as a basis for extension negotiation: if a client supports an extension that the server supports, the client can then follow the protocol defined by the extension. This can include, but is not specifically limited to: 1. Requiring specific structure of messages, such as following a specific schema for a DataPart. 2. Providing additional information in request/response Message and Artifact objects via their `metadata` field. 3. Exposing additional methods beyond the core A2A protocol methods. Messages and Artifacts can now include an indication of which extensions are present in their content. I do not yet know if extension indications are necessary on other data structures (such as `MessageSendParams` or `TaskStatus`). I'd say extension indications are not strictly necessary at all: it's possible to infer that an extension was followed by inspecting the message content itself (are the metadata fields you expect present, does the DataPart follow the schema you expect, etc). However, they are useful for validation and simplifying extension implementation logic: "you said you followed this extension, so I'll validate fields are present and then perform my processing". Fixes #585 --------- Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
diff --git a/docs/specification.md b/docs/specification.md
@@ -51,6 +51,7 @@ A2A revolves around several key concepts. For detailed explanations, please refe
 - **Streaming (SSE):** Real-time, incremental updates for tasks (status changes, artifact chunks) delivered via Server-Sent Events.
 - **Push Notifications:** Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios.
 - **Context:** An optional, server-generated identifier to logically group related tasks.
+- **Extension:** A mechanism for agents to provide additional functionality or data beyond the core A2A specification.
 
 ## 3. Transport and Format
 
@@ -194,11 +195,27 @@ Specifies optional A2A protocol features supported by the agent.
 --8<-- "types/src/types.ts:AgentCapabilities"
 ```
 
-| Field Name               | Type      | Required | Default | Description                                                                          |
-| :----------------------- | :-------- | :------- | :------ | :----------------------------------------------------------------------------------- |
-| `streaming`              | `boolean` | No       | `false` | Indicates support for SSE streaming methods (`message/stream`, `tasks/resubscribe`). |
-| `pushNotifications`      | `boolean` | No       | `false` | Indicates support for push notification methods (`tasks/pushNotificationConfig/*`).  |
-| `stateTransitionHistory` | `boolean` | No       | `false` | Placeholder for future feature: exposing detailed task status change history.        |
+| Field Name               | Type             | Required | Default | Description                                                                          |
+| :----------------------- | :--------------- | :------- | :------ | :----------------------------------------------------------------------------------- |
+| `streaming`              | `boolean`        | No       | `false` | Indicates support for SSE streaming methods (`message/stream`, `tasks/resubscribe`). |
+| `pushNotifications`      | `boolean`        | No       | `false` | Indicates support for push notification methods (`tasks/pushNotificationConfig/*`).  |
+| `stateTransitionHistory` | `boolean`        | No       | `false` | Placeholder for future feature: exposing detailed task status change history.        |
+| `extensions`             | [`AgentExtension`[]](#5521-agentextension-object) | No       | `[]`    | A list of extensions supported by this agent.                                        |
+
+#### 5.5.2.1. `AgentExtension` Object
+
+Specifies an extension to the A2A protocol supported by the agent.
+
+```ts { .no-copy }
+--8<-- "types/src/types.ts:AgentExtension"
+```
+
+| Field Name    | Type      | Required | Description                                                                                 |
+| :-------------| :-------- | :------- | :------------------------------------------------------------------------------------------ |
+| `uri`         | `string`  | Yes      | The URI for the supported extension.                                                        |
+| `required`    | `boolean` | No       | Whether the agent requires clients to follow some protocol logic specific to the extension. Clients should expect failures when attempting to interact with a server that requires an extension the client does not support. |
+| `description` | `string`  | No       | A description of how the extension is used by the agent.                                    |
+| `params`      | `object`  | No       | Configuration parameters specific to the extension                                          |
 
 #### 5.5.3. `SecurityScheme` Object
 
@@ -361,6 +378,7 @@ Represents a single communication turn or a piece of contextual information betw
 | `role`             | `"user"` \| `"agent"`           | Yes      | Indicates the sender: `"user"` (from A2A Client) or `"agent"` (from A2A Server). |
 | `parts`            | [`Part[]`](#65-part-union-type) | Yes      | Array of content parts. Must contain at least one part.                          |
 | `metadata`         | `Record<string, any>`           | No       | Arbitrary key-value metadata associated with this message.                       |
+| `extensions`       | `string[]`                      | No       | A list of extension URIs that contributed to this message.                       |
 | `referenceTaskIds` | `string[]`                      | No       | List of tasks referenced as contextual hint by this message.                     |
 | `messageId`        | `string`                        | Yes      | Message identifier generated by the message sender                               |
 | `taskId`           | `string`                        | No       | Task identifier the current message is related to                                |
@@ -462,6 +480,7 @@ Represents a tangible output generated by the agent during a task. Artifacts are
 | `description` | `string`                        | No       | Human-readable description of the artifact.                                     |
 | `parts`       | [`Part[]`](#65-part-union-type) | Yes      | Content of the artifact, as one or more `Part` objects. Must have at least one. |
 | `metadata`    | `Record<string, any>`           | No       | Arbitrary key-value metadata associated with the artifact.                      |
+| `extensions`  | `string[]`                 | No       | A list of extension URIs that contributed to this artifact.                         |
 
 ### 6.8. `PushNotificationConfig` Object
 
diff --git a/docs/topics/key-concepts.md b/docs/topics/key-concepts.md
@@ -78,5 +78,7 @@ The Agent2Agent (A2A) protocol is built around a set of core concepts that defin
     - Learn more about [Enterprise-Ready Features](./enterprise-ready.md).
 - **Agent Discovery:** The process by which clients find Agent Cards to learn about available A2A Servers and their capabilities.
     - Learn more about [Agent Discovery](./agent-discovery.md).
+- **Extensions:** A2A allows agents to declare custom protocol extensions as part of their AgentCard.
+    - More documentation coming soon.
 
 By understanding these core components and mechanisms, developers can effectively design, implement, and utilize A2A for building interoperable and collaborative AI agent systems.
diff --git a/specification/grpc/a2a.proto b/specification/grpc/a2a.proto
@@ -243,6 +243,8 @@ message Message {
   // protolint:enable REPEATED_FIELD_NAMES_PLURALIZED
   // Any optional metadata to provide along with the message.
   google.protobuf.Struct metadata = 6;
+  // The URIs of extensions that are present or contributed to this Message.
+  repeated string extensions = 7;
 }
 
 // Artifacts are the container for task completed results. These are similar
@@ -259,6 +261,8 @@ message Artifact {
   repeated Part parts = 5;
   // Optional metadata included with the artifact.
   google.protobuf.Struct metadata = 6;
+  // The URIs of extensions that are present or contributed to this Artifact.
+  repeated string extensions = 7;
 }
 
 // TaskStatusUpdateEvent is a delta even on a task indicating that a task
@@ -368,6 +372,20 @@ message AgentCapabilities {
   bool streaming = 1;
   // If the agent can send push notifications to the clients webhook
   bool push_notifications = 2;
+  // Extensions supported by this agent.
+  repeated AgentExtension extensions = 3;
+}
+
+// A declaration of an extension supported by an Agent.
+message AgentExtension {
+  // The URI of the extension.
+  string uri = 1;
+  // A description of how this agent uses this extension.
+  string description = 2;
+  // Whether the client must follow specific requirements of the extension.
+  bool required = 3;
+  // Optional configuration for the extension.
+  google.protobuf.Struct params = 4;
 }
 
 // AgentSkill represents a unit of action/solution that the agent can perform.
diff --git a/specification/json/a2a.json b/specification/json/a2a.json
@@ -99,6 +99,13 @@
         "AgentCapabilities": {
             "description": "Defines optional capabilities supported by an agent.",
             "properties": {
+                "extensions": {
+                    "description": "extensions supported by this agent.",
+                    "items": {
+                        "$ref": "#/definitions/AgentExtension"
+                    },
+                    "type": "array"
+                },
                 "pushNotifications": {
                     "description": "true if the agent can notify updates to client.",
                     "type": "boolean"
@@ -207,6 +214,32 @@
             ],
             "type": "object"
         },
+        "AgentExtension": {
+            "description": "A declaration of an extension supported by an Agent.",
+            "properties": {
+                "description": {
+                    "description": "A description of how this agent uses this extension.",
+                    "type": "string"
+                },
+                "params": {
+                    "additionalProperties": {},
+                    "description": "Optional configuration for the extension.",
+                    "type": "object"
+                },
+                "required": {
+                    "description": "Whether the client must follow specific requirements of the extension.",
+                    "type": "boolean"
+                },
+                "uri": {
+                    "description": "The URI of the extension.",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "uri"
+            ],
+            "type": "object"
+        },
         "AgentProvider": {
             "description": "Represents the service provider of an agent.",
             "properties": {
@@ -288,6 +321,13 @@
                     "description": "Optional description for the artifact.",
                     "type": "string"
                 },
+                "extensions": {
+                    "description": "The URIs of extensions that are present or contributed to this Artifact.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
                 "metadata": {
                     "additionalProperties": {},
                     "description": "Extension metadata.",
@@ -1082,6 +1122,13 @@
                     "description": "The context the message is associated with",
                     "type": "string"
                 },
+                "extensions": {
+                    "description": "The URIs of extensions that are present or contributed to this Message.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
                 "kind": {
                     "const": "message",
                     "description": "Event type",
diff --git a/types/src/types.ts b/types/src/types.ts
@@ -25,9 +25,27 @@ export interface AgentCapabilities {
   pushNotifications?: boolean;
   /** true if the agent exposes status change history for tasks. */
   stateTransitionHistory?: boolean;
+  /** extensions supported by this agent. */
+  extensions?: AgentExtension[];
 }
 // --8<-- [end:AgentCapabilities]
 
+// --8<-- [start:AgentExtension]
+/**
+ * A declaration of an extension supported by an Agent.
+ */
+export interface AgentExtension {
+  /** The URI of the extension. */
+  uri: string;
+  /** A description of how this agent uses this extension. */
+  description?: string;
+  /** Whether the client must follow specific requirements of the extension. */
+  required?: boolean;
+  /** Optional configuration for the extension. */
+  params?: { [key: string]: any };
+}
+// --8<-- [end:AgentExtension]
+
 // --8<-- [start:AgentSkill]
 /**
  * Represents a unit of capability that an agent can perform.
@@ -273,6 +291,8 @@ export interface Artifact {
   metadata?: {
     [key: string]: any;
   };
+  /** The URIs of extensions that are present or contributed to this Artifact. */
+  extensions?: string[];
 }
 // --8<-- [end:Artifact]
 
@@ -287,6 +307,8 @@ export interface Message {
   metadata?: {
     [key: string]: any;
   };
+  /** The URIs of extensions that are present or contributed to this Message. */
+  extensions?: string[];
   /** List of tasks referenced as context by this message.*/
   referenceTaskIds?: string[];
   /** Identifier created by the message creator*/
