UAT: A2aVersionNegotiator uses version "1.0" but spec requires JSON-RPC "2.0" — version negotiation rejects valid A2A clients #2162

Open
opened 2026-04-03 04:35:36 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: fix/a2a-version-negotiator-scheme-mismatch
  • Commit Message: fix(a2a): align A2aVersionNegotiator with spec-defined A2A protocol version scheme and Agent Card declaration
  • Milestone: v3.7.0
  • Parent Epic: #933

Problem

The specification states:

"The JSON-RPC protocol version is always "2.0" (in the jsonrpc field)"
"A2A protocol version is declared in the Agent Card and sent via the A2A-Version HTTP header"

The A2aRequest and A2aResponse models correctly use jsonrpc = "2.0" as the JSON-RPC version. However, A2aVersionNegotiator operates on a completely different version scheme:

class A2aVersionNegotiator:
    CURRENT_VERSION: str = "1.0"
    SUPPORTED_VERSIONS: tuple[str, ...] = ("1.0",)

Expected behavior (per spec): The A2aVersionNegotiator should negotiate the A2A protocol version (which is separate from the JSON-RPC version). The A2A protocol version is declared in the Agent Card and sent via the A2A-Version HTTP header. The current A2A standard version is "1.0" per the external a2a-protocol.org standard — however, the negotiator's version scheme must be consistent with what is declared in the Agent Card and what external A2A clients send.

Actual behavior: The A2aVersionNegotiator rejects version "2.0" (which is the JSON-RPC version, not the A2A protocol version). This creates confusion because:

  1. The A2aRequest model uses jsonrpc = "2.0" (correct — JSON-RPC version)
  2. The A2aVersionNegotiator uses CURRENT_VERSION = "1.0" (A2A protocol version)
  3. The consolidated_misc.feature tests verify that "2.0" is rejected and "1.0" is accepted — but the tests also check context.request.a2a_version == "1.0" which references a non-existent field

The version negotiator and the model are inconsistent: the model uses jsonrpc = "2.0" but the negotiator uses "1.0". There is no clear mapping between these two version schemes, and no Agent Card implementation exists to declare the A2A protocol version.

Code locations:

  • src/cleveragents/a2a/versioning.pyA2aVersionNegotiator.CURRENT_VERSION = "1.0" and SUPPORTED_VERSIONS = ("1.0",)
  • src/cleveragents/a2a/models.pyJSONRPC_VERSION = "2.0" (correct)
  • features/consolidated_misc.feature — tests verify "1.0" is negotiated but also check a2a_version field that doesn't exist

Severity: Medium — the version negotiator is disconnected from the actual A2A protocol version scheme and there is no Agent Card to declare the version, making version negotiation non-functional in server mode.

Subtasks

  • Audit A2aVersionNegotiator in src/cleveragents/a2a/versioning.py and document the intended version scheme (JSON-RPC vs A2A protocol)
  • Clarify and enforce the separation between jsonrpc version ("2.0") and A2A protocol version ("1.0") in code and comments
  • Fix or add the a2a_version field on A2aRequest (or equivalent) so that Behave step definitions referencing context.request.a2a_version resolve correctly
  • Update consolidated_misc.feature Behave scenarios to correctly reference the A2A protocol version field and assert the right value
  • Ensure A2aVersionNegotiator.negotiate() reads the A2A-Version HTTP header (not the jsonrpc field) when determining protocol version compatibility
  • Add or update Behave scenarios to cover: valid A2A-Version: 1.0 header accepted, missing header falls back to default, unsupported version returns appropriate JSON-RPC error
  • Verify all nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e coverage_report)

Definition of Done

  • A2aVersionNegotiator clearly operates on the A2A protocol version (not the JSON-RPC version), with inline documentation distinguishing the two
  • A2aRequest exposes an a2a_version field (or equivalent) populated from the A2A-Version HTTP header, consistent with what Behave step definitions reference
  • consolidated_misc.feature Behave scenarios pass without referencing non-existent fields
  • No # type: ignore suppressions introduced
  • All nox stages pass
  • Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/a2a-version-negotiator-scheme-mismatch` - **Commit Message**: `fix(a2a): align A2aVersionNegotiator with spec-defined A2A protocol version scheme and Agent Card declaration` - **Milestone**: v3.7.0 - **Parent Epic**: #933 ## Problem The specification states: > "The JSON-RPC protocol version is always `"2.0"` (in the `jsonrpc` field)" > "A2A protocol version is declared in the Agent Card and sent via the `A2A-Version` HTTP header" The `A2aRequest` and `A2aResponse` models correctly use `jsonrpc = "2.0"` as the JSON-RPC version. However, `A2aVersionNegotiator` operates on a completely different version scheme: ```python class A2aVersionNegotiator: CURRENT_VERSION: str = "1.0" SUPPORTED_VERSIONS: tuple[str, ...] = ("1.0",) ``` **Expected behavior (per spec)**: The `A2aVersionNegotiator` should negotiate the A2A protocol version (which is separate from the JSON-RPC version). The A2A protocol version is declared in the Agent Card and sent via the `A2A-Version` HTTP header. The current A2A standard version is `"1.0"` per the external a2a-protocol.org standard — however, the negotiator's version scheme must be consistent with what is declared in the Agent Card and what external A2A clients send. **Actual behavior**: The `A2aVersionNegotiator` rejects version `"2.0"` (which is the JSON-RPC version, not the A2A protocol version). This creates confusion because: 1. The `A2aRequest` model uses `jsonrpc = "2.0"` (correct — JSON-RPC version) 2. The `A2aVersionNegotiator` uses `CURRENT_VERSION = "1.0"` (A2A protocol version) 3. The `consolidated_misc.feature` tests verify that `"2.0"` is rejected and `"1.0"` is accepted — but the tests also check `context.request.a2a_version == "1.0"` which references a non-existent field The version negotiator and the model are inconsistent: the model uses `jsonrpc = "2.0"` but the negotiator uses `"1.0"`. There is no clear mapping between these two version schemes, and no Agent Card implementation exists to declare the A2A protocol version. **Code locations**: - `src/cleveragents/a2a/versioning.py` — `A2aVersionNegotiator.CURRENT_VERSION = "1.0"` and `SUPPORTED_VERSIONS = ("1.0",)` - `src/cleveragents/a2a/models.py` — `JSONRPC_VERSION = "2.0"` (correct) - `features/consolidated_misc.feature` — tests verify `"1.0"` is negotiated but also check `a2a_version` field that doesn't exist **Severity**: Medium — the version negotiator is disconnected from the actual A2A protocol version scheme and there is no Agent Card to declare the version, making version negotiation non-functional in server mode. ## Subtasks - [ ] Audit `A2aVersionNegotiator` in `src/cleveragents/a2a/versioning.py` and document the intended version scheme (JSON-RPC vs A2A protocol) - [ ] Clarify and enforce the separation between `jsonrpc` version (`"2.0"`) and A2A protocol version (`"1.0"`) in code and comments - [ ] Fix or add the `a2a_version` field on `A2aRequest` (or equivalent) so that Behave step definitions referencing `context.request.a2a_version` resolve correctly - [ ] Update `consolidated_misc.feature` Behave scenarios to correctly reference the A2A protocol version field and assert the right value - [ ] Ensure `A2aVersionNegotiator.negotiate()` reads the `A2A-Version` HTTP header (not the `jsonrpc` field) when determining protocol version compatibility - [ ] Add or update Behave scenarios to cover: valid `A2A-Version: 1.0` header accepted, missing header falls back to default, unsupported version returns appropriate JSON-RPC error - [ ] Verify all nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e coverage_report`) ## Definition of Done - [ ] `A2aVersionNegotiator` clearly operates on the A2A protocol version (not the JSON-RPC version), with inline documentation distinguishing the two - [ ] `A2aRequest` exposes an `a2a_version` field (or equivalent) populated from the `A2A-Version` HTTP header, consistent with what Behave step definitions reference - [ ] `consolidated_misc.feature` Behave scenarios pass without referencing non-existent fields - [ ] No `# type: ignore` suppressions introduced - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.7.0 milestone 2026-04-03 04:35:41 +00:00
freemo self-assigned this 2026-04-03 16:57:59 +00:00
Author
Owner

MoSCoW classification: Should Have

Rationale: This issue addresses an important spec requirement or quality improvement. The project should include this fix but it is not strictly essential for the milestone.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

MoSCoW classification: **Should Have** Rationale: This issue addresses an important spec requirement or quality improvement. The project should include this fix but it is not strictly essential for the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Starting implementation on branch fix/a2a-version-negotiator-scheme-mismatch.

Issue Summary: Fix A2A version negotiator scheme mismatch — align A2aVersionNegotiator with spec-defined A2A protocol version scheme, add a2a_version field to A2aRequest, and update Behave scenarios.

Wave Plan:

  • Wave 1 (parallel): Subtasks 1 & 2 — Audit versioning.py and clarify JSON-RPC vs A2A protocol version separation
  • Wave 2 (parallel): Subtasks 3 & 5 — Add a2a_version field to A2aRequest + fix negotiate() to read A2A-Version HTTP header
  • Wave 3 (parallel): Subtasks 4 & 6 — Update feature file + add new Behave scenarios
  • Wave 4 (sequential): Subtask 7 — Verify all nox stages pass

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/a2a-version-negotiator-scheme-mismatch`. **Issue Summary**: Fix A2A version negotiator scheme mismatch — align `A2aVersionNegotiator` with spec-defined A2A protocol version scheme, add `a2a_version` field to `A2aRequest`, and update Behave scenarios. **Wave Plan**: - Wave 1 (parallel): Subtasks 1 & 2 — Audit versioning.py and clarify JSON-RPC vs A2A protocol version separation - Wave 2 (parallel): Subtasks 3 & 5 — Add `a2a_version` field to `A2aRequest` + fix `negotiate()` to read `A2A-Version` HTTP header - Wave 3 (parallel): Subtasks 4 & 6 — Update feature file + add new Behave scenarios - Wave 4 (sequential): Subtask 7 — Verify all nox stages pass --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#2162
No description provided.