feat: Add middleware to the client SDK

.github/actions/spelling/allow.txt

@@ -36,10 +36,12 @@ langgraph
 lifecycles
 linting
 oauthoidc
+oidc
 opensource
 protoc
 pyi
 pyversions
+respx
 socio
 sse
 tagwords

.vscode/launch.json

@@ -12,7 +12,12 @@
         "PYTHONPATH": "${workspaceFolder}"
       },
       "cwd": "${workspaceFolder}/examples/helloworld",
-      "args": ["--host", "localhost", "--port", "9999"]
+      "args": [
+        "--host",
+        "localhost",
+        "--port",
+        "9999"
+      ]
     },
     {
       "name": "Debug Currency Agent",
@@ -25,7 +30,24 @@
         "PYTHONPATH": "${workspaceFolder}"
       },
       "cwd": "${workspaceFolder}/examples/langgraph",
-      "args": ["--host", "localhost", "--port", "10000"]
+      "args": [
+        "--host",
+        "localhost",
+        "--port",
+        "10000"
+      ]
+    },
+    {
+      "name": "Pytest All",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "args": [
+        "-v",
+        "-s"
+      ],
+      "console": "integratedTerminal",
+      "justMyCode": true
     }
   ]
-}
+}

pyproject.toml

@@ -75,6 +75,7 @@ dev = [
     "pytest-asyncio>=0.26.0",
     "pytest-cov>=6.1.1",
     "pytest-mock>=3.14.0",
+    "respx>=0.20.2",
     "ruff>=0.11.6",
     "uv-dynamic-versioning>=0.8.2",
 ]

src/a2a/client/__init__.py

@@ -1,5 +1,10 @@
 """Client-side components for interacting with an A2A agent."""
 
+from a2a.client.auth import (
+    AuthInterceptor,
+    CredentialService,
+    InMemoryContextCredentialStore,
+)
 from a2a.client.client import A2ACardResolver, A2AClient
 from a2a.client.errors import (
     A2AClientError,
@@ -8,6 +13,7 @@
 )
 from a2a.client.grpc_client import A2AGrpcClient
 from a2a.client.helpers import create_text_message_object
+from a2a.client.middleware import ClientCallContext, ClientCallInterceptor
 
 
 __all__ = [
@@ -17,5 +23,10 @@
     'A2AClientHTTPError',
     'A2AClientJSONError',
     'A2AGrpcClient',
+    'AuthInterceptor',
+    'ClientCallContext',
+    'ClientCallInterceptor',
+    'CredentialService',
+    'InMemoryContextCredentialStore',
     'create_text_message_object',
 ]

src/a2a/client/auth/__init__.py

@@ -0,0 +1,14 @@
+"""Client-side authentication components for the A2A Python SDK."""
+
+from a2a.client.auth.credentials import (
+    CredentialService,
+    InMemoryContextCredentialStore,
+)
+from a2a.client.auth.interceptor import AuthInterceptor
+
+
+__all__ = [
+    'AuthInterceptor',
+    'CredentialService',
+    'InMemoryContextCredentialStore',
+]

src/a2a/client/auth/credentials.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+
+from a2a.client.middleware import ClientCallContext
+
+
+class CredentialService(ABC):
+    """An abstract service for retrieving credentials."""
+
+    @abstractmethod
+    async def get_credentials(
+        self,
+        security_scheme_name: str,
+        context: ClientCallContext | None,
+    ) -> str | None:
+        """
+        Retrieves a credential (e.g., token) for a security scheme.
+        """
+
+
+class InMemoryContextCredentialStore(CredentialService):
+    """A simple in-memory store for session-keyed credentials.
+
+    This class uses the 'sessionId' from the ClientCallContext state to
+    store and retrieve credentials...
+    """
+
+    def __init__(self) -> None:
+        # {session_id: {scheme_name: credential}}
+        self._store: dict[str, dict[str, str]] = {}
+
+    async def get_credentials(
+        self,
+        security_scheme_name: str,
+        context: ClientCallContext | None,
+    ) -> str | None:
+        if not context or 'sessionId' not in context.state:
+            return None
+        session_id = context.state['sessionId']
+        return self._store.get(session_id, {}).get(security_scheme_name)
+
+    async def set_credential(
+        self, session_id: str, security_scheme_name: str, credential: str
+    ) -> None:
+        """Method to populate the store."""
+        if session_id not in self._store:
+            self._store[session_id] = {}
+        self._store[session_id][security_scheme_name] = credential

src/a2a/client/auth/interceptor.py

@@ -0,0 +1,83 @@
+import logging
+
+from typing import Any
+
+from a2a.client.auth.credentials import CredentialService
+from a2a.client.middleware import ClientCallContext, ClientCallInterceptor
+from a2a.types import (
+    APIKeySecurityScheme,
+    AgentCard,
+    HTTPAuthSecurityScheme,
+    In,
+    OAuth2SecurityScheme,
+    OpenIdConnectSecurityScheme,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class AuthInterceptor(ClientCallInterceptor):
+    """An interceptor that automatically adds authentication details to requests
+    based on the agent's security schemes.
+    """
+
+    def __init__(self, credential_service: CredentialService):
+        self._credential_service = credential_service
+
+    async def intercept(
+        self,
+        method_name: str,
+        request_payload: dict[str, Any],
+        http_kwargs: dict[str, Any],
+        agent_card: AgentCard | None,
+        context: ClientCallContext | None,
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        if (
+            not agent_card
+            or not agent_card.security
+            or not agent_card.securitySchemes
+        ):
+            return request_payload, http_kwargs
+
+        for requirement in agent_card.security:
+            for scheme_name in requirement:
+                credential = await self._credential_service.get_credentials(
+                    scheme_name, context
+                )
+                if credential and scheme_name in agent_card.securitySchemes:
+                    scheme_def_union = agent_card.securitySchemes[scheme_name]
+                    if not scheme_def_union:
+                        continue
+                    scheme_def = scheme_def_union.root
+
+                    headers = http_kwargs.get('headers', {})
+
+                    is_bearer_scheme = False
+                    if (
+                        isinstance(scheme_def, HTTPAuthSecurityScheme)
+                        and scheme_def.scheme.lower() == 'bearer'
+                    ) or isinstance(
+                        scheme_def,
+                        OAuth2SecurityScheme | OpenIdConnectSecurityScheme,
+                    ):
+                        is_bearer_scheme = True
+
+                    if is_bearer_scheme:
+                        headers['Authorization'] = f'Bearer {credential}'
+                        logger.debug(
+                            f"Added Bearer token for scheme '{scheme_name}' (type: {scheme_def.type})."
+                        )
+                        http_kwargs['headers'] = headers
+                        return request_payload, http_kwargs
+                    if isinstance(scheme_def, APIKeySecurityScheme):
+                        if scheme_def.in_ == In.header:
+                            headers[scheme_def.name] = credential
+                            logger.debug(
+                                f"Added API Key Header for scheme '{scheme_name}'."
+                            )
+                            http_kwargs['headers'] = headers
+                            return request_payload, http_kwargs
+                        # Note: API keys in query or cookie are not handled here.
+
+        return request_payload, http_kwargs

src/a2a/client/auth/user.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) -> bool:
+        return False
+
+    @property
+    def user_name(self) -> str:
+        return ''