Skip to content

Commit 2ccef0d

Browse files
ShivamSharma43claudeIwaniukooo11
authored
fix(compat): serve v0.3 gRPC agent cards with a device code OAuth flow (a2aproject#1434)
# Description The v0.3 gRPC `GetAgentCard` fails for an agent card that has an OAuth2 scheme with a device code flow. v1.0 added `DeviceCodeOAuthFlow`, and v0.3 has no equivalent, so `to_compat_oauth_flows` leaves the v0.3 `OAuthFlows` with no flow set. `ToProto.oauth2_flows` raises `ValueError('Unknown oauth flow definition')` for that. `CompatGrpcHandler._handle_unary` only catches `A2AError`, so the call fails with `UNKNOWN`: ```python from a2a.compat.v0_3.conversions import to_compat_agent_card from a2a.compat.v0_3.proto_utils import ToProto from a2a.types.a2a_pb2 import ( AgentCard, AgentInterface, DeviceCodeOAuthFlow, OAuth2SecurityScheme, OAuthFlows, SecurityScheme, ) card = AgentCard( name='a', description='d', version='1', supported_interfaces=[AgentInterface( url='http://x', protocol_binding='GRPC', protocol_version='0.3')], security_schemes={'device': SecurityScheme( oauth2_security_scheme=OAuth2SecurityScheme(flows=OAuthFlows( device_code=DeviceCodeOAuthFlow( device_authorization_url='https://a/device', token_url='https://a/token'))))}, ) ToProto.agent_card(to_compat_agent_card(card)) # ValueError: Unknown oauth flow definition ``` The v0.3 JSON-RPC and REST bindings serve the same scheme as `"flows": {}`, and the public agent card does too. ## Fix - `ToProto.oauth2_flows` returns an empty `OAuthFlows` when no flow is set, instead of raising. gRPC clients then get the same scheme the JSON bindings already send. - `FromProto.oauth2_flows` returned a password flow with empty URLs for an `OAuthFlows` with no flow set, because password was its fallback branch. It now checks for `password` and returns an empty `OAuthFlows` otherwise, so the v0.3 gRPC client does not read the empty flows as a password flow. ## Tests - `test_get_agent_card_with_device_code_oauth_flow` (`test_grpc_handler.py`) serves a card with a device code scheme through `CompatGrpcHandler.GetAgentCard`. On main it fails with the `ValueError` above. With the fix the scheme comes back with empty flows. - `test_oauth_flows_conversion` asserted that `ToProto.oauth2_flows(OAuthFlows())` raises `ValueError`. It now checks that the empty flows convert to an empty proto and back. The `FromProto` half fails on main, where it returns a password flow. - `uv run pytest tests/compat/v0_3`: 324 passed - `bash scripts/lint.sh`: success. The 3 ruff diagnostics it prints are in `client_factory.py` and `transports/__init__.py`, which this change does not touch. - `uv run pytest` on Windows, Python 3.11, skipping `tests/integration/cross_version` and `tests/integration/push_notifications` because they need `os.killpg` and fork-based multiprocessing: 2549 passed, 207 skipped, 4 xfailed, 1 xpassed (with `PYTHONUTF8=1`, which `test_samples_smoke.py` needs on a cp1252 console) - [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) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Mateusz Iwaniuk <45974414+Iwaniukooo11@users.noreply.github.com>
1 parent 257626b commit 2ccef0d

6 files changed

Lines changed: 100 additions & 14 deletions

File tree

‎src/a2a/compat/v0_3/proto_utils.py‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -574,7 +574,9 @@ def oauth2_flows(cls, flows: types.OAuthFlows) -> a2a_pb2.OAuthFlows:
574574
token_url=flows.password.token_url,
575575
),
576576
)
577-
raise ValueError('Unknown oauth flow definition')
577+
# No v0.3 flow is set, e.g. for a v1.0 device code flow, which v0.3
578+
# does not have.
579+
return a2a_pb2.OAuthFlows()
578580

579581
@classmethod
580582
def skill(cls, skill: types.AgentSkill) -> a2a_pb2.AgentSkill:
@@ -1058,13 +1060,15 @@ def oauth2_flows(cls, flows: a2a_pb2.OAuthFlows) -> types.OAuthFlows:
10581060
scopes=dict(flows.implicit.scopes.items()),
10591061
),
10601062
)
1061-
return types.OAuthFlows(
1062-
password=types.PasswordOAuthFlow(
1063-
refresh_url=flows.password.refresh_url,
1064-
scopes=dict(flows.password.scopes.items()),
1065-
token_url=flows.password.token_url,
1066-
),
1067-
)
1063+
if flows.HasField('password'):
1064+
return types.OAuthFlows(
1065+
password=types.PasswordOAuthFlow(
1066+
refresh_url=flows.password.refresh_url,
1067+
scopes=dict(flows.password.scopes.items()),
1068+
token_url=flows.password.token_url,
1069+
),
1070+
)
1071+
return types.OAuthFlows()
10681072

10691073
@classmethod
10701074
def stream_response(

‎tests/compat/v0_3/test_grpc_handler.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -496,3 +496,42 @@ async def test_extract_task_and_config_id_invalid(
496496
):
497497
with pytest.raises(InvalidParamsError):
498498
handler._extract_task_and_config_id('invalid-name')
499+
500+
501+
@pytest.mark.asyncio
502+
async def test_get_agent_card_with_device_code_oauth_flow(
503+
handler: compat_grpc_handler.CompatGrpcHandler,
504+
mock_request_handler: AsyncMock,
505+
mock_grpc_context: AsyncMock,
506+
sample_agent_card: a2a_pb2.AgentCard,
507+
) -> None:
508+
"""A v1.0 device code flow, which v0.3 lacks, is sent with no flows."""
509+
sample_agent_card.security_schemes['device'].CopyFrom(
510+
a2a_pb2.SecurityScheme(
511+
oauth2_security_scheme=a2a_pb2.OAuth2SecurityScheme(
512+
description='Device code',
513+
flows=a2a_pb2.OAuthFlows(
514+
device_code=a2a_pb2.DeviceCodeOAuthFlow(
515+
device_authorization_url='https://auth.example.com/device',
516+
token_url='https://auth.example.com/token',
517+
scopes={'read': 'Read access'},
518+
)
519+
),
520+
)
521+
)
522+
)
523+
mock_request_handler.on_get_extended_agent_card.return_value = (
524+
sample_agent_card
525+
)
526+
527+
response = await handler.GetAgentCard(
528+
a2a_v0_3_pb2.GetAgentCardRequest(), mock_grpc_context
529+
)
530+
531+
mock_grpc_context.abort.assert_not_called()
532+
assert response.security_schemes['device'] == a2a_v0_3_pb2.SecurityScheme(
533+
oauth2_security_scheme=a2a_v0_3_pb2.OAuth2SecurityScheme(
534+
description='Device code',
535+
flows=a2a_v0_3_pb2.OAuthFlows(),
536+
)
537+
)

‎tests/compat/v0_3/test_proto_utils.py‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -234,9 +234,13 @@ def test_oauth_flows_conversion(self):
234234
proto_auth_code_flow = proto_utils.ToProto.oauth2_flows(auth_code_flow)
235235
assert proto_auth_code_flow.HasField('authorization_code')
236236

237-
# Test invalid flow
238-
with pytest.raises(ValueError):
239-
proto_utils.ToProto.oauth2_flows(types.OAuthFlows())
237+
# Test no flow, e.g. a v1.0 device code flow converted to v0.3
238+
proto_no_flow = proto_utils.ToProto.oauth2_flows(types.OAuthFlows())
239+
assert proto_no_flow == a2a_pb2.OAuthFlows()
240+
assert (
241+
proto_utils.FromProto.oauth2_flows(proto_no_flow)
242+
== types.OAuthFlows()
243+
)
240244

241245
# Test FromProto
242246
roundtrip_password = proto_utils.FromProto.oauth2_flows(

‎tests/integration/cross_version/client_server/client_0_3.py‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
FileWithBytes,
1616
FileWithUri,
1717
Message,
18+
OAuth2SecurityScheme,
1819
Part,
1920
Role,
2021
TaskIdParams,
@@ -224,7 +225,19 @@ async def test_get_extended_agent_card(client):
224225
print(
225226
f'card.supports_authenticated_extended_card is: {card.supports_authenticated_extended_card}'
226227
)
227-
assert card.supports_authenticated_extended_card in (False, None)
228+
assert card.supports_authenticated_extended_card is True
229+
230+
scheme = card.security_schemes['oauth'].root
231+
assert isinstance(scheme, OAuth2SecurityScheme)
232+
assert scheme.description == 'Device code'
233+
# v0.3 has no device code flow, so the server sends no flows. The
234+
# v0.3 gRPC client reads empty flows as a password flow with empty
235+
# fields.
236+
flows = scheme.flows
237+
assert flows.authorization_code is None
238+
assert flows.client_credentials is None
239+
assert flows.implicit is None
240+
assert flows.password is None or flows.password.token_url == ''
228241

229242
print(f'Success: get_extended_agent_card passed.')
230243

‎tests/integration/cross_version/client_server/client_1_0.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,9 @@ async def test_get_extended_agent_card(client):
212212

213213
if card.name == 'Server 1.0':
214214
assert len(card.supported_interfaces) == 4
215-
assert card.capabilities.extended_agent_card in (False, None)
215+
assert card.capabilities.extended_agent_card is True
216+
flows = card.security_schemes['oauth'].oauth2_security_scheme.flows
217+
assert flows.device_code.token_url == 'https://auth.example.com/token'
216218
else:
217219
assert len(card.supported_interfaces) > 0
218220
assert card.capabilities.extended_agent_card in (False, None)

‎tests/integration/cross_version/client_server/server_1_0.py‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,11 @@
2323
AgentCapabilities,
2424
AgentCard,
2525
AgentInterface,
26+
DeviceCodeOAuthFlow,
27+
OAuth2SecurityScheme,
28+
OAuthFlows,
2629
Part,
30+
SecurityScheme,
2731
TaskState,
2832
)
2933
from a2a.utils import TransportProtocol
@@ -138,7 +142,27 @@ async def main_async(http_port: int, grpc_port: int):
138142
description='Server running on a2a v1.0',
139143
version='1.0.0',
140144
skills=[],
141-
capabilities=AgentCapabilities(streaming=True, push_notifications=True),
145+
capabilities=AgentCapabilities(
146+
streaming=True,
147+
push_notifications=True,
148+
# Makes v0.3 clients fetch the extended card from the server.
149+
extended_agent_card=True,
150+
),
151+
# v0.3 has no device code flow, so v0.3 clients get no flows.
152+
security_schemes={
153+
'oauth': SecurityScheme(
154+
oauth2_security_scheme=OAuth2SecurityScheme(
155+
description='Device code',
156+
flows=OAuthFlows(
157+
device_code=DeviceCodeOAuthFlow(
158+
device_authorization_url='https://auth.example.com/device',
159+
token_url='https://auth.example.com/token',
160+
scopes={'read': 'Read access'},
161+
)
162+
),
163+
)
164+
)
165+
},
142166
default_input_modes=['text/plain'],
143167
default_output_modes=['text/plain'],
144168
supported_interfaces=[

0 commit comments

Comments
 (0)