a2aproject / a2aproject/A2A

[Feat]: Support preserving integer semantics for Part.data (user IDs as integers)

Aperta
#2,025 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Shell
Stelle
25.7k
Fork
2.6k
Merge medio
3g 6h
PR unite (30g)
16

Descrizione

### Is your feature request related to a problem? Please describe.

Hi A2A team,

First of all, thanks for the great work on A2A and the clear specification.

We have a concrete use case where we use `Part.data` to carry structured payloads that include user IDs. In our system, user IDs are **semantically and technically integers** (e.g. 64‑bit IDs), and it is important for us to preserve that integer semantics end‑to‑end.

Currently, the `Part` message defines:

```proto
message Part {
oneof content {
// The string content of the `text` part.
string text = 1;
// The `raw` byte content of a file. In JSON serialization, this is encoded as a base64 string.
bytes raw = 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 = 5;
// An optional `filename` 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;
}
```

As `google.protobuf.Value` is defined in `google/protobuf/struct.proto`, it represents numbers via a single `number_value` field of type `double` and follows JSON's numeric model (no distinction between integers and floating‑point numbers). This implies that:

- Any JSON number inside `data` is stored as a `double` internally (e.g. `123` becomes `123.0`), and
- On the client side, we cannot reliably distinguish whether a value was originally an integer or a floating‑point number, nor can we guarantee lossless representation of large integer IDs. [[stackoverflow](https://stackoverflow.com/questions/51818125/how-to-use-ints-in-a-protobuf-struct)](https://stackoverflow.com/questions/51818125/how-to-use-ints-in-a-protobuf-struct)

For our use case, some fields in `Part.data` represent user IDs that must remain integers, both for semantic clarity and for avoiding precision loss when IDs exceed the safe integer range of `double`.

We would like to request support for preserving integer semantics for such values in `Part.data`. Some possible options we can see (not mutually exclusive):

1. **Introduce an integer‑specific wrapper or encoding guideline**

Define a recommended representation for integer IDs in `data`, for example:

- A convention like `{ "user_id": { "type": "int64", "value": "1234567890123456789" } }`, or
- A small, well‑defined schema (e.g. a `UserId` message) that can be embedded or referenced to carry int64 IDs without going through `google.protobuf.Value`.

This would give clients a portable way to distinguish integers from general JSON numbers.

2. **Allow/define an alternative field for integer payloads**

For cases where `Part.data` is used to carry strongly typed, ID‑heavy payloads, consider:

- Adding an additional field in `Part` (or a new message type) that can carry int32/int64 typed payload fields alongside `data`, or
- Documenting a recommended pattern where certain integer‑typed fields are modeled as regular proto fields rather than `google.protobuf.Value`, while `data` is reserved for truly dynamic JSON.

3. **Provide explicit guidance in the spec**

Even if the proto definition itself remains based on `google.protobuf.Value`, it would be very helpful if the A2A specification explicitly addressed:

- How to represent integer IDs in `Part.data` without precision loss (e.g. using strings for large IDs), and
- How clients are expected to interpret such fields (e.g. treating specific keys as int64 encoded as strings).

This change (or clarification) would make it much safer to use `Part.data` in real‑world systems where IDs, primary keys, and similar fields are inherently integers, and avoid subtle bugs caused by JSON/`double`‑based numeric encoding.

If you think this is better suited as an extension or a best‑practice guideline rather than a core spec change, we are happy to align with that as well; the important part for us is having an **officially supported, interoperable way** to carry integer user IDs through `Part.data`.

Thanks again for your work on A2A, and we’d be glad to share more details about our use case if that would help shape the design.

### Describe the solution you'd like

We would like an officially supported way to preserve integer semantics for values carried in `Part.data`, especially for user IDs that are inherently int32/int64 rather than generic JSON numbers. Specifically, it would help to either: (1) define a recommended encoding pattern for integer IDs (for example, a `{ "type": "int64", "value": "1234567890123456789" }` wrapper or a small `UserId` schema), (2) provide an alternative, strongly typed field or message path for carrying integer-heavy payloads alongside `google.protobuf.Value`, or (3) add explicit guidance in the A2A specification on how to represent integers in `Part.data` without precision loss (for example, when to use strings for large IDs and how clients should interpret them). This would allow clients and servers to interoperate safely while retaining the guarantee that user IDs remain precise integers end to end.

### Describe alternatives you've considered

_No response_

### Additional context

_No response_

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.