Compare commits

...

2 Commits

Author SHA1 Message Date
Darrel Miller
cbaa625554 Fixes to indents. 2026-01-15 21:52:10 -05:00
Darrel Miller (from Dev Box)
64fb1441c5 fix: Clarified versioning strategy 2026-01-13 22:12:14 -05:00
2 changed files with 289 additions and 472 deletions

View File

@ -12,6 +12,7 @@
```proto { .no-copy }
--8<-- "specification/grpc/a2a.proto:{{ region_tag }}"
```
{% endmacro %}
??? note "**Latest Released Version** [`0.3.0`](https://a2a-protocol.org/v0.3.0/specification)"
@ -125,7 +126,7 @@ In addition to the protocol requirements defined in this document, the file `spe
**Change Control and Deprecation Lifecycle:**
- Introduction: When a proto message or field is renamed, the new name is added while existing published names remain available, but marked deprecated, until the next major release.
- Documentation: This specification MUST include a Migration Appendix (Appendix A) enumerating legacy→current name mappings with planned removal versions.
- Documentation: Migration guidance MUST be provided via an ancillary document when introducing major breaking changes.
- Anchors: Legacy documentation anchors MUST be preserved (as hidden HTML anchors) to avoid breaking inbound links.
- SDK/Schema Aliases: SDKs and JSON Schemas SHOULD provide deprecated alias types/definitions to maintain backward compatibility.
- Removal: A deprecated name SHOULD NOT be removed earlier than the next major version after introduction of its replacement.
@ -153,7 +154,7 @@ A2A revolves around several key concepts. For detailed explanations, please refe
- **Agent Card:** A JSON metadata document published by an A2A Server, describing its identity, capabilities, skills, service endpoint, and authentication requirements.
- **Message:** A communication turn between a client and a remote agent, having a `role` ("user" or "agent") and containing one or more `Parts`.
- **Task:** The fundamental unit of work managed by A2A, identified by a unique ID. Tasks are stateful and progress through a defined lifecycle.
- **Part:** The smallest unit of content within a Message or Artifact (e.g., `TextPart`, `FilePart`, `DataPart`).
- **Part:** The smallest unit of content within a Message or Artifact. Parts can contain text, file references, or structured data.
- **Artifact:** An output (e.g., a document, image, structured data) generated by the agent as a result of a task, composed of `Parts`.
- **Streaming:** Real-time, incremental updates for tasks (status changes, artifact chunks) delivered via protocol-specific streaming mechanisms.
- **Push Notifications:** Asynchronous task updates delivered via server-initiated HTTP POST requests to a client-provided webhook URL, for long-running or disconnected scenarios.
@ -268,11 +269,11 @@ None specific to this operation beyond standard protocol errors.
The operation MUST return only tasks visible to the authenticated client and MUST use cursor-based pagination for performance and consistency. Tasks MUST be sorted by last update time in descending order. Implementations MUST implement appropriate authorization scoping to ensure clients can only access authorized tasks. See [Section 13.1 Data Access and Authorization Scoping](#131-data-access-and-authorization-scoping) for detailed security requirements.
***Pagination Strategy:***
**_Pagination Strategy:_**
This method uses cursor-based pagination (via `pageToken`/`nextPageToken`) rather than offset-based pagination for better performance and consistency, especially with large datasets. Cursor-based pagination avoids the "deep pagination problem" where skipping large numbers of records becomes inefficient for databases. This approach is consistent with the gRPC specification, which also uses cursor-based pagination (page_token/next_page_token).
***Ordering:***
**_Ordering:_**
Implementations MUST return tasks sorted by their last update time in descending order (most recently updated tasks first). This ensures consistent pagination and allows clients to efficiently monitor recent task activity.
@ -348,7 +349,7 @@ Creates or updates a push notification configuration for a task to receive async
The operation MUST establish a webhook endpoint for task update notifications. When task updates occur, the agent will send HTTP POST requests to the configured webhook URL with [`StreamResponse`](#323-stream-response) payloads (see [Push Notification Payload](#433-push-notification-payload) for details). This operation is only available if the agent supports push notifications capability. The configuration MUST persist until task completion or explicit deletion.
<span id="tasks-push-notification-config-operations"></span><span id="grpc-push-notification-operations"></span><span id="push-notification-operations"></span>
<span id="tasks-push-notification-config-operations"></span><span id="grpc-push-notification-operations"></span><span id="push-notification-operations"></span>
#### 3.1.8. Get Push Notification Config
@ -494,10 +495,10 @@ A key-value map for passing horizontally applicable context or parameters with c
**Standard A2A Service Parameters:**
| Name | Description | Example Value |
| Name | Description | Example Value |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
| `A2A-Extensions` | Comma-separated list of extension URIs that the client wants to use for the request | `https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1` |
| `A2A-Version` | The A2A protocol version that the client is using. If the version is not supported, the agent returns [`VersionNotSupportedError`](#332-error-handling) | `0.3` |
| `A2A-Extensions` | Comma-separated list of extension URIs that the client wants to use for the request | `https://example.com/extensions/geolocation/v1,https://standards.org/extensions/citations/v1` |
| `A2A-Version` | The A2A protocol version that the client is using. If the version is not supported, the agent returns [`VersionNotSupportedError`](#332-error-handling) | `0.3` |
As service parameter names MAY need to co-exist with other parameters defined by the underlying transport protocol or infrastructure, all service parameters defined by this specification will be prefixed with `a2a-`.
@ -516,6 +517,7 @@ All operations may return errors in the following categories. Servers **MUST** r
**Error Categories and Server Requirements:**
- **Authentication Errors**: Invalid or missing credentials
- Servers **MUST** reject requests with invalid or missing authentication credentials
- Servers **SHOULD** include authentication challenge information in the error response
- Servers **SHOULD** specify which authentication scheme is required
@ -523,6 +525,7 @@ All operations may return errors in the following categories. Servers **MUST** r
- Example scenarios: Missing bearer token, expired API key, invalid OAuth token
- **Authorization Errors**: Insufficient permissions for requested operation
- Servers **MUST** return an authorization error when the authenticated client lacks required permissions
- Servers **SHOULD** indicate what permission or scope is missing (without leaking sensitive information about resources the client cannot access)
- Servers **MUST NOT** reveal the existence of resources the client is not authorized to access
@ -530,6 +533,7 @@ All operations may return errors in the following categories. Servers **MUST** r
- Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes
- **Validation Errors**: Invalid input parameters or message format
- Servers **MUST** validate all input parameters before processing
- Servers **SHOULD** specify which parameter(s) failed validation and why
- Servers **SHOULD** provide guidance on valid parameter values or formats
@ -537,6 +541,7 @@ All operations may return errors in the following categories. Servers **MUST** r
- Example scenarios: Invalid task ID format, missing required message parts, unsupported content type
- **Resource Errors**: Requested task not found or not accessible
- Servers **MUST** return a not found error when a requested resource does not exist or is not accessible to the authenticated client
- Servers **SHOULD NOT** distinguish between "does not exist" and "not authorized" to prevent information leakage
- Example error codes: HTTP `404 Not Found`, gRPC `NOT_FOUND`, JSON-RPC custom error (see A2A-specific errors)
@ -752,21 +757,9 @@ The A2A protocol defines a canonical data model using Protocol Buffers. All prot
{{ proto_to_table("specification/grpc/a2a.proto", "Part") }}
<a id="FilePart"></a>
#### 4.1.7. FilePart
{{ proto_to_table("specification/grpc/a2a.proto", "FilePart") }}
<a id="DataPart"></a>
#### 4.1.8. DataPart
{{ proto_to_table("specification/grpc/a2a.proto", "DataPart") }}
<a id="Artifact"></a>
#### 4.1.9. Artifact
#### 4.1.7. Artifact
{{ proto_to_table("specification/grpc/a2a.proto", "Artifact") }}
@ -871,7 +864,7 @@ For detailed security guidance on push notifications, see [Section 13.2 Push Not
- **`supportsExtendedAgentCard`** (optional, boolean): Whether the agent supports providing an extended agent card when authenticated.
- **`signatures`** (optional, array of [`AgentCardSignature`](#447-agentcardsignature)): JSON Web Signatures computed for this AgentCard.
- **`iconUrl`** (optional, string): An optional URL to an icon for the agent.
<a id="AgentProvider"></a>
<a id="AgentProvider"></a>
#### 4.4.2. AgentProvider
@ -984,54 +977,54 @@ The A2A protocol supports extensions to provide additional functionality or data
Agents declare their supported extensions in the [`AgentCard`](#441-agentcard) using the `extensions` field, which contains an array of [`AgentExtension`](#444-agentextension) objects.
*Example: Agent declaring extension support in AgentCard:*
_Example: Agent declaring extension support in AgentCard:_
```json
{
"protocolVersion": "0.3.0",
"name": "Research Assistant Agent",
"description": "AI agent for academic research and fact-checking",
"supportedInterfaces": [
{
"url": "https://research-agent.example.com/a2a/v1",
"protocolBinding": "HTTP+JSON"
}
],
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extensions": [
{
"uri": "https://standards.org/extensions/citations/v1",
"description": "Provides citation formatting and source verification",
"required": false
},
{
"uri": "https://example.com/extensions/geolocation/v1",
"description": "Location-based search capabilities",
"required": false
}
"protocolVersion": "0.3.0",
"name": "Research Assistant Agent",
"description": "AI agent for academic research and fact-checking",
"supportedInterfaces": [
{
"url": "https://research-agent.example.com/a2a/v1",
"protocolBinding": "HTTP+JSON"
}
],
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extensions": [
{
"uri": "https://standards.org/extensions/citations/v1",
"description": "Provides citation formatting and source verification",
"required": false
},
{
"uri": "https://example.com/extensions/geolocation/v1",
"description": "Location-based search capabilities",
"required": false
}
]
},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"],
"skills": [
{
"id": "academic-research",
"name": "Academic Research Assistant",
"description": "Provides research assistance with citations and source verification",
"tags": ["research", "citations", "academic"],
"examples": ["Find peer-reviewed articles on climate change"],
"inputModes": ["text/plain"],
"outputModes": ["text/plain"]
}
]
},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"],
"skills": [
{
"id": "academic-research",
"name": "Academic Research Assistant",
"description": "Provides research assistance with citations and source verification",
"tags": ["research", "citations", "academic"],
"examples": ["Find peer-reviewed articles on climate change"],
"inputModes": ["text/plain"],
"outputModes": ["text/plain"]
}
]
}
```
Clients indicate their desire to opt into the use of specific extensions through binding-specific mechanisms such as HTTP headers, gRPC metadata, or JSON-RPC request parameters that identify the extension identifiers they wish to utilize during the interaction.
*Example: HTTP client opting into extensions using headers:*
_Example: HTTP client opting into extensions using headers:_
```http
POST /v1/message:send HTTP/1.1
@ -1063,23 +1056,21 @@ Extensions can be integrated into the A2A protocol at several well-defined exten
Messages can be extended to allow clients to provide additional strongly typed context or parameters relevant to the message being sent, or TaskStatus Messages to include extra information about the task's progress.
*Example: A location extension using the extensions and metadata arrays:*
_Example: A location extension using the extensions and metadata arrays:_
```json
{
"role": "user",
"parts": [
{"text": "Find restaurants near me"}
],
"extensions": ["https://example.com/extensions/geolocation/v1"],
"metadata": {
"https://example.com/extensions/geolocation/v1": {
"latitude": 37.7749,
"longitude": -122.4194,
"accuracy": 10.0,
"timestamp": "2025-10-21T14:30:00Z"
"role": "user",
"parts": [{ "text": "Find restaurants near me" }],
"extensions": ["https://example.com/extensions/geolocation/v1"],
"metadata": {
"https://example.com/extensions/geolocation/v1": {
"latitude": 37.7749,
"longitude": -122.4194,
"accuracy": 10.0,
"timestamp": "2025-10-21T14:30:00Z"
}
}
}
}
```
@ -1087,31 +1078,31 @@ Messages can be extended to allow clients to provide additional strongly typed c
Artifacts can include extension data to provide strongly typed context or metadata about the generated content.
*Example: An artifact with citation extension for research sources:*
_Example: An artifact with citation extension for research sources:_
```json
{
"artifactId": "research-summary-001",
"name": "Climate Change Summary",
"parts": [
{
"text": "Global temperatures have risen by 1.1°C since pre-industrial times, with significant impacts on weather patterns and sea levels."
}
],
"extensions": ["https://standards.org/extensions/citations/v1"],
"metadata": {
"https://standards.org/extensions/citations/v1": {
"sources": [
"artifactId": "research-summary-001",
"name": "Climate Change Summary",
"parts": [
{
"title": "Global Temperature Anomalies - 2023 Report",
"authors": ["Smith, J.", "Johnson, M."],
"url": "https://climate.gov/reports/2023-temperature",
"accessDate": "2025-10-21",
"relevantText": "Global temperatures have risen by 1.1°C"
"text": "Global temperatures have risen by 1.1°C since pre-industrial times, with significant impacts on weather patterns and sea levels."
}
],
"extensions": ["https://standards.org/extensions/citations/v1"],
"metadata": {
"https://standards.org/extensions/citations/v1": {
"sources": [
{
"title": "Global Temperature Anomalies - 2023 Report",
"authors": ["Smith, J.", "Johnson, M."],
"url": "https://climate.gov/reports/2023-temperature",
"accessDate": "2025-10-21",
"relevantText": "Global temperatures have risen by 1.1°C"
}
]
}
]
}
}
}
```
@ -1220,9 +1211,9 @@ The A2A protocol uses [`google.protobuf.Timestamp`](https://protobuf.dev/referen
```json
{
"timestamp": "2025-10-28T10:30:00.000Z",
"createdAt": "2025-10-28T14:25:33.142Z",
"lastModified": "2025-10-31T17:45:22.891Z"
"timestamp": "2025-10-28T10:30:00.000Z",
"createdAt": "2025-10-28T14:25:33.142Z",
"lastModified": "2025-10-31T17:45:22.891Z"
}
```
@ -1691,11 +1682,9 @@ Authorization: Bearer token
"text": "Analyze this image and highlight any faces."
},
{
"file": {
"name": "input_image.png",
"mediaType": "image/png",
"fileWithBytes": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
}
"bytes": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
"filename": "input_image.png",
"mediaType": "image/png"
}
],
"messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6"
@ -1723,11 +1712,9 @@ Content-Type: application/a2a+json
"name": "processed_image_with_faces.png",
"parts": [
{
"file": {
"name": "output.png",
"mediaType": "image/png",
"fileWithUri": "https://storage.example.com/processed/task-bbb/output.png?token=xyz"
}
"url": "https://storage.example.com/processed/task-bbb/output.png?token=xyz",
"filename": "output.png",
"mediaType": "image/png"
}
]
}
@ -1754,8 +1741,8 @@ Authorization: Bearer token
"parts": [
{
"text": "Show me a list of my open IT tickets",
"mediaType": "application/json",
"metadata": {
"mediaType": "application/json",
"schema": {
"type": "array",
"items": {
@ -1817,14 +1804,14 @@ Host: example.com
```json
{
"supportsExtendedAgentCard": true,
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
"supportsExtendedAgentCard": true,
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}
}
}
```
@ -1946,12 +1933,14 @@ Before signing, the Agent Card content **MUST** be canonicalized using the JSON
**Canonicalization Rules:**
1. **Field Presence and Default Value Handling**: Before canonicalization, the JSON representation **MUST** respect Protocol Buffer field presence semantics as defined in [Section 5.7](#57-field-presence-and-optionality). This ensures that the canonical form accurately reflects which fields were explicitly provided versus which were omitted, enabling signature verification when Agent Cards are reconstructed:
- **Optional fields not explicitly set**: Fields marked with the `optional` keyword that were not explicitly set **MUST** be omitted from the JSON object
- **Optional fields explicitly set to defaults**: Fields marked with `optional` that were explicitly set to a value (even if that value matches a default) **MUST** be included in the JSON object
- **Required fields**: Fields marked with `REQUIRED` **MUST** always be present, even if the field value matches the default.
- **Default values**: Fields with default values **MUST** be omitted unless the field is marked as `REQUIRED` or has the `optional` keyword.
2. **RFC 8785 Compliance**: The Agent Card JSON **MUST** be canonicalized according to RFC 8785, which specifies:
- Predictable ordering of object properties (lexicographic by key)
- Consistent representation of numbers, strings, and other primitive values
- Removal of insignificant whitespace
@ -1964,14 +1953,14 @@ Original Agent Card fragment:
```json
{
"name": "Example Agent",
"description": "",
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extensions": []
},
"skills": []
"name": "Example Agent",
"description": "",
"capabilities": {
"streaming": false,
"pushNotifications": false,
"extensions": []
},
"skills": []
}
```
@ -1988,7 +1977,12 @@ Applying the canonicalization rules:
After applying RFC 8785:
```json
{"capabilities":{"pushNotifications":false,"streaming":false},"description":"","name":"Example Agent","skills":[]}
{
"capabilities": { "pushNotifications": false, "streaming": false },
"description": "",
"name": "Example Agent",
"skills": []
}
```
#### 8.4.2. Signature Format
@ -2014,16 +2008,19 @@ The protected header **MAY** include:
**Signature Generation Process:**
1. **Prepare the payload:**
- Remove properties with default values from the Agent Card
- Exclude the `signatures` field
- Canonicalize the resulting JSON using RFC 8785 to produce the canonical payload
2. **Create the protected header:**
- Construct a JSON object with the required header parameters (`alg`, `typ`, `kid`) and any optional parameters (`jku`)
- Serialize the header to JSON
- Base64url-encode the serialized header to produce the `protected` field value
3. **Compute the signature:**
- Construct the JWS Signing Input: `ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload))`
- Sign the JWS Signing Input using the algorithm specified in the `alg` header parameter and the private key
- Base64url-encode the resulting signature bytes to produce the `signature` field value
@ -2039,15 +2036,20 @@ Given a canonical Agent Card payload and signing key, the signature generation p
```json
{
"protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0",
"signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ"
"protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0",
"signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ"
}
```
Where the `protected` value decodes to:
```json
{"alg":"ES256","typ":"JOSE","kid":"key-1","jku":"https://example.com/agent/jwks.json"}
{
"alg": "ES256",
"typ": "JOSE",
"kid": "key-1",
"jku": "https://example.com/agent/jwks.json"
}
```
#### 8.4.3. Signature Verification
@ -2073,77 +2075,86 @@ Clients verifying Agent Card signatures **MUST**:
```json
{
"protocolVersion": "0.3.0",
"name": "GeoSpatial Route Planner Agent",
"description": "Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.",
"supportedInterfaces": [
{"url": "https://georoute-agent.example.com/a2a/v1", "protocolBinding": "JSONRPC"},
{"url": "https://georoute-agent.example.com/a2a/grpc", "protocolBinding": "GRPC"},
{"url": "https://georoute-agent.example.com/a2a/json", "protocolBinding": "HTTP+JSON"}
],
"provider": {
"organization": "Example Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
},
"iconUrl": "https://georoute-agent.example.com/icon.png",
"version": "1.2.0",
"documentationUrl": "https://docs.examplegeoservices.com/georoute-agent/api",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"stateTransitionHistory": false
},
"securitySchemes": {
"google": {
"type": "openIdConnect",
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
},
"security": [{ "google": ["openid", "profile", "email"] }],
"defaultInputModes": ["application/json", "text/plain"],
"defaultOutputModes": ["application/json", "image/png"],
"skills": [
{
"id": "route-optimizer-traffic",
"name": "Traffic-Aware Route Optimizer",
"description": "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).",
"tags": ["maps", "routing", "navigation", "directions", "traffic"],
"examples": [
"Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.",
"{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}"
],
"inputModes": ["application/json", "text/plain"],
"outputModes": [
"application/json",
"application/vnd.geo+json",
"text/html"
]
"protocolVersion": "0.3.0",
"name": "GeoSpatial Route Planner Agent",
"description": "Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.",
"supportedInterfaces": [
{
"url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC"
},
{
"url": "https://georoute-agent.example.com/a2a/grpc",
"protocolBinding": "GRPC"
},
{
"url": "https://georoute-agent.example.com/a2a/json",
"protocolBinding": "HTTP+JSON"
}
],
"provider": {
"organization": "Example Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
},
{
"id": "custom-map-generator",
"name": "Personalized Map Generator",
"description": "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.",
"tags": ["maps", "customization", "visualization", "cartography"],
"examples": [
"Generate a map of my upcoming road trip with all planned stops highlighted.",
"Show me a map visualizing all coffee shops within a 1-mile radius of my current location."
],
"inputModes": ["application/json"],
"outputModes": [
"image/png",
"image/jpeg",
"application/json",
"text/html"
]
}
],
"supportsExtendedAgentCard": true,
"signatures": [
{
"protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0",
"signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ"
}
]
"iconUrl": "https://georoute-agent.example.com/icon.png",
"version": "1.2.0",
"documentationUrl": "https://docs.examplegeoservices.com/georoute-agent/api",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"stateTransitionHistory": false
},
"securitySchemes": {
"google": {
"type": "openIdConnect",
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
},
"security": [{ "google": ["openid", "profile", "email"] }],
"defaultInputModes": ["application/json", "text/plain"],
"defaultOutputModes": ["application/json", "image/png"],
"skills": [
{
"id": "route-optimizer-traffic",
"name": "Traffic-Aware Route Optimizer",
"description": "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).",
"tags": ["maps", "routing", "navigation", "directions", "traffic"],
"examples": [
"Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.",
"{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}"
],
"inputModes": ["application/json", "text/plain"],
"outputModes": [
"application/json",
"application/vnd.geo+json",
"text/html"
]
},
{
"id": "custom-map-generator",
"name": "Personalized Map Generator",
"description": "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.",
"tags": ["maps", "customization", "visualization", "cartography"],
"examples": [
"Generate a map of my upcoming road trip with all planned stops highlighted.",
"Show me a map visualizing all coffee shops within a 1-mile radius of my current location."
],
"inputModes": ["application/json"],
"outputModes": [
"image/png",
"image/jpeg",
"application/json",
"text/html"
]
}
],
"supportsExtendedAgentCard": true,
"signatures": [
{
"protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0",
"signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ"
}
]
}
```
@ -2192,10 +2203,12 @@ All JSON-RPC requests **MUST** follow the standard JSON-RPC 2.0 format:
```json
{
"jsonrpc": "2.0",
"id": "unique-request-id",
"method": "category/action",
"params": { /* method-specific parameters */ }
"jsonrpc": "2.0",
"id": "unique-request-id",
"method": "category/action",
"params": {
/* method-specific parameters */
}
}
```
@ -2209,10 +2222,12 @@ Sends a message to initiate or continue a task.
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": { /* SendMessageRequest object */ }
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {
/* SendMessageRequest object */
}
}
```
@ -2258,13 +2273,13 @@ Retrieves the current state of a task.
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "GetTask",
"params": {
"id": "task-uuid",
"historyLength": 10
}
"jsonrpc": "2.0",
"id": 2,
"method": "GetTask",
"params": {
"id": "task-uuid",
"historyLength": 10
}
}
```
@ -2276,15 +2291,15 @@ Lists tasks with optional filtering and pagination.
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "ListTasks",
"params": {
"contextId": "context-uuid",
"status": "working",
"pageSize": 50,
"pageToken": "cursor-token"
}
"jsonrpc": "2.0",
"id": 3,
"method": "ListTasks",
"params": {
"contextId": "context-uuid",
"status": "working",
"pageSize": 50,
"pageToken": "cursor-token"
}
}
```
@ -2296,12 +2311,12 @@ Cancels an ongoing task.
```json
{
"jsonrpc": "2.0",
"id": 4,
"method": "CancelTask",
"params": {
"id": "task-uuid"
}
"jsonrpc": "2.0",
"id": 4,
"method": "CancelTask",
"params": {
"id": "task-uuid"
}
}
```
@ -2315,12 +2330,12 @@ Subscribes to a task stream for receiving updates on a task that is not in a ter
```json
{
"jsonrpc": "2.0",
"id": 5,
"method": "SubscribeToTask",
"params": {
"id": "task-uuid"
}
"jsonrpc": "2.0",
"id": 5,
"method": "SubscribeToTask",
"params": {
"id": "task-uuid"
}
}
```
@ -2343,9 +2358,9 @@ Retrieves an extended Agent Card.
```json
{
"jsonrpc": "2.0",
"id": 6,
"method": "GetExtendedAgentCard"
"jsonrpc": "2.0",
"id": 6,
"method": "GetExtendedAgentCard"
}
```
@ -2375,15 +2390,15 @@ A2A-specific errors use codes in the range `-32001` to `-32099`. For the complet
```json
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Method not found",
"data": {
"method": "invalid/method"
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Method not found",
"data": {
"method": "invalid/method"
}
}
}
}
```
@ -2391,16 +2406,16 @@ A2A-specific errors use codes in the range `-32001` to `-32099`. For the complet
```json
{
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32001,
"message": "Task not found",
"data": {
"taskId": "nonexistent-task-id",
"timestamp": "2025-11-09T10:30:00.000Z"
"jsonrpc": "2.0",
"id": 2,
"error": {
"code": -32001,
"message": "Task not found",
"data": {
"taskId": "nonexistent-task-id",
"timestamp": "2025-11-09T10:30:00.000Z"
}
}
}
}
```
@ -2985,12 +3000,12 @@ Custom bindings **MUST** be declared in the Agent Card:
```json
{
"supportedInterfaces": [
{
"url": "wss://agent.example.com/a2a/websocket",
"protocolBinding": "WEBSOCKET"
}
]
"supportedInterfaces": [
{
"url": "wss://agent.example.com/a2a/websocket",
"protocolBinding": "WEBSOCKET"
}
]
}
```
@ -3289,190 +3304,12 @@ https://agent.example.com/.well-known/agent-card.json
---
## Appendix A. Migration & Legacy Compatibility
This appendix catalogs renamed protocol messages and objects, their legacy identifiers, and the planned deprecation/removal schedule. All legacy names and anchors MUST remain resolvable until the stated earliest removal version.
| Legacy Name | Current Name | Earliest Removal Version | Notes |
| ----------------------------------------------- | ----------------------------------------- | ------------------------ | ------------------------------------------------------ |
| `MessageSendParams` | `SendMessageRequest` | >= 0.5.0 | Request payload rename for clarity (request vs params) |
| `SendMessageSuccessResponse` | `SendMessageResponse` | >= 0.5.0 | Unified success response naming |
| `SendStreamingMessageSuccessResponse` | `StreamResponse` | >= 0.5.0 | Shorter, binding-agnostic streaming response |
| `SetTaskPushNotificationConfigRequest` | `CreateTaskPushNotificationConfigRequest` | >= 0.5.0 | Explicit creation intent |
| `ListTaskPushNotificationConfigSuccessResponse` | `ListTaskPushNotificationConfigResponse` | >= 0.5.0 | Consistent response suffix removal |
| `GetAuthenticatedExtendedCardRequest` | `GetExtendedAgentCardRequest` | >= 0.5.0 | Removed "Authenticated" from naming |
Planned Lifecycle (example timeline; adjust per release strategy):
1. 0.3.x: New names introduced; legacy names documented; aliases added.
2. 0.4.x: Legacy names marked "deprecated" in SDKs and schemas; warning notes added.
3. ≥0.5.0: Legacy names eligible for removal after review; migration appendix updated.
### A.1 Legacy Documentation Anchors
Hidden anchor spans preserve old inbound links:
<!-- Legacy inbound link compatibility anchors (old spec numbering & names) -->
<span id="32-supported-transport-protocols"></span>
<span id="324-transport-extensions"></span>
<span id="35-method-mapping-and-naming-conventions"></span>
<span id="5-agent-discovery-the-agent-card"></span>
<span id="53-recommended-location"></span>
<span id="55-agentcard-object-structure"></span>
<span id="56-transport-declaration-and-url-relationships"></span>
<span id="563-client-transport-selection-rules"></span>
<span id="57-sample-agent-card"></span>
<span id="6-protocol-data-objects"></span>
<span id="61-task-object"></span>
<span id="610-taskpushnotificationconfig-object"></span>
<span id="611-json-rpc-structures"></span>
<span id="612-jsonrpcerror-object"></span>
<span id="63-taskstate-enum"></span>
<span id="69-pushnotificationauthenticationinfo-object"></span>
<span id="711-messagesendparams-object"></span>
<span id="72-messagestream"></span>
<span id="721-sendstreamingmessageresponse-object"></span>
<span id="731-taskqueryparams-object"></span>
<span id="741-listtasksparams-object"></span>
<span id="742-listtasksresult-object"></span>
<span id="751-taskidparams-object-for-taskscancel-and-taskspushnotificationconfigget"></span>
<span id="77-taskspushnotificationconfigget"></span>
<span id="771-gettaskpushnotificationconfigparams-object-taskspushnotificationconfigget"></span>
<span id="781-listtaskpushnotificationconfigparams-object-taskspushnotificationconfiglist"></span>
<span id="791-deletetaskpushnotificationconfigparams-object-taskspushnotificationconfigdelete"></span>
<span id="8-error-handling"></span>
<span id="82-a2a-specific-errors"></span>
<!-- Legacy renamed message/object name anchors -->
<span id="messagesendparams"></span>
<span id="sendmessagesuccessresponse"></span>
<span id="sendstreamingmessagesuccessresponse"></span>
<span id="settaskpushnotificationconfigrequest"></span>
<span id="listtaskpushnotificationconfigsuccessresponse"></span>
<span id="getauthenticatedextendedcardrequest"></span>
<span id="938-agentgetauthenticatedextendedcard"></span>
Each legacy span SHOULD be placed adjacent to the current object's heading (to be inserted during detailed object section edits). If an exact numeric-prefixed anchor existed (e.g., `#414-message`), add an additional span matching that historical form if known.
### A.2 Migration Guidance
Client Implementations SHOULD:
- Prefer new names immediately for all new integrations.
- Implement dual-handling where schemas/types permit (e.g., union type or backward-compatible decoder).
- Log a warning when receiving legacy-named objects after the first deprecation announcement release.
Server Implementations MAY:
- Accept both legacy and current request message forms during the overlap period.
- Emit only current form in responses (recommended) while providing explicit upgrade notes.
#### A.2.1 Breaking Change: Kind Discriminator Removed
**Version 1.0 introduces a breaking change** in how polymorphic objects are represented in the protocol. This affects `Part` types and streaming event types.
**Legacy Pattern (v0.3.x):**
Objects used an inline `kind` field as a discriminator to identify the object type:
**Example 1 - TextPart:**
```json
{
"kind": "TextPart",
"text": "Hello, world!"
}
```
**Example 2 - FilePart:**
```json
{
"kind": "FilePart",
"mimeType": "image/png",
"name": "diagram.png",
"fileWithBytes": "iVBORw0KGgo..."
}
```
**Current Pattern (v1.0):**
Objects now use the **JSON member name** itself to identify the type. The member name acts as the discriminator, and the value structure depends on the specific type:
**Example 1 - TextPart:**
```json
{
"text": "Hello, world!"
}
```
**Example 2 - FilePart:**
```json
{
"file": {
"mediaType": "image/png",
"name": "diagram.png",
"fileWithBytes": "iVBORw0KGgo..."
}
}
```
**Affected Types:**
1. **Part Union Types**:
- **TextPart**:
- **Legacy:** `{ "kind": "TextPart", "text": "..." }`
- **Current:** `{ "text": "..." }` (direct string value)
- **FilePart**:
- **Legacy:** `{ "kind": "FilePart", "mimeType": "...", "name": "...", "fileWithBytes": "..." }`
- **Current:** `{ "file": { "mediaType": "...", "name": "...", "fileWithBytes": "..." } }`
- **DataPart**:
- **Legacy:** `{ "kind": "DataPart", "data": {...} }`
- **Current:** `{ "data": { "data": {...} } }`
2. **Streaming Event Types**:
- **TaskStatusUpdateEvent**:
- **Legacy:** `{ "kind": "TaskStatusUpdateEvent", "taskId": "...", "status": {...} }`
- **Current:** `{ "statusUpdate": { "taskId": "...", "status": {...} } }`
- **TaskArtifactUpdateEvent**:
- **Legacy:** `{ "kind": "TaskArtifactUpdateEvent", "taskId": "...", "artifact": {...} }`
- **Current:** `{ "artifactUpdate": { "taskId": "...", "artifact": {...} } }`
**Migration Strategy:**
For **Clients** upgrading from pre-0.3.x:
1. Update parsers to expect wrapper objects with member names as discriminators
2. When constructing requests, use the new wrapper format
3. Implement version detection based on the agent's `protocolVersion` in the `AgentCard`
4. Consider maintaining backward compatibility by detecting and handling both formats during a transition period
For **Servers** upgrading from pre-0.3.x:
1. Update serialization logic to emit wrapper objects
2. **Breaking:** The `kind` field is no longer part of the protocol and should not be emitted
3. Update deserialization to expect wrapper objects with member names
4. Ensure the `AgentCard` declares the correct `protocolVersion` (1.0 or later)
**Rationale:**
This change aligns with modern API design practices and Protocol Buffers' `oneof` semantics, where the field name itself serves as the type discriminator. This approach:
- Reduces redundancy (no need for both a field name and a `kind` value)
- Aligns JSON-RPC and gRPC representations more closely
- Simplifies code generation from schema definitions
- Eliminates the need for representing inheritance structures in schema languages
- Improves type safety in strongly-typed languages
### 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`.
## Appendix B. Relationship to MCP (Model Context Protocol)
## Appendix A. Relationship to MCP (Model Context Protocol)
A2A and MCP are complementary protocols designed for different aspects of agentic systems:
- **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/):** Focuses on standardizing how AI models and agents connect to and interact with **tools, APIs, data sources, and other external resources.** It defines structured ways to describe tool capabilities (like function calling in LLMs), pass inputs, and receive structured outputs. Think of MCP as the "how-to" for an agent to *use* a specific capability or access a resource.
- **Agent2Agent Protocol (A2A):** Focuses on standardizing how independent, often opaque, **AI agents communicate and collaborate with each other as peers.** A2A provides an application-level protocol for agents to discover each other, negotiate interaction modalities, manage shared tasks, and exchange conversational context or complex results. It's about how agents *partner* or *delegate* work.
- **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/):** Focuses on standardizing how AI models and agents connect to and interact with **tools, APIs, data sources, and other external resources.** It defines structured ways to describe tool capabilities (like function calling in LLMs), pass inputs, and receive structured outputs. Think of MCP as the "how-to" for an agent to _use_ a specific capability or access a resource.
- **Agent2Agent Protocol (A2A):** Focuses on standardizing how independent, often opaque, **AI agents communicate and collaborate with each other as peers.** A2A provides an application-level protocol for agents to discover each other, negotiate interaction modalities, manage shared tasks, and exchange conversational context or complex results. It's about how agents _partner_ or _delegate_ work.
**How they work together:**
An A2A Client agent might request an A2A Server agent to perform a complex task. The Server agent, in turn, might use MCP to interact with several underlying tools, APIs, or data sources to gather information or perform actions necessary to fulfill the A2A task.

View File

@ -223,46 +223,26 @@ message TaskStatus {
// Parts can be purely textual, some sort of file (image, video, etc) or
// a structured data blob (i.e. JSON).
message Part {
oneof part {
oneof content {
// The string content of the text part.
string text = 1;
// The file content, represented as either a URI or as base64-encoded bytes.
FilePart file = 2;
// The structured data content.
DataPart data = 3;
// The base64-encoded content of a file.
bytes bytes = 2;
// A URL pointing to the file's content.
string url = 3;
// Arbitrary structured data as a JSON value (object, array, string, number, boolean, or null).
google.protobuf.Value data = 4;
}
// Optional metadata associated with this part.
google.protobuf.Struct metadata = 4;
google.protobuf.Struct metadata = 5;
// An optional name for the file (e.g., "document.pdf").
string filename = 6;
// The media type (MIME type) of the part content (e.g., "text/plain", "application/json", "image/png").
// This field is available for all part types.
string media_type = 7;
}
// --8<-- [end:Part]
// --8<-- [start:FilePart]
// FilePart represents the different ways files can be provided. If files are
// small, directly feeding the bytes is supported via file_with_bytes. If the
// file is large, the agent should read the content as appropriate directly
// from the file_with_uri source.
message FilePart {
oneof file {
// A URL pointing to the file's content.
string file_with_uri = 1;
// The base64-encoded content of the file.
bytes file_with_bytes = 2;
}
// The media type of the file (e.g., "application/pdf").
string media_type = 3;
// An optional name for the file (e.g., "document.pdf").
string name = 4;
}
// --8<-- [end:FilePart]
// --8<-- [start:DataPart]
// DataPart represents a structured blob.
message DataPart {
// A JSON object containing arbitrary data.
google.protobuf.Struct data = 1 [(google.api.field_behavior) = REQUIRED];
}
// --8<-- [end:DataPart]
// --8<-- [start:Role]
// Defines the sender of a message in A2A protocol communication.
enum Role {