chore: incorporate latest proto changes (blocking -> return_immediately) (#810)

Original spec PR: a2aproject/A2A#1507.

Required a bunch of inversions including compat conversion updates. The
gotcha here is that 0.3 SDK **already** uses blocking mode by default
(although it's not according to the spec), so this spec change is about
applying a de-facto standard.

Author: ishymko

buf.gen.yaml

@@ -2,7 +2,7 @@
 version: v2
 inputs:
   - git_repo: https://github.com/a2aproject/A2A.git
-    ref: aca981cee3e7a3f22a4df8fb8a5302406f7a1cf5
+    ref: main
     subdir: specification
 managed:
   enabled: true

src/a2a/client/base_client.py

@@ -94,8 +94,7 @@ async def send_message(
             yield client_event
 
     def _apply_client_config(self, request: SendMessageRequest) -> None:
-        if not request.configuration.blocking and self._config.polling:
-            request.configuration.blocking = not self._config.polling
+        request.configuration.return_immediately |= self._config.polling
         if (
             not request.configuration.HasField('task_push_notification_config')
             and self._config.push_notification_configs

src/a2a/compat/v0_3/conversions.py

@@ -304,9 +304,7 @@ def to_core_send_message_configuration(
 ) -> pb2_v10.SendMessageConfiguration:
     """Convert send message configuration to v1.0 core type."""
     core_config = pb2_v10.SendMessageConfiguration()
-    core_config.blocking = (
-        True  # Default to True as per A2A spec for SendMessage
-    )
+    # Result will be blocking by default (return_immediately=False)
     if compat_config.accepted_output_modes:
         core_config.accepted_output_modes.extend(
             compat_config.accepted_output_modes
@@ -320,7 +318,7 @@ def to_core_send_message_configuration(
     if compat_config.history_length is not None:
         core_config.history_length = compat_config.history_length
     if compat_config.blocking is not None:
-        core_config.blocking = compat_config.blocking
+        core_config.return_immediately = not compat_config.blocking
     return core_config
 
 
@@ -340,7 +338,7 @@ def to_compat_send_message_configuration(
         history_length=core_config.history_length
         if core_config.HasField('history_length')
         else None,
-        blocking=core_config.blocking,
+        blocking=not core_config.return_immediately,
     )
 
 
@@ -1039,8 +1037,6 @@ def to_core_send_message_request(
         core_req.configuration.CopyFrom(
             to_core_send_message_configuration(compat_req.params.configuration)
         )
-    else:
-        core_req.configuration.blocking = True  # Default for A2A
     if compat_req.params.metadata:
         ParseDict(compat_req.params.metadata, core_req.metadata)
     return core_req

src/a2a/server/request_handlers/default_request_handler.py

@@ -340,9 +340,7 @@ async def on_message_send(
         consumer = EventConsumer(queue)
         producer_task.add_done_callback(consumer.agent_task_callback)
 
-        blocking = True  # Default to blocking behavior
-        if params.configuration and params.configuration.blocking is False:
-            blocking = False
+        blocking = not params.configuration.return_immediately
 
         interrupted_or_non_blocking = False
         try:

src/a2a/types/a2a_pb2.py

@@ -46,16 +46,16 @@ ROLE_USER: Role
 ROLE_AGENT: Role
 
 class SendMessageConfiguration(_message.Message):
-    __slots__ = ("accepted_output_modes", "task_push_notification_config", "history_length", "blocking")
+    __slots__ = ("accepted_output_modes", "task_push_notification_config", "history_length", "return_immediately")
     ACCEPTED_OUTPUT_MODES_FIELD_NUMBER: _ClassVar[int]
     TASK_PUSH_NOTIFICATION_CONFIG_FIELD_NUMBER: _ClassVar[int]
     HISTORY_LENGTH_FIELD_NUMBER: _ClassVar[int]
-    BLOCKING_FIELD_NUMBER: _ClassVar[int]
+    RETURN_IMMEDIATELY_FIELD_NUMBER: _ClassVar[int]
     accepted_output_modes: _containers.RepeatedScalarFieldContainer[str]
     task_push_notification_config: TaskPushNotificationConfig
     history_length: int
-    blocking: bool
-    def __init__(self, accepted_output_modes: _Optional[_Iterable[str]] = ..., task_push_notification_config: _Optional[_Union[TaskPushNotificationConfig, _Mapping]] = ..., history_length: _Optional[int] = ..., blocking: _Optional[bool] = ...) -> None: ...
+    return_immediately: bool
+    def __init__(self, accepted_output_modes: _Optional[_Iterable[str]] = ..., task_push_notification_config: _Optional[_Union[TaskPushNotificationConfig, _Mapping]] = ..., history_length: _Optional[int] = ..., return_immediately: _Optional[bool] = ...) -> None: ...
 
 class Task(_message.Message):
     __slots__ = ("id", "context_id", "status", "artifacts", "history", "metadata")

src/a2a/types/a2a_pb2.pyi

@@ -235,7 +235,7 @@ async def test_send_message_callsite_config_overrides_non_streaming(
 
         cfg = SendMessageConfiguration(
             history_length=2,
-            blocking=False,
+            return_immediately=True,
             accepted_output_modes=['application/json'],
         )
         request = SendMessageRequest(message=sample_message, configuration=cfg)
@@ -249,7 +249,7 @@ async def test_send_message_callsite_config_overrides_non_streaming(
 
         params = mock_transport.send_message.call_args[0][0]
         assert params.configuration.history_length == 2
-        assert params.configuration.blocking is False
+        assert params.configuration.return_immediately is True
         assert params.configuration.accepted_output_modes == [
             'application/json'
         ]
@@ -278,7 +278,6 @@ async def create_stream(*args, **kwargs):
 
         cfg = SendMessageConfiguration(
             history_length=0,
-            blocking=True,
             accepted_output_modes=['text/plain'],
         )
         request = SendMessageRequest(message=sample_message, configuration=cfg)
@@ -292,5 +291,5 @@ async def create_stream(*args, **kwargs):
 
         params = mock_transport.send_message_streaming.call_args[0][0]
         assert params.configuration.history_length == 0
-        assert params.configuration.blocking is True
+        assert params.configuration.return_immediately is False
         assert params.configuration.accepted_output_modes == ['text/plain']

tests/client/test_base_client.py

@@ -427,7 +427,6 @@ def test_send_message_configuration_conversion():
     v10_expected = pb2_v10.SendMessageConfiguration(
         accepted_output_modes=['text/plain', 'application/json'],
         history_length=10,
-        blocking=True,
         task_push_notification_config=pb2_v10.TaskPushNotificationConfig(
             url='http://test',
             authentication=pb2_v10.AuthenticationInfo(scheme='Basic'),
@@ -443,7 +442,7 @@ def test_send_message_configuration_conversion():
 
 def test_send_message_configuration_conversion_minimal():
     v03_config = types_v03.MessageSendConfiguration()
-    v10_expected = pb2_v10.SendMessageConfiguration(blocking=True)
+    v10_expected = pb2_v10.SendMessageConfiguration()
 
     v10_config = to_core_send_message_configuration(v03_config)
     assert v10_config == v10_expected
@@ -1306,9 +1305,7 @@ def test_send_message_request_conversion():
             role=pb2_v10.Role.ROLE_USER,
             parts=[pb2_v10.Part(text='Hi')],
         ),
-        configuration=pb2_v10.SendMessageConfiguration(
-            history_length=5, blocking=True
-        ),
+        configuration=pb2_v10.SendMessageConfiguration(history_length=5),
     )
     ParseDict({'k': 'v'}, v10_expected.metadata)
 
@@ -1767,8 +1764,8 @@ def test_to_core_send_message_request_no_configuration():
         ),
     )
     core_req = to_core_send_message_request(v03_req)
-    # Default is True if configuration is absent
-    assert core_req.configuration.blocking is True
+    # Blocking by default (return_immediately=False)
+    assert core_req.configuration.return_immediately is False
     assert not core_req.HasField('message')
 
 

tests/compat/v0_3/test_conversions.py

@@ -68,7 +68,7 @@ async def test_send_message_success_task(
             message_id='msg-1', role=a2a_pb2.Role.ROLE_USER
         ),
         configuration=a2a_pb2.SendMessageConfiguration(
-            history_length=0, blocking=False
+            history_length=0, return_immediately=True
         ),
     )
     mock_request_handler.on_message_send.assert_called_once_with(
@@ -105,7 +105,7 @@ async def test_send_message_success_message(
             message_id='msg-1', role=a2a_pb2.Role.ROLE_USER
         ),
         configuration=a2a_pb2.SendMessageConfiguration(
-            history_length=0, blocking=False
+            history_length=0, return_immediately=True
         ),
     )
     mock_request_handler.on_message_send.assert_called_once_with(
@@ -158,7 +158,7 @@ async def mock_stream(*args, **kwargs):
             message_id='msg-1', role=a2a_pb2.Role.ROLE_USER
         ),
         configuration=a2a_pb2.SendMessageConfiguration(
-            history_length=0, blocking=False
+            history_length=0, return_immediately=True
         ),
     )
     mock_request_handler.on_message_send_stream.assert_called_once_with(

tests/compat/v0_3/test_grpc_handler.py

@@ -184,7 +184,7 @@ async def test_notification_triggering_after_config_change_e2e(
                     parts=[Part(text='How are you?')],
                     role=Role.ROLE_USER,
                 ),
-                configuration=SendMessageConfiguration(blocking=True),
+                configuration=SendMessageConfiguration(),
             )
         )
     ]
@@ -225,7 +225,7 @@ async def test_notification_triggering_after_config_change_e2e(
                     parts=[Part(text='Good')],
                     role=Role.ROLE_USER,
                 ),
-                configuration=SendMessageConfiguration(blocking=True),
+                configuration=SendMessageConfiguration(),
             )
         )
     ]