Merge branch 'main' into main

Author: wadave

.github/actions/spelling/excludes.txt

@@ -1,8 +1,8 @@
 # See https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-excludes
+(?:^|/)(?i).gitignore\E$
+(?:^|/)(?i)CODE_OF_CONDUCT.md\E$
 (?:^|/)(?i)COPYRIGHT
 (?:^|/)(?i)LICEN[CS]E
-(?:^|/)(?i)CODE_OF_CONDUCT.md\E$
-(?:^|/)(?i).gitignore\E$
 (?:^|/)3rdparty/
 (?:^|/)go\.sum$
 (?:^|/)package(?:-lock|)\.json$
@@ -33,6 +33,7 @@
 \.gif$
 \.git-blame-ignore-revs$
 \.gitattributes$
+\.gitignore\E$
 \.gitkeep$
 \.graffle$
 \.gz$
@@ -62,6 +63,7 @@
 \.pyc$
 \.pylintrc$
 \.qm$
+\.ruff.toml$
 \.s$
 \.sig$
 \.so$
@@ -71,6 +73,7 @@
 \.tgz$
 \.tiff?$
 \.ttf$
+\.vscode/
 \.wav$
 \.webm$
 \.webp$
@@ -82,8 +85,7 @@
 \.zip$
 ^\.github/actions/spelling/
 ^\.github/workflows/
-\.gitignore\E$
-\.vscode/
-noxfile.py
-\.ruff.toml$
+^\Qsrc/a2a/auth/__init__.py\E$
+^\Qsrc/a2a/server/request_handlers/context.py\E$
 CHANGELOG.md
+noxfile.py

.github/actions/spelling/expect.txt

@@ -1,3 +1,4 @@
+AUser
 excinfo
 GVsb
 notif

examples/helloworld/__main__.py

@@ -5,7 +5,11 @@
 from a2a.server.apps import A2AStarletteApplication
 from a2a.server.request_handlers import DefaultRequestHandler
 from a2a.server.tasks import InMemoryTaskStore
-from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentSkill,
+)
 
 
 if __name__ == '__main__':
@@ -17,25 +21,48 @@
         examples=['hi', 'hello world'],
     )
 
-    agent_card = AgentCard(
+    extended_skill = AgentSkill(
+        id='super_hello_world',
+        name='Returns a SUPER Hello World',
+        description='A more enthusiastic greeting, only for authenticated users.',
+        tags=['hello world', 'super', 'extended'],
+        examples=['super hi', 'give me a super hello'],
+    )
+
+    # This will be the public-facing agent card
+    public_agent_card = AgentCard(
         name='Hello World Agent',
         description='Just a hello world agent',
         url='http://localhost:9999/',
         version='1.0.0',
         defaultInputModes=['text'],
         defaultOutputModes=['text'],
         capabilities=AgentCapabilities(streaming=True),
-        skills=[skill],
+        skills=[skill],  # Only the basic skill for the public card
+        supportsAuthenticatedExtendedCard=True,
+    )
+
+    # This will be the authenticated extended agent card
+    # It includes the additional 'extended_skill'
+    specific_extended_agent_card = public_agent_card.model_copy(
+        update={
+            'name': 'Hello World Agent - Extended Edition', # Different name for clarity
+            'description': 'The full-featured hello world agent for authenticated users.',
+            'version': '1.0.1', # Could even be a different version
+            # Capabilities and other fields like url, defaultInputModes, defaultOutputModes,
+            # supportsAuthenticatedExtendedCard are inherited from public_agent_card unless specified here.
+            'skills': [skill, extended_skill],  # Both skills for the extended card
+        }
     )
 
     request_handler = DefaultRequestHandler(
         agent_executor=HelloWorldAgentExecutor(),
         task_store=InMemoryTaskStore(),
     )
 
-    server = A2AStarletteApplication(
-        agent_card=agent_card, http_handler=request_handler
-    )
+    server = A2AStarletteApplication(agent_card=public_agent_card,
+                                     http_handler=request_handler,
+                                     extended_agent_card=specific_extended_agent_card)
     import uvicorn
 
     uvicorn.run(server.build(), host='0.0.0.0', port=9999)

examples/helloworld/pyproject.toml

@@ -3,7 +3,7 @@ name = "helloworld"
 version = "0.1.0"
 description = "HelloWorld agent example that only returns Messages"
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.12"
 dependencies = [
     "a2a-sdk",
     "click>=8.1.8",

examples/helloworld/test_client.py

@@ -1,19 +1,70 @@
-from a2a.client import A2AClient
+import logging  # Import the logging module
 from typing import Any
-import httpx
 from uuid import uuid4
-from a2a.types import (
-    SendMessageRequest,
-    MessageSendParams,
-    SendStreamingMessageRequest,
-)
+
+import httpx
+
+from a2a.client import A2ACardResolver, A2AClient
+from a2a.types import (AgentCard, MessageSendParams, SendMessageRequest,
+                       SendStreamingMessageRequest)
 
 
 async def main() -> None:
+    PUBLIC_AGENT_CARD_PATH = "/.well-known/agent.json"
+    EXTENDED_AGENT_CARD_PATH = "/agent/authenticatedExtendedCard"
+
+    # Configure logging to show INFO level messages
+    logging.basicConfig(level=logging.INFO)
+    logger = logging.getLogger(__name__)  # Get a logger instance
+
+    base_url = 'http://localhost:9999'
+
     async with httpx.AsyncClient() as httpx_client:
-        client = await A2AClient.get_client_from_agent_card_url(
-            httpx_client, 'http://localhost:9999'
+        # Initialize A2ACardResolver
+        resolver = A2ACardResolver(
+            httpx_client=httpx_client,
+            base_url=base_url,
+            # agent_card_path uses default, extended_agent_card_path also uses default
+        )
+
+        # Fetch Public Agent Card and Initialize Client
+        final_agent_card_to_use: AgentCard | None = None
+
+        try:
+            logger.info(f"Attempting to fetch public agent card from: {base_url}{PUBLIC_AGENT_CARD_PATH}")
+            _public_card = await resolver.get_agent_card()  # Fetches from default public path
+            logger.info("Successfully fetched public agent card:")
+            logger.info(_public_card.model_dump_json(indent=2, exclude_none=True))
+            final_agent_card_to_use = _public_card
+            logger.info("\nUsing PUBLIC agent card for client initialization (default).")
+
+            if _public_card.supportsAuthenticatedExtendedCard:
+                try:
+                    logger.info(f"\nPublic card supports authenticated extended card. Attempting to fetch from: {base_url}{EXTENDED_AGENT_CARD_PATH}")
+                    auth_headers_dict = {"Authorization": "Bearer dummy-token-for-extended-card"}
+                    _extended_card = await resolver.get_agent_card(
+                        relative_card_path=EXTENDED_AGENT_CARD_PATH,
+                        http_kwargs={"headers": auth_headers_dict}
+                    )
+                    logger.info("Successfully fetched authenticated extended agent card:")
+                    logger.info(_extended_card.model_dump_json(indent=2, exclude_none=True))
+                    final_agent_card_to_use = _extended_card # Update to use the extended card
+                    logger.info("\nUsing AUTHENTICATED EXTENDED agent card for client initialization.")
+                except Exception as e_extended:
+                    logger.warning(f"Failed to fetch extended agent card: {e_extended}. Will proceed with public card.", exc_info=True)
+            elif _public_card: # supportsAuthenticatedExtendedCard is False or None
+                logger.info("\nPublic card does not indicate support for an extended card. Using public card.")
+
+        except Exception as e:
+            logger.error(f"Critical error fetching public agent card: {e}", exc_info=True)
+            raise RuntimeError("Failed to fetch the public agent card. Cannot continue.") from e
+
+
+        client = A2AClient(
+            httpx_client=httpx_client, agent_card=final_agent_card_to_use
         )
+        logger.info("A2AClient initialized.")
+
         send_message_payload: dict[str, Any] = {
             'message': {
                 'role': 'user',
@@ -29,14 +80,19 @@ async def main() -> None:
 
         response = await client.send_message(request)
         print(response.model_dump(mode='json', exclude_none=True))
+        # The HelloWorld agent doesn't support streaming requests. Validate
+        # this throws an error.
+        try:
+            streaming_request = SendStreamingMessageRequest(
+                params=MessageSendParams(**send_message_payload)
+            )
 
-        streaming_request = SendStreamingMessageRequest(
-            params=MessageSendParams(**send_message_payload)
-        )
-
-        stream_response = client.send_message_streaming(streaming_request)
-        async for chunk in stream_response:
-            print(chunk.model_dump(mode='json', exclude_none=True))
+            stream_response = client.send_message_streaming(streaming_request)
+            print("Got an unexpected response:")
+            async for chunk in stream_response:
+                print(chunk.model_dump(mode='json', exclude_none=True))
+        except Exception:
+          pass
 
 
 if __name__ == '__main__':

examples/langgraph/pyproject.toml

@@ -3,7 +3,7 @@ name = "langgraph-example"
 version = "0.1.0"
 description = "Currency conversion agent example"
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.12"
 dependencies = [
     "a2a-sdk",
     "click>=8.1.8",

src/a2a/auth/__init__.py

@@ -0,0 +1,29 @@
+"""Authenticated user information."""
+
+from abc import ABC, abstractmethod
+
+
+class User(ABC):
+    """A representation of an authenticated user."""
+
+    @property
+    @abstractmethod
+    def is_authenticated(self) -> bool:
+        """Returns whether the current user is authenticated."""
+
+    @property
+    @abstractmethod
+    def user_name(self) -> str:
+        """Returns the user name of the current user."""
+
+
+class UnauthenticatedUser(User):
+    """A representation that no user has been authenticated in the request."""
+
+    @property
+    def is_authenticated(self):
+        return False
+
+    @property
+    def user_name(self) -> str:
+        return ''