docs(helpers): note that whole numbers in a data Part come back as floats (#1373)

# Description

Whole numbers placed in a data Part come back as floats. For example,
`4326` becomes `4326.0`. This happens because `google.protobuf.Value`
stores every number as a double. It affects every transport and is not a
spec violation, since JSON does not distinguish the two.

As agreed in #1328, this PR documents the behavior and does not change
it.

- Add a short note to the docstrings of `new_data_part` and
`get_data_parts`.
- Add one bullet to the v1.0 migration guide with the client-side
workaround.
- Add a strict xfail test that expects integers to stay integers, so CI
flags it when the behavior changes.

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- [x] Ensure the tests and linter pass (Run `bash scripts/format.sh`
from the repository root to format)
- [x] Appropriate docs were updated (if necessary)

Refs #1328 🦕

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Mateusz Iwaniuk <45974414+Iwaniukooo11@users.noreply.github.com>

Author: 3 people

docs/migrations/v1_0/README.md

@@ -99,6 +99,7 @@ Constructing messages is simplified in v1.0. The old API required wrapping conte
 **Note**:
 * When using `File (bytes)` in v1.0, data serialization (via base64 encoding) is not required because A2A now uses Protobuf, which handles it automatically.
 * In v1.0, `Part.DataPart.data` is renamed to `Part.data` and is of type `google.protobuf.Value`. Use `ParseDict` to convert a Python dict into a suitable value. See the examples below for more details.
+* `google.protobuf.Value` stores every number as a double, so whole numbers in a data Part are read back as floats on every transport (`4326` becomes `4326.0`). This is a fidelity loss, not a spec violation, since JSON does not distinguish the two. On the receiving side, narrow floats for fields you model as integers (for example with `float.is_integer()`) and leave other fields alone.
 
 **Before (v0.3):**
 ```python

src/a2a/helpers/proto_helpers.py

@@ -339,6 +339,11 @@ def new_data_part(
 ) -> Part:
     """Creates a Part with structured data (google.protobuf.Value).
 
+    Note:
+        ``google.protobuf.Value`` stores every number as a double, so whole
+        numbers lose their integer type here and are read back as floats
+        (``4326`` becomes ``4326.0``). See ``get_data_parts``.
+
     Args:
         data: JSON-serializable data to embed (dict, list, str, etc.).
         media_type: Optional MIME type of the part content (e.g., "text/plain", "application/json", "image/png").
@@ -407,6 +412,11 @@ def get_data_parts(parts: Sequence[Part]) -> list[Any]:
     Each returned element is the Python object obtained by converting
     the ``google.protobuf.Value`` back via ``MessageToDict``.
 
+    Note:
+        Whole numbers come back as floats (``4326`` becomes ``4326.0``)
+        because ``google.protobuf.Value`` stores numbers as doubles. For
+        fields you model as integers, narrow floats with ``is_integer()``.
+
     Args:
         parts: A sequence of ``Part`` objects.
 

tests/helpers/test_proto_helpers.py

@@ -471,6 +471,17 @@ def test_get_data_parts_empty() -> None:
     assert get_data_parts(parts) == []
 
 
+@pytest.mark.xfail(
+    reason='https://github.com/a2aproject/a2a-python/issues/1328',
+    strict=True,
+)
+def test_get_data_parts_keeps_whole_numbers_as_ints() -> None:
+    result = get_data_parts([new_data_part({'id': 4326, 'items': [240]})])
+    assert result == [{'id': 4326, 'items': [240]}]
+    assert isinstance(result[0]['id'], int)
+    assert isinstance(result[0]['items'][0], int)
+
+
 def test_get_raw_parts() -> None:
     parts = [
         Part(raw=b'\x89PNG'),