Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

[Bug]: `A2A-Version` sent as a request parameter is ignored (spec §3.6.1), so a v1.0 request is treated as 0.3

Fechada
  • Algo errado?
#1,344 0 comentários 0 reações 2 responsáveis Ver no GitHub

Mantenedores costumam responder em até 2 dias

@Iwaniukooo11 já está trabalhando nisso.

Desde 19/10/2026.

Avaliação

Esta issue ainda não foi avaliada.

Descrição

What happened?

Summary

The server only reads A2A-Version from the request header. A client that sends the version as a request parameter, which the specification allows, is treated as a 0.3 client and gets VersionNotSupportedError for a valid v1.0 request.

Section 3.6.1 ("Client Responsibilities") of the v1.0.0 specification says: "Clients MAY provide the A2A-Version as a request parameter instead of a header." Its example is GET /tasks/task-123?A2A-Version=1.0. Section 3.6.2 then requires the agent to process the request using the semantics of the requested version.

DefaultServerCallContextBuilder.build() copies only request.headers into state['headers'] (src/a2a/server/routes/common.py:115), and validate_version reads only that dict (src/a2a/utils/version_validator.py:68). The query string is never consulted, so the request falls through to the empty-header default of 0.3.

Reproduce

pip install "a2a-sdk[http-server]==1.2.2" httpx, then run:

import asyncio

import httpx
from starlette.applications import Starlette

from a2a.server.agent_execution import AgentExecutor
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.routes import create_jsonrpc_routes, create_rest_routes
from a2a.server.tasks import InMemoryTaskStore
from a2a.types import AgentCapabilities, AgentCard, AgentInterface


class Noop(AgentExecutor):
    async def execute(self, context, event_queue): ...
    async def cancel(self, context, event_queue): ...


card = AgentCard(
    name="probe", description="probe", version="0.0.1",
    capabilities=AgentCapabilities(),
    supported_interfaces=[AgentInterface(
        url="http://test/rpc", protocol_binding="JSONRPC", protocol_version="1.0")],
)
handler = DefaultRequestHandler(
    agent_executor=Noop(), task_store=InMemoryTaskStore(), agent_card=card)
app = Starlette(routes=[*create_jsonrpc_routes(handler, "/rpc"),
                        *create_rest_routes(handler)])

RPC = {"jsonrpc": "2.0", "id": 1, "method": "GetTask", "params": {"id": "task-123"}}
HDR = {"A2A-Version": "1.0"}


async def main():
    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app),
                                 base_url="http://test") as c:
        for label, resp in [
            ("JSON-RPC  header      ", await c.post("/rpc", json=RPC, headers=HDR)),
            ("JSON-RPC  ?A2A-Version", await c.post("/rpc?A2A-Version=1.0", json=RPC)),
            ("HTTP+JSON header      ", await c.get("/tasks/task-123", headers=HDR)),
            ("HTTP+JSON ?A2A-Version", await c.get("/tasks/task-123?A2A-Version=1.0")),
        ]:
            body = resp.json()
            err = body.get("error", body)
            print(f"{label} -> HTTP {resp.status_code}  {err.get('code')}  {err.get('message')}")


asyncio.run(main())

Actual (identical on main at e86695c, and with enable_v0_3_compat=True):

JSON-RPC  header       -> HTTP 200  -32001  Task not found
JSON-RPC  ?A2A-Version -> HTTP 200  -32009  A2A version '0.3' is not supported by this handler. Expected version '1.0'.
HTTP+JSON header       -> HTTP 404  404  Task not found
HTTP+JSON ?A2A-Version -> HTTP 400  400  A2A version '0.3' is not supported by this handler. Expected version '1.0'.

Expected: the two ?A2A-Version=1.0 requests behave like the header requests and return Task not found.

On JSON-RPC the failure is quiet: an HTTP 200 carrying -32009. A client that checks the status code and then reads an SSE stream sees an empty stream, which looks like an agent with nothing to say.

Suggested fix

When the header is absent, fall back to the A2A-Version request parameter in DefaultServerCallContextBuilder.build(). That way every transport and validate_version see the same value. The spec does not say which wins when both are present; letting the header win seems the least surprising.

A smaller related improvement: when the client sent no version at all, say so in the error. Today the message reads "A2A version '0.3' is not supported", which suggests the client sent 0.3. Something like "no A2A-Version header or parameter; defaulted to 0.3, which this handler does not support" would point straight at the cause.

Relevant log output
Version mismatch: actual='0.3', expected='1.0'
Code of Conduct
  • I agree to follow this project's Code of Conduct
Linguagem predominante
Python
Estrelas
2.2k
Forks
518
Merge médio
3d 12h
PRs com merge (30d)
39

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de a2aproject/a2a-python

Todas as issues de a2aproject/a2a-python

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.