Whole numbers in a data Part are returned as floats (e.g. 4326 becomes 4326.0)
Maintainers usually reply within 2 days
@carstenpiepel is already working on this.
Since Oct 19, 2026.
Assessment
This issue has not been assessed yet.
Description
Summary
When an agent sends structured data in a data Part, every whole number in that
data comes back to the client as a decimal number. For example, the integer
4326 is received as 4326.0.
This happens on the normal REST + JSON transport (the response body is JSON over
HTTPS, not gRPC). A client that expects a whole number for a field therefore
receives a decimal and may reject the message during validation.
I believe this is a side effect of how the SDK builds the JSON, not something the
A2A specification requires. I am filing it so it is written down in one place for
both maintainers and other developers who hit the same thing.
What I expected
If my agent puts the whole number 4326 into a data Part, the client should
receive 4326 (a whole number), the same value I put in.
What actually happens
The client receives 4326.0 (a decimal). This is true for every whole number
in the structured data, not just one field. In my case the same response also
turned 240 into 240.0, 500 into 500.0, and 48000000 into 48000000.0.
Why it happens (as far as I can tell)
Since the 1.0 release the SDK represents every message as a Protocol Buffers
object in memory. The data field of a Part is typed as a protobuf Struct
value:
# a2a/types/a2a_pb2.pyi
data: _struct_pb2.Value
A protobuf Struct has only one way to store a number: number_value, which is
a 64-bit floating-point number (a double). It has no separate type for whole
numbers. So the moment a whole number is placed into a Struct, it becomes a
decimal.
When the SDK produces the JSON response, it converts that protobuf object with
MessageToDict (and the streaming path yields MessageToDict per frame):
# a2a/server/routes/rest_dispatcher.py
from google.protobuf.json_format import MessageToDict, Parse
...
return A2AJSONResponse(content=MessageToDict(response)) # non-streaming
...
yield MessageToDict(response) # each SSE frame
MessageToDict faithfully copies the number out of the Struct — but by then it
is already a decimal, so the JSON shows 4326.0.
So the number is lost on the way in (when it is stored in the Struct), not
on the way out. The REST + JSON transport is not the cause; the cause is the
in-memory Struct typing that sits behind it.
Minimal reproduction
No server needed — this reproduces with the protobuf tools the SDK uses:
from google.protobuf import struct_pb2
from google.protobuf.json_format import ParseDict, MessageToDict
v = struct_pb2.Value()
ParseDict({"spatialReference": 4326, "assetEmployees": 240}, v)
print(MessageToDict(v))
# -> {'spatialReference': 4326.0, 'assetEmployees': 240.0}
The whole numbers go in and come out as decimals.
Environment
a2a-sdkversion:1.2.1(also present in1.2.2; unchanged by that patch)- Transport: REST + JSON over HTTPS, server built with
create_rest_routes/
RestDispatcher/DefaultRequestHandlerV2 - Python 3.13
Is this a specification violation?
I do not think it is, and I want to be fair about that. The A2A data Part holds
general structured JSON, and plain JSON does not separate whole numbers from
decimals — 4326 and 4326.0 are the same JSON number. So a strict reading of
the spec is satisfied.
The problem is practical, not formal: many real clients and schemas do treat
whole numbers and decimals as different types (for example, an identifier field
typed as an integer). For those clients, receiving 4326.0 where they modelled
4326 is a validation failure. This is a loss of fidelity — the value you sent
is not the value shape the receiver gets back — introduced by the move to
protobuf types, even though no rule is technically broken.
This is closely related to #884 (the removal of Pydantic models and the resulting
rough edges of the proto-only path). This is one concrete, user-visible symptom of
that.
Suggested resolution (small and spec-safe)
I am not asking you to change the wire format or break the spec. Either of these
would help:
- Document it clearly. State in the docs that whole numbers in a
dataPart
are delivered as decimals, so client authors expect it and coerce on their side.
This alone would have saved me a long investigation. - Offer an opt-in way to keep whole numbers whole. For example, a
serialization helper or flag that narrows decimals with no fractional part back
to whole numbers when producing the JSON. Opt-in, so nothing changes for anyone
who does not ask for it.
Workaround for anyone else who finds this
Until the above exists, fix it on the client: when you expect a whole number
for a field, accept a decimal whose fractional part is zero and convert it back to
a whole number (reject only genuinely fractional values). Scope this to fields
that are meant to be whole numbers — do not blanket-convert, or you will corrupt
values that are legitimately decimals (coordinates, distances, measurements).
- Dominant language
- Python
- Stars
- 2.2k
- Forks
- 540
- Avg merge
- 2d 9h
- Merged PRs (30d)
- 56
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from a2aproject/a2a-python
-
[Bug]: `A2A-Version` validation ignores minor versions and the query parameterPossibly taken @rohityan claimed this 82 days ago. Opencomponent: server status:awaiting response status:stale
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
a2aproject/a2a-python#1204 · 4 comments · 1 assignee ·
Maintainers usually reply within 2 days
-
[Bug]: REST task/request id sanitizationMay be free again A pull request for this issue was closed without being merged. Openmaintainers-only
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
a2aproject/a2a-python#805 · 1 comment ·
Maintainers usually reply within 2 days
-
[Bug]: JSON-RPC client ignores the JSON-RPC error body when the HTTP status is not 2xxPossibly taken @rohityan claimed this today. Open
a2aproject/a2a-python#1475 · 2 assignees ·
Maintainers usually reply within 2 days
-
[Feat]: validate_input_modes: match media ranges such as image/* declared in the agent cardPossibly taken @rohityan claimed this 2 days ago. Open
a2aproject/a2a-python#1468 · 2 assignees ·
Maintainers usually reply within 2 days
-
Required extensions aren't enforced, so ExtensionSupportRequiredError is never raisedPossibly taken @rohityan claimed this 2 days ago. Opencomponent: server status:awaiting response
a2aproject/a2a-python#1467 · 1 comment · 1 assignee ·
Maintainers usually reply within 2 days
All issues in a2aproject/a2a-python
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
Install the skills as a Claude Code pluginPossibly taken @ruban-24 claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 6 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
FAIRmat-NFDI/pynxtools#874 ·
-
Eval: PublicationOpendata
Difficulty 2/5 1-3 hours Newbie friendliness 66/100