feat: add poc example with A2AStarletteRouteBuilder and A2AStarletteBuilder

Signed-off-by: Shingo OKAWA <[email protected]>

Author: ognis1205

examples/apicatalog/README.md

@@ -0,0 +1,19 @@
+# API Catalog Example
+
+Example showcasing multi-agent open discovery using a single base URL and an [API Catalog](https://www.ietf.org/archive/id/draft-ietf-httpapi-api-catalog-08.html). This example defines multiple agents under the same domain and exposes their metadata via `.well-known/api-catalog.json`.
+
+The agents provided in this example are minimal and behave similarly to the one in the `helloworld` example — they simply return predefined `Message` events in response to a request. The focus of this example is not on agent logic, but on demonstrating multi-agent discovery and resolution using an [API Catalog](https://www.ietf.org/archive/id/draft-ietf-httpapi-api-catalog-08.html).
+
+## Getting started
+
+1. Start the server
+
+   ```bash
+   uv run .
+   ```
+
+2. Run the test client
+
+   ```bash
+   uv run test_client.py
+   ```

examples/apicatalog/__init__.py

@@ -0,0 +1,100 @@
+import logging
+import os
+import sys
+import traceback
+
+import click
+import uvicorn
+
+from agent_executors import (
+    HelloWorldAgentExecutor, # type: ignore[import-untyped]
+    EchoAgentExecutor, # type: ignore[import-untyped]
+)
+
+from a2a.server.apps import A2AStarletteRouteBuilder, A2AStarletteBuilder
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentSkill,
+)
+from dotenv import load_dotenv
+
+
+load_dotenv()
+logging.basicConfig()
+
+
+@click.command()
+@click.option('--host', 'host', default='localhost')
+@click.option('--port', 'port', default=9999)
+def main(host: str, port: int):
+    hello_skill = AgentSkill(
+        id='hello_world',
+        name='Returns hello world',
+        description='just returns hello world',
+        tags=['hello world'],
+        examples=['hi', 'hello world'],
+    )
+    hello_card = AgentCard(
+        name='Hello World Agent',
+        description='Just a hello world agent',
+        url=f'http://{host}:{port}/a2a/hello',
+        version='1.0.0',
+        defaultInputModes=['text'],
+        defaultOutputModes=['text'],
+        capabilities=AgentCapabilities(streaming=True),
+        skills=[hello_skill],
+        supportsAuthenticatedExtendedCard=False,
+    )
+    hello_handler = DefaultRequestHandler(
+        agent_executor=HelloWorldAgentExecutor(),
+        task_store=InMemoryTaskStore(),
+    )
+    hello_agent = A2AStarletteRouteBuilder(
+        agent_card=hello_card,
+        http_handler=hello_handler,
+    )
+
+    echo_skill = AgentSkill(
+        id="echo",
+        name="Echo input",
+        description="Returns the input text as is",
+        tags=["echo"],
+        examples=["Hello!", "Repeat after me"],
+    )
+    echo_card = AgentCard(
+        name="Echo Agent",
+        description="An agent that echoes back your input.",
+        url=f"http://{host}:{port}/a2a/echo",
+        version="1.0.0",
+        defaultInputModes=["text"],
+        defaultOutputModes=["text"],
+        capabilities=AgentCapabilities(streaming=True),
+        skills=[echo_skill],
+        supportsAuthenticatedExtendedCard=False,
+    )
+    echo_handler = DefaultRequestHandler(
+        agent_executor=EchoAgentExecutor(),
+        task_store=InMemoryTaskStore(),
+    )
+    echo_agent = A2AStarletteRouteBuilder(
+        agent_card=echo_card,
+        http_handler=echo_handler,
+    )
+
+    server = (
+        A2AStarletteBuilder()
+            .mount(hello_agent)
+            .mount(echo_agent)
+            .build()
+    )
+    uvicorn.run(server, host=host, port=port)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as _:
+        print(traceback.format_exc(), file=sys.stderr)

examples/apicatalog/__main__.py

@@ -0,0 +1,124 @@
+from typing_extensions import override
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.utils import new_agent_text_message
+
+
+class HelloWorldAgent:
+    """A simple agent that returns a static 'Hello, world!' message."""
+
+    async def invoke(self) -> str:
+        """Invokes the agent's main logic and returns a response message.
+
+        Returns:
+            str: The fixed message 'Hello, world!'.
+        """
+        return 'Hello, world!'
+
+
+class HelloWorldAgentExecutor(AgentExecutor):
+    """AgentExecutor implementation for the HelloWorldAgent.
+
+    This executor wraps a HelloWorldAgent and, when executed, sends
+    a single text message event with the message "Hello World".
+
+    Intended for demonstration, testing, or HelloWorld scaffolding purposes.
+    """
+
+    def __init__(self):
+        """Initializes the executor with a HelloWorldAgent instance."""
+        self.agent = HelloWorldAgent()
+
+    @override
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Executes the agent by invoking it and emitting the result as a text message event.
+
+        Args:
+            context: The request context provided by the framework.
+            event_queue: The event queue to which agent messages should be enqueued.
+        """
+        result = await self.agent.invoke()
+        event_queue.enqueue_event(new_agent_text_message(result))
+
+    @override
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Raises an exception because cancelation is not supported for this example agent.
+
+        Args:
+            context: The request context (not used in this method).
+            event_queue: The event queue (not used in this method).
+
+        Raises:
+            Exception: Always raised, indicating cancel is not supported.
+        """
+        raise Exception('cancel not supported')
+
+
+class EchoAgent:
+    """An agent that returns the input message as-is."""
+
+    async def invoke(self, message: str) -> str:
+        """Invokes the agent's main logic and returns the input message unchanged.
+
+        This method simulates an echo behavior by returning
+        the same message that was passed as input.
+
+        Args:
+            message: The input string to echo.
+
+        Returns:
+            The same string that was provided as input.
+        """
+        return message
+
+
+class EchoAgentExecutor(AgentExecutor):
+    """AgentExecutor implementation for the EchoAgent.
+
+    This executor wraps an EchoAgent and, when executed, it sends back
+    the same message it receives, simulating a basic echo response.
+
+    Intended for demonstration, testing, or HelloWorld scaffolding purposes.
+    """
+
+    def __init__(self):
+        """Initializes the executor with a EchoAgent instance."""
+        self.agent = EchoAgent()
+
+    @override
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Executes the agent by invoking it and emitting the result as a text message event.
+
+        Args:
+            context: The request context provided by the framework.
+            event_queue: The event queue to which agent messages should be enqueued.
+        """
+        message = context.get_user_input()
+        result = await self.agent.invoke(message)
+        event_queue.enqueue_event(new_agent_text_message(result))
+
+    @override
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Raises an exception because cancelation is not supported for this example agent.
+
+        Args:
+            context: The request context (not used in this method).
+            event_queue: The event queue (not used in this method).
+
+        Raises:
+            Exception: Always raised, indicating cancel is not supported.
+        """
+        raise Exception('cancel not supported')

examples/apicatalog/agent_executors.py

@@ -0,0 +1,24 @@
+[project]
+name = "apicatalog"
+version = "0.1.0"
+description = "Minimal example agent with API Catalog support, similar to HelloWorld"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "a2a-sdk",
+    "click>=8.1.8",
+    "dotenv>=0.9.9",
+    "httpx>=0.28.1",
+    "uvicorn>=0.34.2",
+    "python-dotenv>=1.1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.uv.sources]
+a2a-sdk = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

examples/apicatalog/pyproject.toml

@@ -0,0 +1,38 @@
+import asyncio
+import logging
+import os
+import sys
+import traceback
+
+import click
+import httpx
+
+from dotenv import load_dotenv
+
+
+load_dotenv()
+logging.basicConfig()
+
+
+async def fetch_api_catalog(base_url: str):
+    url = f'{base_url.rstrip("/")}/.well-known/api-catalog.json'
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url)
+        response.raise_for_status()
+        return response.json()
+
+
+@click.command()
+@click.option('--host', 'host', default='localhost')
+@click.option('--port', 'port', default=9999)
+def main(host: str, port: int):
+    base = f'http://{host}:{port}'
+    catalog = asyncio.run(fetch_api_catalog(base))
+    print(catalog)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as _:
+        print(traceback.format_exc(), file=sys.stderr)

examples/apicatalog/test_client.py

@@ -827,6 +827,7 @@ def _join_url(base: str, *paths: str) -> str:
     joined_path = posixpath.join(parsed.path.rstrip('/'), *clean_paths)
     return urlunparse(parsed._replace(path='/' + joined_path))
 
+
 def _get_path_from_url(url: str) -> str:
     """Extracts and returns the path component from a full URL.
 
@@ -839,6 +840,7 @@ def _get_path_from_url(url: str) -> str:
     path = urlparse(url).path
     return path if path else '/'
 
+
 class A2AStarletteBuilder:
     """Builder class for assembling a Starlette application with A2A protocol routes.