Skip to content

fix(client): resolve v0.3 agent cards that list several OAuth flows - #1479

Open
0z5a wants to merge 1 commit into
a2aproject:mainfrom
0z5a:fix/legacy-oauth-several-flows
Open

0z5a wants to merge 1 commit into
a2aproject:mainfrom
0z5a:fix/legacy-oauth-several-flows

Conversation

@0z5a

@0z5a 0z5a commented Nov 16, 2026

Copy link
Copy Markdown

Description

parse_agent_card maps legacy v0.3 security schemes to their 1.0 form, but it copies an oauth2 scheme's flows object across unchanged. In the v0.3 JSON schema every flow is an independent optional property of OAuthFlows (specification/json/a2a.json at v0.3.0; this SDK's a2a.compat.v0_3.types.OAuthFlows and the a2a-sdk 0.3.x models have the same shape), so a v0.3 card may list, for example, authorizationCode and clientCredentials together. The v0.3 proto declares a oneof, but cards are discovered as JSON. In 1.0 OAuthFlows is a oneof, so ParseDict raises and A2ACardResolver.get_agent_card() / ClientFactory.create_from_url() fail with AgentCardResolutionError:

Failed to validate agent card structure from http://127.0.0.1:<port>/.well-known/agent-card.json: Failed to parse securitySchemes field: Failed to parse flows field: Message type "lf.a2a.v1.OAuthFlows" should not have multiple "flow" oneof fields ...

To reproduce, I ran an agent on a2a-sdk==0.3.26 that builds its card with that release's own OAuthFlows(authorization_code=..., client_credentials=...) and serves it with A2AStarletteApplication, then pointed ClientFactory(ClientConfig()).create_from_url() from main at it (macOS arm64, 127.0.0.1):

card served by the 0.3.26 agent main this change
clientCredentials only resolves, flow client_credentials resolves, flow client_credentials
authorizationCode + clientCredentials AgentCardResolutionError resolves, flow client_credentials

So a 1.0 client cannot connect to a 0.3 agent that describes its OAuth server with more than one flow.

This change keeps a single flow when a legacy oauth2 scheme lists several, and logs a warning naming the flows. It keeps the same flow as the v0.3 compat conversion: to_core_oauth_flows sets the flows in order on the oneof, so the last one present wins, and both paths give the same result for the same card. Only the legacy branch (type: oauth2) is touched. A 1.0 card whose oauth2SecurityScheme.flows sets two flows is still rejected.

Tests: added test_parse_030_agent_card_oauth2_with_several_flows, which fails on main with the ParseError above and passes with the fix. It also checks that the 1.0 form with two flows still raises. tests/client and tests/compat: 637 passed. Full suite: 2623 passed, 215 skipped, 4 xfailed, 1 xpassed. ruff check: all checks passed; ruff format --check: 285 files already formatted; ty check reports the same 3 diagnostics as on main, none in the changed files.

This change was drafted with Claude Code (claude-opus-5-5); the test results above are from the runs described.

In v0.3 every OAuth flow is an optional field, so a card may list
several. In 1.0 OAuthFlows is a oneof, and parse_agent_card copied the
legacy flows object across unchanged, so ParseDict rejected such cards
and the client could not be created.

Keep one flow for a legacy oauth2 scheme, the same one the v0.3 compat
conversion keeps, and log a warning naming the flows.
@0z5a
0z5a requested a review from a team as a code owner November 16, 2026 13:18
@github-actions

Copy link
Copy Markdown

🧪 Code Coverage (vs main)

⬇️ Download Full Report

Base PR Delta
src/a2a/client/card_resolver.py 100.00% 98.36% 🔴 -1.64%
src/a2a/server/cluster/database_event_stream.py 93.64% 97.27% 🟢 +3.64%
Total 93.67% 93.70% 🟢 +0.03%

Generated by coverage-comment.yml

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant