feat!: Add method for fetching extended card (#929)

# Description
This change adds support for a new JSON-RPC method
`agent/getAuthenticatedExtendedCard` for fetching authenticated extended
card.

This is only applicable if `AgentCard.supportsAuthenticatedExtendedCard`
bit is set to `true` that allows fetching authenticated context specific
agent card.

In the previous versions, the extended card was served via
`{AgentCard.url}/../agent/authenticatedExtendedCard` endpoint. This
endpoint is being removed in favor of the JSON-RPC method. This endpoint
will be deprecated in the SDKs and will be removed in a future release.

Release-As: 0.3.0

---------

Co-authored-by: a2a-bot <[email protected]>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Holt Skinner <[email protected]>

Author: 4 people

docs/llms.txt

@@ -18,7 +18,7 @@ The repository provides:
 
 Key features of the A2A protocol highlighted by the specification and samples include: agent discovery via Agent Cards, standardized task management (send, get, cancel), support for different content types (text, files, structured data) via `Parts` and `Artifacts`, streaming updates for long-running tasks, and mechanisms for push notifications. The project is open source and encourages community contribution.
 
-# A2A (Agent2Agent) Protocol 
+# A2A (Agent2Agent) Protocol
 
 ## 1. Overview
 
@@ -149,10 +149,9 @@ Key features of the A2A protocol highlighted by the specification and samples in
     - `message`: (`Message`) The message to send.
     - `configuration`: (`MessageSendConfiguration`) Optional configuration for the message.
     - `metadata`: (object) Custom key-value data for client use (optional).
-- **`agent/authenticatedExtendedCard`:** (HTTP GET)
+- **`agent/getAuthenticatedExtendedCard`:** (JSON-RPC Method)
     - Retrieves a potentially more detailed version of the Agent Card after the client has authenticated.
     - Available only if `AgentCard.supportsAuthenticatedExtendedCard` is `true`.
-    - Endpoint URL: `{AgentCard.url}/../agent/authenticatedExtendedCard`
     - Authentication: Required using one of the schemes declared in the public `AgentCard.securitySchemes`.
     - Response: Complete `AgentCard` object with potentially additional details.
 
@@ -234,7 +233,7 @@ Key features of the A2A protocol highlighted by the specification and samples in
 - **Communication:** Uses `Message` objects containing `Part`s (text, file, data). Task outputs are represented as `Artifact`s, also containing `Part`s.
 - **Streaming:** Long-running tasks can provide real-time updates using Server-Sent Events (SSE) via `message/stream`. Updates are sent as `MessageEvent`, `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`. Reconnection after interruptions is supported via `tasks/resubscribe`.
 - **Push Notifications:** Agents can proactively notify clients about task updates using webhook URLs provided via `tasks/pushNotificationConfig/set`. Authentication mechanisms (e.g., Bearer tokens via JWT signed with keys from agent's JWKS endpoint) are supported for secure communication.
-- **Authentication:** Defined in `AgentCard` (via `securitySchemes` and `security` fields) and `PushNotificationConfig`. Can involve various schemes (e.g., API keys, OAuth, JWT). The protocol supports authenticated extended Agent Card retrieval via the `agent/authenticatedExtendedCard` endpoint. Samples use JWT for push notifications and secure communication.
+- **Authentication:** Defined in `AgentCard` (via `securitySchemes` and `security` fields) and `PushNotificationConfig`. Can involve various schemes (e.g., API keys, OAuth, JWT). The protocol supports authenticated extended Agent Card retrieval via the `agent/getAuthenticatedExtendedCard` JSON-RPC method. Samples use JWT for push notifications and secure communication.
 - **Forms:** Structured data can be requested and submitted using `DataPart` within Messages/Artifacts (demonstrated in ADK sample).
 
 ## 4. Security Considerations

docs/specification.md

@@ -1106,25 +1106,19 @@ The purpose is to resume receiving _subsequent_ updates. The server's behavior r
 
 </div>
 
-### 7.10. `agent/authenticatedExtendedCard`
+### 7.10. `agent/getAuthenticatedExtendedCard`
 
 Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if `AgentCard.supportsAuthenticatedExtendedCard` is `true`.
 
-- **Endpoint URL**: `{AgentCard.url}/../agent/authenticatedExtendedCard` (relative to the base URL specified in the public Agent Card).
-- **HTTP Method**: `GET`
 - **Authentication**: The client **MUST** authenticate the request using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields.
-- **Request `params`**: None (HTTP GET request).
 - **Response `result` type (on success)**: `AgentCard` (A complete Agent Card object, which may contain additional details or skills not present in the public card).
 - **Response `error` type (on failure)**: Standard HTTP error codes.
     - `401 Unauthorized`: Authentication failed (missing or invalid credentials). The server **SHOULD** include a `WWW-Authenticate` header.
-    - `403 Forbidden`: Authentication succeeded, but the client/user is not authorized to access the extended card.
-    - `404 Not Found`: The `supportsAuthenticatedExtendedCard` capability is declared, but the server has not implemented this endpoint at the specified path.
-    - `5xx Server Error`: An internal server error occurred.
 
 <div class="grid cards" markdown>
 
 === "JSON-RPC"
-    -   **URL:** `agent/authenticatedExtendedCard`
+    -   **URL:** `agent/getAuthenticatedExtendedCard`
     -   **HTTP Method:** `POST`
     -   **Payload:** None
     -   **Response:** `AgentCard`
@@ -1145,16 +1139,8 @@ Retrieves a potentially more detailed version of the Agent Card after the client
 
 Clients retrieving this authenticated card **SHOULD** replace their cached public Agent Card with the content received from this endpoint for the duration of their authenticated session or until the card's version changes.
 
-#### 7.10.1. `AuthenticatedExtendedCardParams` Object
-
-This endpoint does not use JSON-RPC `params`. Any parameters would be included as HTTP query parameters if needed (though none are defined by the standard).
-
-#### 7.10.2. `AuthenticatedExtendedCardResponse` Object
-
-The successful response body is a JSON object conforming to the `AgentCard` interface.
-
 ```ts { .no-copy }
---8<-- "types/src/types.ts:AuthenticatedExtendedCardResponse"
+--8<-- "types/src/types.ts:GetAuthenticatedExtendedCardSuccessResponse"
 ```
 
 ## 8. Error Handling
@@ -1186,6 +1172,7 @@ These are custom error codes defined within the JSON-RPC server error range (`-3
 | `-32004` | `UnsupportedOperationError`         | This operation is not supported    | The requested operation or a specific aspect of it (perhaps implied by parameters) is not supported by this server agent implementation. Broader than just method not found.                                                         |
 | `-32005` | `ContentTypeNotSupportedError`      | Incompatible content types         | A [Media Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) provided in the request's `message.parts` (or implied for an artifact) is not supported by the agent or the specific skill being invoked. |
 | `-32006` | `InvalidAgentResponseError`         | Invalid agent response type        | Agent generated an invalid response for the requested method                                                                                                                                                                         |
+| `-32007` | `AuthenticatedExtendedCardNotConfiguredError`         | Authenticated Extended Card not configured        | The agent does not have an Authenticated Extended Card configured.|
 
 Servers MAY define additional error codes within the `-32000` to `-32099` range for more specific scenarios not covered above, but they **SHOULD** document these clearly. The `data` field of the `JSONRPCError` object can be used to provide more structured details for any error.
 
@@ -1209,16 +1196,19 @@ This section provides illustrative JSON examples of common A2A interactions. Tim
 
 3. **Client obtains necessary credentials out-of-band (e.g., performs OAuth 2.0 flow with Google, resulting in an access token).**
 
-4. **Client fetches the authenticated extended Agent Card:**
+4. **Client fetches the authenticated extended Agent Card using `agent/getAuthenticatedExtendedCard` request:**
 
-   ```none
-   GET https://example.com/a2a/agent/authenticatedExtendedCard
-   Authorization: Bearer <obtained_access_token>
+   ```json
+   {
+     "jsonrpc": "2.0",
+     "id": 1,
+     "method": "agent/getAuthenticatedExtendedCard"
+   }
    ```
 
 5. **Server authenticates and authorizes the request.**
 
-6. **Server responds with the full Agent Card:**
+6. **Server responds with the full Agent Card as the JSON-RPC result:**
 
 ### 9.2. Basic Execution (Synchronous / Polling Style)
 

specification/json/a2a.json

@@ -941,7 +941,8 @@ export type JSONRPCResponse =
   | SetTaskPushNotificationConfigResponse
   | GetTaskPushNotificationConfigResponse
   | ListTaskPushNotificationConfigResponse
-  | DeleteTaskPushNotificationConfigResponse;
+  | DeleteTaskPushNotificationConfigResponse
+  | GetAuthenticatedExtendedCardResponse;
 // --8<-- [end:JSONRPCResponse]
 
 // --8<-- [start:SendMessageRequest]
@@ -1231,6 +1232,40 @@ export type DeleteTaskPushNotificationConfigResponse =
   | JSONRPCErrorResponse;
 // --8<-- [end:DeleteTaskPushNotificationConfigResponse]
 
+// --8<-- [start:GetAuthenticatedExtendedCardRequest]
+/**
+ * Represents a JSON-RPC request for the `agent/getAuthenticatedExtendedCard` method.
+ */
+export interface GetAuthenticatedExtendedCardRequest extends JSONRPCRequest {
+  /** The identifier for this request. */
+  id: number | string;
+  /** The method name. Must be 'agent/getAuthenticatedExtendedCard'. */
+  readonly method: "agent/getAuthenticatedExtendedCard";
+  /** This method does not accept parameters. */
+  params?: never;
+}
+// --8<-- [end:GetAuthenticatedExtendedCardRequest]
+
+// --8<-- [start:GetAuthenticatedExtendedCardSuccessResponse]
+/**
+ * Represents a successful JSON-RPC response for the `agent/getAuthenticatedExtendedCard` method.
+ */
+export interface GetAuthenticatedExtendedCardSuccessResponse
+  extends JSONRPCSuccessResponse {
+  /** The result is an Agent Card object. */
+  result: AgentCard;
+}
+// --8<-- [end:GetAuthenticatedExtendedCardSuccessResponse]
+
+// --8<-- [start:GetAuthenticatedExtendedCardResponse]
+/**
+ * Represents a JSON-RPC response for the `agent/getAuthenticatedExtendedCard` method.
+ */
+export type GetAuthenticatedExtendedCardResponse =
+  | GetAuthenticatedExtendedCardSuccessResponse
+  | JSONRPCErrorResponse;
+// --8<-- [end:GetAuthenticatedExtendedCardResponse]
+
 // --8<-- [start:A2ARequest]
 /**
  * A discriminated union representing all possible JSON-RPC 2.0 requests supported by the A2A specification.
@@ -1244,7 +1279,8 @@ export type A2ARequest =
   | GetTaskPushNotificationConfigRequest
   | TaskResubscriptionRequest
   | ListTaskPushNotificationConfigRequest
-  | DeleteTaskPushNotificationConfigRequest;
+  | DeleteTaskPushNotificationConfigRequest
+  | GetAuthenticatedExtendedCardRequest;
 // --8<-- [end:A2ARequest]
 
 // --8<-- [start:JSONParseError]
@@ -1414,6 +1450,23 @@ export interface InvalidAgentResponseError extends JSONRPCError {
 }
 // --8<-- [end:InvalidAgentResponseError]
 
+// --8<-- [start:AuthenticatedExtendedCardNotConfiguredError]
+/**
+ * An A2A-specific error indicating that the agent does not have an
+ * Authenticated Extended Card configured
+ */
+export interface AuthenticatedExtendedCardNotConfiguredError
+  extends JSONRPCError {
+  /** The error code for when an authenticated extended card is not configured. */
+  readonly code: -32007;
+  /**
+   * The error message.
+   * @default "Authenticated Extended Card not configured"
+   */
+  message: string;
+}
+// --8<-- [end:AuthenticatedExtendedCardNotConfiguredError]
+
 // --8<-- [start:A2AError]
 /**
  * A discriminated union of all standard JSON-RPC and A2A-specific error types.
@@ -1429,5 +1482,6 @@ export type A2AError =
   | PushNotificationNotSupportedError
   | UnsupportedOperationError
   | ContentTypeNotSupportedError
-  | InvalidAgentResponseError;
+  | InvalidAgentResponseError
+  | AuthenticatedExtendedCardNotConfiguredError;
 // --8<-- [end:A2AError]