Merge branch 'main' into manual-update-spec

Author: holtskinner

src/a2a/server/apps/jsonrpc/fastapi_app.py

@@ -16,6 +16,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 
 
@@ -89,6 +90,12 @@ def add_routes_to_app(
         )(self._handle_requests)
         app.get(agent_card_url)(self._handle_get_agent_card)
 
+        # add deprecated path only if the agent_card_url uses default well-known path
+        if agent_card_url == AGENT_CARD_WELL_KNOWN_PATH:
+            app.get(PREV_AGENT_CARD_WELL_KNOWN_PATH, include_in_schema=False)(
+                self.handle_deprecated_agent_card_path
+            )
+
         if self.agent_card.supports_authenticated_extended_card:
             app.get(extended_agent_card_url)(
                 self._handle_get_authenticated_extended_agent_card

src/a2a/server/apps/jsonrpc/jsonrpc_app.py

@@ -52,6 +52,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 from a2a.utils.errors import MethodNotImplementedError
 
@@ -436,6 +437,15 @@ async def _handle_get_agent_card(self, request: Request) -> JSONResponse:
             )
         )
 
+    async def handle_deprecated_agent_card_path(
+        self, request: Request
+    ) -> JSONResponse:
+        """Handles GET requests for the deprecated agent card endpoint."""
+        logger.warning(
+            f"Deprecated agent card endpoint '{PREV_AGENT_CARD_WELL_KNOWN_PATH}' accessed. Please use '{AGENT_CARD_WELL_KNOWN_PATH}' instead. This endpoint will be removed in a future version."
+        )
+        return await self._handle_get_agent_card(request)
+
     async def _handle_get_authenticated_extended_agent_card(
         self, request: Request
     ) -> JSONResponse:

src/a2a/server/apps/jsonrpc/starlette_app.py

@@ -15,6 +15,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 
 
@@ -86,6 +87,17 @@ def routes(
             ),
         ]
 
+        # add deprecated path only if the agent_card_url uses default well-known path
+        if agent_card_url == AGENT_CARD_WELL_KNOWN_PATH:
+            app_routes.append(
+                Route(
+                    PREV_AGENT_CARD_WELL_KNOWN_PATH,
+                    self.handle_deprecated_agent_card_path,
+                    methods=['GET'],
+                    name='agent_card_path_deprecated',
+                )
+            )
+
         if self.agent_card.supports_authenticated_extended_card:
             app_routes.append(
                 Route(

src/a2a/utils/__init__.py

@@ -9,6 +9,7 @@
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
     EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
 )
 from a2a.utils.helpers import (
     append_artifact_to_task,
@@ -34,6 +35,7 @@
     'AGENT_CARD_WELL_KNOWN_PATH',
     'DEFAULT_RPC_URL',
     'EXTENDED_AGENT_CARD_PATH',
+    'PREV_AGENT_CARD_WELL_KNOWN_PATH',
     'append_artifact_to_task',
     'are_modalities_compatible',
     'build_text_artifact',

src/a2a/utils/constants.py

@@ -1,5 +1,6 @@
 """Constants for well-known URIs used throughout the A2A Python SDK."""
 
-AGENT_CARD_WELL_KNOWN_PATH = '/.well-known/agent.json'
+AGENT_CARD_WELL_KNOWN_PATH = '/.well-known/agent-card.json'
+PREV_AGENT_CARD_WELL_KNOWN_PATH = '/.well-known/agent.json'
 EXTENDED_AGENT_CARD_PATH = '/agent/authenticatedExtendedCard'
 DEFAULT_RPC_URL = '/'

tests/client/test_client.py

@@ -48,6 +48,7 @@
     TaskPushNotificationConfig,
     TaskQueryParams,
 )
+from a2a.utils import AGENT_CARD_WELL_KNOWN_PATH
 
 
 AGENT_CARD = AgentCard(
@@ -128,7 +129,7 @@ async def async_iterable_from_list(
 
 class TestA2ACardResolver:
     BASE_URL = 'http://example.com'
-    AGENT_CARD_PATH = '/.well-known/agent.json'
+    AGENT_CARD_PATH = AGENT_CARD_WELL_KNOWN_PATH
     FULL_AGENT_CARD_URL = f'{BASE_URL}{AGENT_CARD_PATH}'
     EXTENDED_AGENT_CARD_PATH = (
         '/agent/authenticatedExtendedCard'  # Default path
@@ -154,7 +155,10 @@ async def test_init_parameters_stored_correctly(
             httpx_client=mock_httpx_client,
             base_url=base_url,
         )
-        assert resolver_default_path.agent_card_path == '.well-known/agent.json'
+        assert (
+            '/' + resolver_default_path.agent_card_path
+            == AGENT_CARD_WELL_KNOWN_PATH
+        )
 
     @pytest.mark.asyncio
     async def test_init_strips_slashes(self, mock_httpx_client: AsyncMock):

tests/server/request_handlers/test_default_request_handler.py

@@ -1,4 +1,5 @@
 import asyncio
+import logging
 import time
 
 from unittest.mock import (
@@ -50,6 +51,9 @@
     TextPart,
     UnsupportedOperationError,
 )
+from a2a.utils import (
+    new_task,
+)
 
 
 class DummyAgentExecutor(AgentExecutor):
@@ -579,6 +583,79 @@ async def test_on_message_send_task_id_mismatch():
     assert 'Task ID mismatch' in exc_info.value.error.message  # type: ignore
 
 
+class HelloAgentExecutor(AgentExecutor):
+    async def execute(self, context: RequestContext, event_queue: EventQueue):
+        task = context.current_task
+        if not task:
+            assert context.message is not None, (
+                'A message is required to create a new task'
+            )
+            task = new_task(context.message)  # type: ignore
+            await event_queue.enqueue_event(task)
+        updater = TaskUpdater(event_queue, task.id, task.context_id)
+
+        try:
+            parts = [Part(root=TextPart(text='I am working'))]
+            await updater.update_status(
+                TaskState.working,
+                message=updater.new_agent_message(parts),
+            )
+        except Exception as e:
+            # Stop processing when the event loop is closed
+            logging.warning('Error: %s', e)
+            return
+        await updater.add_artifact(
+            [Part(root=TextPart(text='Hello world!'))],
+            name='conversion_result',
+        )
+        await updater.complete()
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue):
+        pass
+
+
+@pytest.mark.asyncio
+async def test_on_message_send_non_blocking():
+    task_store = InMemoryTaskStore()
+    push_store = InMemoryPushNotificationConfigStore()
+
+    request_handler = DefaultRequestHandler(
+        agent_executor=HelloAgentExecutor(),
+        task_store=task_store,
+        push_config_store=push_store,
+    )
+    params = MessageSendParams(
+        message=Message(
+            role=Role.user,
+            message_id='msg_push',
+            parts=[Part(root=TextPart(text='Hi'))],
+        ),
+        configuration=MessageSendConfiguration(
+            blocking=False, accepted_output_modes=['text/plain']
+        ),
+    )
+
+    result = await request_handler.on_message_send(
+        params, create_server_call_context()
+    )
+
+    assert result is not None
+    assert isinstance(result, Task)
+    assert result.status.state == TaskState.submitted
+
+    # Polling for 500ms until task is completed.
+    task: Task | None = None
+    for _ in range(5):
+        await asyncio.sleep(0.1)
+        task = await task_store.get(result.id)
+        assert task is not None
+        if task.status.state == TaskState.completed:
+            break
+
+    assert task is not None
+    assert task.status.state == TaskState.completed
+
+
 @pytest.mark.asyncio
 async def test_on_message_send_interrupted_flow():
     """Test on_message_send when flow is interrupted (e.g., auth_required)."""

tests/server/test_integration.py

@@ -44,6 +44,10 @@
     TextPart,
     UnsupportedOperationError,
 )
+from a2a.utils import (
+    AGENT_CARD_WELL_KNOWN_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
+)
 from a2a.utils.errors import MethodNotImplementedError
 
 
@@ -147,7 +151,7 @@ def client(app: A2AStarletteApplication, **kwargs):
 
 def test_agent_card_endpoint(client: TestClient, agent_card: AgentCard):
     """Test the agent card endpoint returns expected data."""
-    response = client.get('/.well-known/agent.json')
+    response = client.get(AGENT_CARD_WELL_KNOWN_PATH)
     assert response.status_code == 200
     data = response.json()
     assert data['name'] == agent_card.name
@@ -169,6 +173,36 @@ def test_authenticated_extended_agent_card_endpoint_not_supported(
     assert response.status_code == 404  # Starlette's default for no route
 
 
+def test_agent_card_default_endpoint_has_deprecated_route(
+    agent_card: AgentCard, handler: mock.AsyncMock
+):
+    """Test agent card deprecated route is available for default route."""
+    app_instance = A2AStarletteApplication(agent_card, handler)
+    client = TestClient(app_instance.build())
+    response = client.get(AGENT_CARD_WELL_KNOWN_PATH)
+    assert response.status_code == 200
+    data = response.json()
+    assert data['name'] == agent_card.name
+    response = client.get(PREV_AGENT_CARD_WELL_KNOWN_PATH)
+    assert response.status_code == 200
+    data = response.json()
+    assert data['name'] == agent_card.name
+
+
+def test_agent_card_custom_endpoint_has_no_deprecated_route(
+    agent_card: AgentCard, handler: mock.AsyncMock
+):
+    """Test agent card deprecated route is not available for custom route."""
+    app_instance = A2AStarletteApplication(agent_card, handler)
+    client = TestClient(app_instance.build(agent_card_url='/my-agent'))
+    response = client.get('/my-agent')
+    assert response.status_code == 200
+    data = response.json()
+    assert data['name'] == agent_card.name
+    response = client.get(PREV_AGENT_CARD_WELL_KNOWN_PATH)
+    assert response.status_code == 404
+
+
 def test_authenticated_extended_agent_card_endpoint_not_supported_fastapi(
     agent_card: AgentCard, handler: mock.AsyncMock
 ):
@@ -253,9 +287,7 @@ def test_starlette_rpc_endpoint_custom_url(
     """Test the RPC endpoint with a custom URL."""
     # Provide a valid Task object as the return value
     task_status = TaskStatus(**MINIMAL_TASK_STATUS)
-    task = Task(
-        id='task1', context_id='ctx1', state='completed', status=task_status
-    )
+    task = Task(id='task1', context_id='ctx1', status=task_status)
     handler.on_get_task.return_value = task
     client = TestClient(app.build(rpc_url='/api/rpc'))
     response = client.post(
@@ -278,9 +310,7 @@ def test_fastapi_rpc_endpoint_custom_url(
     """Test the RPC endpoint with a custom URL."""
     # Provide a valid Task object as the return value
     task_status = TaskStatus(**MINIMAL_TASK_STATUS)
-    task = Task(
-        id='task1', context_id='ctx1', state='completed', status=task_status
-    )
+    task = Task(id='task1', context_id='ctx1', status=task_status)
     handler.on_get_task.return_value = task
     client = TestClient(app.build(rpc_url='/api/rpc'))
     response = client.post(
@@ -315,7 +345,7 @@ def custom_handler(request):
     assert response.json() == {'message': 'Hello'}
 
     # Ensure default routes still work
-    response = client.get('/.well-known/agent.json')
+    response = client.get(AGENT_CARD_WELL_KNOWN_PATH)
     assert response.status_code == 200
     data = response.json()
     assert data['name'] == agent_card.name
@@ -339,11 +369,40 @@ def custom_handler(request):
     assert response.json() == {'message': 'Hello'}
 
     # Ensure default routes still work
-    response = client.get('/.well-known/agent.json')
+    response = client.get(AGENT_CARD_WELL_KNOWN_PATH)
     assert response.status_code == 200
     data = response.json()
     assert data['name'] == agent_card.name
 
+    # check if deprecated agent card path route is available with default well-known path
+    response = client.get(PREV_AGENT_CARD_WELL_KNOWN_PATH)
+    assert response.status_code == 200
+    data = response.json()
+    assert data['name'] == agent_card.name
+
+
+def test_fastapi_build_custom_agent_card_path(
+    app: A2AFastAPIApplication, agent_card: AgentCard
+):
+    """Test building the app with a custom agent card path."""
+
+    test_app = app.build(agent_card_url='/agent-card')
+    client = TestClient(test_app)
+
+    # Ensure custom card path works
+    response = client.get('/agent-card')
+    assert response.status_code == 200
+    data = response.json()
+    assert data['name'] == agent_card.name
+
+    # Ensure default agent card location is not available
+    response = client.get(AGENT_CARD_WELL_KNOWN_PATH)
+    assert response.status_code == 404
+
+    # check if deprecated agent card path route is not available
+    response = client.get(PREV_AGENT_CARD_WELL_KNOWN_PATH)
+    assert response.status_code == 404
+
 
 # === REQUEST METHODS TESTS ===
 
@@ -395,9 +454,7 @@ def test_cancel_task(client: TestClient, handler: mock.AsyncMock):
     # Setup mock response
     task_status = TaskStatus(**MINIMAL_TASK_STATUS)
     task_status.state = TaskState.canceled  # 'cancelled' #
-    task = Task(
-        id='task1', context_id='ctx1', state='cancelled', status=task_status
-    )
+    task = Task(id='task1', context_id='ctx1', status=task_status)
     handler.on_cancel_task.return_value = task
 
     # Send request
@@ -425,9 +482,7 @@ def test_get_task(client: TestClient, handler: mock.AsyncMock):
     """Test getting a task."""
     # Setup mock response
     task_status = TaskStatus(**MINIMAL_TASK_STATUS)
-    task = Task(
-        id='task1', context_id='ctx1', state='completed', status=task_status
-    )
+    task = Task(id='task1', context_id='ctx1', status=task_status)
     handler.on_get_task.return_value = task  # JSONRPCResponse(root=task)
 
     # Send request