fix(spec): Refactor Part object to remove the need for FilePart and DataPart by darrelmiller · Pull Request #1363 · a2aproject/A2A

darrelmiller · 2026-01-14T03:17:34Z

Removed FilePart and DataPart
Moved all content properties into a oneOf
Moved filename and meda_type into part so that they are optional properties for all content
Changed data property to be value instead of struct to support all kinds of JSON structures.

gemini-code-assist

Code Review

This pull request introduces a significant and beneficial refactoring of the Part message in the A2A protocol, simplifying the structure by flattening FilePart and DataPart. This makes the message more flexible and easier to use. The changes are well-designed, for instance by moving media_type to the top level to apply to all content types. My review includes a couple of minor suggestions to improve the clarity of comments for the new fields. The broader changes to clarify the versioning strategy in the specification document are also a welcome and necessary addition, especially given the breaking change in the Part message.

gemini-code-assist · 2026-01-14T03:19:27Z

specification/grpc/a2a.proto

-// from the file_with_uri source.
-message FilePart {
-  oneof file {
+    // The base64-encoded content of a file.


The comment for the bytes field could be more precise. While bytes fields are base64-encoded in JSON representations, they are transmitted as raw bytes in Protobuf's binary format (like in gRPC). Clarifying this distinction will help developers working with different protocol bindings.

Suggested change

// The base64-encoded content of a file.

// The byte content of a file. In JSON representations, this is base64-encoded.

gemini-code-assist · 2026-01-14T03:19:27Z

specification/grpc/a2a.proto

-  string media_type = 3;
+  // Optional metadata associated with this part.
+  google.protobuf.Struct metadata = 5;
  // An optional name for the file (e.g., "document.pdf").


The filename field is useful not just for file-based parts (bytes, url) but could also be relevant for data parts (e.g., to name a JSON structure like config.json). The current comment limits its scope to files. A more general comment would better reflect its potential use cases.

Suggested change

// An optional name for the file (e.g., "document.pdf").

// An optional name for the content, often used as a filename (e.g., "document.pdf").

darrelmiller · 2026-01-16T03:04:49Z

docs/specification.md

    ```proto { .no-copy }
    --8<-- "specification/grpc/a2a.proto:{{ region_tag }}"
    ```
+


Suggested change

darrelmiller · 2026-01-16T03:05:34Z

docs/specification.md

 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:_**


Suggested change

**_Pagination Strategy:_**

***Pagination Strategy:***

darrelmiller · 2026-01-16T03:06:03Z

docs/specification.md

 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:_**


Suggested change

**_Ordering:_**

***Ordering:***

darrelmiller · 2026-01-16T03:06:32Z

docs/specification.md

 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>


Suggested change

darrelmiller · 2026-01-16T03:07:03Z

docs/specification.md

 **Standard A2A Service Parameters:**

-| Name | Description | Example Value |
+| Name             | Description                                                                                                                                             | Example Value                                                                                 |


darrelmiller · 2026-01-16T03:08:03Z

docs/specification.md

 | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
-| `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` |


Suggested change

| `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-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` |

darrelmiller · 2026-01-16T04:53:16Z

docs/specification.md

-| `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`                                                                                         |


Suggested change

| `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-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` |

darrelmiller · 2026-01-16T04:53:28Z

docs/specification.md

 **Error Categories and Server Requirements:**

 - **Authentication Errors**: Invalid or missing credentials
+


Suggested change

darrelmiller · 2026-01-16T04:53:41Z

docs/specification.md

    - Example scenarios: Missing bearer token, expired API key, invalid OAuth token

 - **Authorization Errors**: Insufficient permissions for requested operation
+


Suggested change

darrelmiller · 2026-01-16T04:54:38Z

docs/specification.md

    - Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes

 - **Validation Errors**: Invalid input parameters or message format
+


Suggested change

darrelmiller · 2026-01-16T04:54:52Z

docs/specification.md

    - Example scenarios: Invalid task ID format, missing required message parts, unsupported content type

 - **Resource Errors**: Requested task not found or not accessible
+


Suggested change

darrelmiller · 2026-01-16T04:55:11Z

docs/specification.md

 - **`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>


Suggested change

<a id="AgentProvider"></a>

<a id="AgentProvider"></a>

darrelmiller · 2026-01-16T04:55:36Z

docs/specification.md

 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:_


Suggested change

_Example: Agent declaring extension support in AgentCard:_

*Example: Agent declaring extension support in AgentCard:*

darrelmiller · 2026-01-16T04:56:09Z

docs/specification.md

 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:_


Suggested change

_Example: HTTP client opting into extensions using headers:_

*Example: HTTP client opting into extensions using headers:*

darrelmiller · 2026-01-16T04:56:42Z

docs/specification.md

 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:_


Suggested change

_Example: A location extension using the extensions and metadata arrays:_

*Example: A location extension using the extensions and metadata arrays:*

darrelmiller · 2026-01-16T16:19:33Z

docs/specification.md

 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:_


Suggested change

_Example: An artifact with citation extension for research sources:_

*Example: An artifact with citation extension for research sources:*

darrelmiller · 2026-01-16T16:20:24Z

docs/specification.md

 **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:
+


Suggested change

darrelmiller · 2026-01-16T16:21:01Z

docs/specification.md

    - **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:
+


Suggested change

darrelmiller · 2026-01-16T16:22:43Z

docs/specification.md

 **Signature Generation Process:**

 1. **Prepare the payload:**
+


Suggested change

darrelmiller · 2026-01-16T16:23:02Z

docs/specification.md

    - Canonicalize the resulting JSON using RFC 8785 to produce the canonical payload

 2. **Create the protected header:**
+


Suggested change

darrelmiller · 2026-01-16T16:23:16Z

docs/specification.md

    - Base64url-encode the serialized header to produce the `protected` field value

 3. **Compute the signature:**
+


Suggested change

darrelmiller · 2026-01-25T15:21:17Z

Closing this PR as it has been replaced by PR #1411 that does not have all the formatting changes in it.

…art (#1411) This change simplifies the Part message design by: - Renaming oneof 'part' to 'content' for clarity - Flattening FilePart fields (file_with_uri -> url, file_with_bytes -> bytes) directly into Part - Flattening DataPart by using google.protobuf.Value instead of Struct - Moving media_type and filename to Part level (available for all content types) - Removing separate FilePart and DataPart messages Also updated migration guidance documentation to reference ancillary documents instead of requiring an in-spec appendix. Related to issue #1255 Replaces PR #1363 --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: Luca Muscariello <muscariello@ieee.org>

fix: Clarified versioning strategy

64fb144

darrelmiller requested a review from a team as a code owner January 14, 2026 03:17

darrelmiller changed the title ~~fix(spec): Clarified versioning strategy~~ fix(spec): Refactor Part object to remove the need for FilePart and DataPart Jan 14, 2026

gemini-code-assist bot reviewed Jan 14, 2026

View reviewed changes

a2aproject deleted a comment from gemini-code-assist bot Jan 14, 2026

darrelmiller marked this pull request as draft January 14, 2026 03:24

Fixes to indents.

cbaa625

darrelmiller commented Jan 16, 2026

View reviewed changes

docs/specification.md

**Signature Generation Process:**

1. **Prepare the payload:**

Copy link
Copy Markdown

Contributor Author

darrelmiller Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

darrelmiller commented Jan 16, 2026

View reviewed changes

Tehsmash mentioned this pull request Jan 21, 2026

feat(spec)!: support arrays and primitives in DataPart #1306

Closed

muscariello linked an issue Jan 22, 2026 that may be closed by this pull request

[Feat]: Move media type from FilePart to base Part to support all part types #1255

Closed

muscariello added this to the 1.0 milestone Jan 22, 2026

muscariello added this to TSC Review Jan 22, 2026

github-project-automation bot moved this to Backlog in TSC Review Jan 22, 2026

muscariello removed this from the 1.0 milestone Jan 22, 2026

darrelmiller mentioned this pull request Jan 25, 2026

fix: Simplify Part message structure by flattening FilePart and DataPart #1411

Merged

darrelmiller closed this Jan 25, 2026

github-project-automation bot moved this from Backlog to Done in TSC Review Jan 25, 2026

muscariello removed a link to an issue Jan 26, 2026

[Feat]: Move media type from FilePart to base Part to support all part types #1255

Closed

	// The base64-encoded content of a file.
	// The byte content of a file. In JSON representations, this is base64-encoded.

	// An optional name for the file (e.g., "document.pdf").
	// An optional name for the content, often used as a filename (e.g., "document.pdf").

	<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>

	\| 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-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-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` \|

		Error Categories and Server Requirements:

		- Authentication Errors: Invalid or missing credentials

		- Example scenarios: Missing bearer token, expired API key, invalid OAuth token

		- Authorization Errors: Insufficient permissions for requested operation

		- Example scenarios: Attempting to access a task created by another user, insufficient OAuth scopes

		- Validation Errors: Invalid input parameters or message format

		- Example scenarios: Invalid task ID format, missing required message parts, unsupported content type

		- Resource Errors: Requested task not found or not accessible

	_Example: Agent declaring extension support in AgentCard:_
	Example: Agent declaring extension support in AgentCard:

	_Example: HTTP client opting into extensions using headers:_
	Example: HTTP client opting into extensions using headers:

	_Example: A location extension using the extensions and metadata arrays:_
	Example: A location extension using the extensions and metadata arrays:

	_Example: An artifact with citation extension for research sources:_
	Example: An artifact with citation extension for research sources:

		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:

		- 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:

		Signature Generation Process:

		1. Prepare the payload:

		- Canonicalize the resulting JSON using RFC 8785 to produce the canonical payload

		2. Create the protected header:

		- Base64url-encode the serialized header to produce the `protected` field value

		3. Compute the signature:

Conversation

darrelmiller commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

darrelmiller commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

darrelmiller commented Jan 14, 2026 •

edited

Loading