refactor(spec)!: Move extendedAgentCard field to AgentCapabilities (#1307)

Relocates `supports_extended_agent_card` from AgentCard to
AgentCapabilities for architectural consistency. All optional features
that enable specific operations now reside in the capabilities object.

Rationale:
- Consistent placement: streaming, push_notifications, and
state_transition_history are all in AgentCapabilities
- Improved discoverability: developers naturally check capabilities for
optional features
- Semantic correctness: extended agent card support is a capability

Changes:
- Proto: Removed field 13 from AgentCard, added field 5 to
AgentCapabilities
- Field renamed: supports_extended_agent_card → extended_agent_card
- Updated all references: AgentCard.supportsExtendedAgentCard →
AgentCard.capabilities.extendedAgentCard
- Updated JSON examples to reflect new structure
- Added migration guidance in Appendix A.2.2 of specification

Breaking change: Clients and agents must update capability checking
logic. See specification Appendix A.2.2 for migration steps.

Fixes #1229

---------

Co-authored-by: Luca Muscariello <[email protected]>
Co-authored-by: Darrel <[email protected]>

Author: 3 people

docs/llms.txt

@@ -42,11 +42,10 @@ Key features of the A2A protocol include: agent discovery via Agent Cards, stand
     -   `name`, `description`, `version`: (string) Agent's identity.
     -   `url`: (string) The preferred endpoint URL for the agent's A2A service.
     -   `provider`: (`AgentProvider`) Organization details.
-    -   `capabilities`: (`AgentCapabilities`) Features supported (streaming, push notifications, extensions).
+    -   `capabilities`: (`AgentCapabilities`) Features supported (streaming, push notifications, state transition history, extended agent card, extensions).
     -   `securitySchemes`, `security`: (object, array) Authentication and authorization requirements, following OpenAPI specifications.
     -   `defaultInputModes`, `defaultOutputModes`: (string[]) Default supported MIME types.
     -   `skills`: (`AgentSkill[]`) List of specific capabilities.
-    -   `supportsExtendedAgentCard`: (boolean) Indicates if a more detailed card is available post-authentication.
     -   `signatures`: (`AgentCardSignature[]`) JWS signatures for verifying the card's integrity.
 -   **`AgentSkill`:** A specific capability of an agent, with `id`, `name`, `description`, `tags`, and `examples`.
 -   **`Task`:** Represents a stateful unit of work.

docs/specification.md

@@ -417,7 +417,7 @@ The operation MUST permanently remove the specified push notification configurat
 
 #### 3.1.11. Get Extended Agent Card
 
-Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if `AgentCard.supportsExtendedAgentCard` is `true`.
+Retrieves a potentially more detailed version of the Agent Card after the client has authenticated. This endpoint is available only if `AgentCard.capabilities.extendedAgentCard` is `true`.
 
 **Inputs:**
 
@@ -437,7 +437,7 @@ Retrieves a potentially more detailed version of the Agent Card after the client
 - **Authentication**: The client MUST authenticate the request using one of the schemes declared in the public `AgentCard.securitySchemes` and `AgentCard.security` fields.
 - **Extended Information**: The operation MAY return different details based on client authentication level, including additional skills, capabilities, or configuration not available in the public Agent Card.
 - **Card Replacement**: Clients retrieving this extended 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.
-- **Availability**: This operation is only available if the public Agent Card declares `supportsExtendedAgentCard: true`.
+- **Availability**: This operation is only available if the public Agent Card declares `capabilities.extendedAgentCard: true`.
 
 For detailed security guidance on extended agent cards, see [Section 13.3 Extended Agent Card Access Control](#133-extended-agent-card-access-control).
 
@@ -586,7 +586,7 @@ Agents declare optional capabilities in their [`AgentCard`](#441-agentcard). Whe
 
 - **Push Notifications**: If `AgentCard.capabilities.pushNotifications` is `false` or not present, operations related to push notification configuration (Set, Get, List, Delete) **MUST** return [`PushNotificationNotSupportedError`](#332-error-handling).
 - **Streaming**: If `AgentCard.capabilities.streaming` is `false` or not present, attempts to use `SendStreamingMessage` or `SubscribeToTask` operations **MUST** return [`UnsupportedOperationError`](#332-error-handling).
-- **Extended Agent Card**: If `AgentCard.supportsExtendedAgentCard` is `false` or not present, attempts to call the Get Extended Agent Card operation **MUST** return [`UnsupportedOperationError`](#332-error-handling). If the agent declares support but has not configured an extended card, it **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling).
+- **Extended Agent Card**: If `AgentCard.capabilities.extendedAgentCard` is `false` or not present, attempts to call the Get Extended Agent Card operation **MUST** return [`UnsupportedOperationError`](#332-error-handling). If the agent declares support but has not configured an extended card, it **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling).
 - **Extensions**: When a client requests use of an extension marked as `required: true` in the Agent Card but the client does not declare support for it, the agent **MUST** return [`ExtensionSupportRequiredError`](#332-error-handling).
 
 Clients **SHOULD** validate capability support by examining the Agent Card before attempting operations that require optional capabilities.
@@ -1834,7 +1834,9 @@ Host: example.com
 
 ```json
 {
-  "supportsExtendedAgentCard": true,
+  "capabilities": {
+    "extendedAgentCard": true
+  },
   "securitySchemes": {
     "google": {
       "openIdConnectSecurityScheme": {
@@ -2108,7 +2110,8 @@ Clients verifying Agent Card signatures **MUST**:
   "capabilities": {
     "streaming": true,
     "pushNotifications": true,
-    "stateTransitionHistory": false
+    "stateTransitionHistory": false,
+    "extendedAgentCard": true
   },
   "securitySchemes": {
     "google": {
@@ -2154,7 +2157,6 @@ Clients verifying Agent Card signatures **MUST**:
       ]
     }
   ],
-  "supportsExtendedAgentCard": true,
   "signatures": [
     {
       "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0",
@@ -3114,8 +3116,8 @@ The extended Agent Card feature allows agents to provide additional capabilities
 
 **Availability Declaration:**
 
-- Agents declare extended card support via `AgentCard.supportsExtendedAgentCard`
-- When `supportsExtendedAgentCard` is `false` or not present, the operation **MUST** return [`UnsupportedOperationError`](#332-error-handling)
+- Agents declare extended card support via `AgentCard.capabilities.extendedAgentCard`
+- When `capabilities.extendedAgentCard` is `false` or not present, the operation **MUST** return [`UnsupportedOperationError`](#332-error-handling)
 - When support is declared but no extended card is configured, the operation **MUST** return [`ExtendedAgentCardNotConfiguredError`](#332-error-handling)
 
 See also: [Section 3.1.11 Get Extended Agent Card](#3111-get-extended-agent-card) and [Section 3.3.4 Capability Validation](#334-capability-validation).
@@ -3480,6 +3482,71 @@ This change aligns with modern API design practices and Protocol Buffers' `oneof
 - Eliminates the need for representing inheritance structures in schema languages
 - Improves type safety in strongly-typed languages
 
+#### A.2.2 Breaking Change: Extended Agent Card Field Relocated
+
+**Version 1.0 relocates the extended agent card capability** from a top-level field to the capabilities object for architectural consistency.
+
+**Legacy Structure (pre-1.0):**
+
+```json
+{
+  "supportsExtendedAgentCard": true,
+  "capabilities": {
+    "streaming": true
+  }
+}
+```
+
+**Current Structure (1.0+):**
+
+```json
+{
+  "capabilities": {
+    "streaming": true,
+    "extendedAgentCard": true
+  }
+}
+```
+
+**Proto Changes:**
+
+- Removed: `AgentCard.supports_extended_agent_card` (field 13)
+- Added: `AgentCapabilities.extended_agent_card` (field 5)
+
+**Migration Steps:**
+
+For **Agent Implementations**:
+
+1. Remove `supportsExtendedAgentCard` from top-level AgentCard
+2. Add `extendedAgentCard` to `capabilities` object
+3. Update validation: `agentCard.capabilities?.extendedAgentCard`
+
+For **Client Implementations**:
+
+1. Update capability checks: `agentCard.capabilities?.extendedAgentCard`
+2. Temporary fallback (transition period):
+
+   ```javascript
+   const supported = agentCard.capabilities?.extendedAgentCard ||
+                     agentCard.supportsExtendedAgentCard;
+   ```
+
+3. Remove fallback after agent ecosystem migrates
+
+For **SDK Developers**:
+
+1. Regenerate code from updated proto
+2. Update type definitions
+3. Document breaking change in release notes
+
+**Rationale:**
+
+All optional features enabling specific operations (`streaming`, `pushNotifications`, `stateTransitionHistory`) reside in `AgentCapabilities`. Moving `extendedAgentCard` achieves:
+
+- Architectural consistency
+- Improved discoverability
+- Semantic correctness (it is a capability)
+
 ### A.3 Future Automation
 
 Once the proto→schema generation pipeline lands, this appendix will be partially auto-generated (legacy mapping table sourced from a maintained manifest). Until then, edits MUST be manual and reviewed in PRs affecting `a2a.proto`.

specification/grpc/a2a.proto

@@ -449,8 +449,6 @@ message AgentCard {
   // a descriptive concept but represents a more focused set of behaviors that the
   // agent is likely to succeed at.
   repeated AgentSkill skills = 12 [(google.api.field_behavior) = REQUIRED];
-  // Whether the agent supports providing an extended agent card when authenticated.
-  optional bool supports_extended_agent_card = 13;
   // JSON Web Signatures computed for this AgentCard.
   repeated AgentCardSignature signatures = 17;
   // An optional URL to an icon for the agent.
@@ -481,6 +479,8 @@ message AgentCapabilities {
   repeated AgentExtension extensions = 3;
   // Indicates if the agent provides a history of state transitions for a task.
   optional bool state_transition_history = 4;
+  // Indicates if the agent supports providing an extended agent card when authenticated.
+  optional bool extended_agent_card = 5;
 }
 // --8<-- [end:AgentCapabilities]