Merge branch 'main' into test-coverage

Author: holtskinner

.github/actions/spelling/allow.txt

@@ -45,6 +45,7 @@ opensource
 protoc
 pyi
 pyversions
+respx
 resub
 socio
 sse

.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
     }
   ]
-}
+}

README.md

@@ -59,6 +59,8 @@ pip install a2a-sdk
    uv run test_client.py
    ```
 
+3. You can validate your agent using the agent inspector. Follow the instructions at the [a2a-inspector](https://github.com/google-a2a/a2a-inspector) repo. 
+
 You can also find more Python samples [here](https://github.com/google-a2a/a2a-samples/tree/main/samples/python) and JavaScript samples [here](https://github.com/google-a2a/a2a-samples/tree/main/samples/js).
 
 ## License

buf.gen.yaml

@@ -19,7 +19,7 @@ managed:
 plugins:
   # Generate python protobuf related code
   # Generates *_pb2.py files, one for each .proto
-  - remote: buf.build/protocolbuffers/python
+  - remote: buf.build/protocolbuffers/python:v29.3
     out: src/a2a/grpc
   # Generate python service code.
   # Generates *_pb2_grpc.py

pyproject.toml

@@ -8,19 +8,19 @@ authors = [{ name = "Google LLC", email = "[email protected]" }]
 requires-python = ">=3.10"
 keywords = ["A2A", "A2A SDK", "A2A Protocol", "Agent2Agent"]
 dependencies = [
-    "fastapi>=0.115.2",
-    "httpx>=0.28.1",
-    "httpx-sse>=0.4.0",
-    "google-api-core>=1.26.0",
-    "opentelemetry-api>=1.33.0",
-    "opentelemetry-sdk>=1.33.0",
-    "pydantic>=2.11.3",
-    "sse-starlette",
-    "starlette",
-    "grpcio>=1.60",
-    "grpcio-tools>=1.60",
-    "grpcio_reflection>=1.7.0",
-    "protobuf==6.31.1",
+  "fastapi>=0.115.2",
+  "httpx>=0.28.1",
+  "httpx-sse>=0.4.0",
+  "google-api-core>=1.26.0",
+  "opentelemetry-api>=1.33.0",
+  "opentelemetry-sdk>=1.33.0",
+  "pydantic>=2.11.3",
+  "sse-starlette",
+  "starlette",
+  "grpcio>=1.60",
+  "grpcio-tools>=1.60",
+  "grpcio_reflection>=1.7.0",
+  "protobuf==5.29.5",
 ]
 
 classifiers = [
@@ -49,8 +49,11 @@ packages = ["src/a2a"]
 testpaths = ["tests"]
 python_files = "test_*.py"
 python_functions = "test_*"
-addopts = "--cov=src --cov-config=.coveragerc --cov-report term --cov-report xml:coverage.xml --cov-branch"
+addopts = "-ra --strict-markers"
 asyncio_mode = "strict"
+markers = [
+    "asyncio: mark a test as a coroutine that should be run by pytest-asyncio",
+]
 
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning"]
@@ -60,26 +63,25 @@ build-backend = "hatchling.build"
 source = "uv-dynamic-versioning"
 
 [tool.hatch.build.targets.sdist]
-exclude = [
-  "tests/",
-]
+exclude = ["tests/"]
 
 [tool.uv-dynamic-versioning]
 vcs = "git"
 style = "pep440"
 
 [dependency-groups]
 dev = [
-    "datamodel-code-generator>=0.30.0",
-    "mypy>=1.15.0",
-    "pytest>=8.3.5",
-    "pytest-asyncio>=0.26.0",
-    "pytest-cov>=6.1.1",
-    "pytest-mock>=3.14.0",
-    "ruff>=0.11.6",
-    "uv-dynamic-versioning>=0.8.2",
-    "types-protobuf",
-    "types-requests",
+  "datamodel-code-generator>=0.30.0",
+  "mypy>=1.15.0",
+  "pytest>=8.3.5",
+  "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",
+  "types-protobuf",
+  "types-requests",
 ]
 
 [[tool.uv.index]]

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,55 @@
+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:
+        self._store: dict[str, dict[str, str]] = {}
+
+    async def get_credentials(
+        self,
+        security_scheme_name: str,
+        context: ClientCallContext | None,
+    ) -> str | None:
+        """Retrieves credentials from the in-memory store.
+
+        Args:
+            security_scheme_name: The name of the security scheme.
+            context: The client call context.
+
+        Returns:
+            The credential string, or None if not found.
+        """
+        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_credentials(
+        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,93 @@
+import logging  # noqa: I001
+from typing import Any
+
+from a2a.client.auth.credentials import CredentialService
+from a2a.client.middleware import ClientCallContext, ClientCallInterceptor
+from a2a.types import (
+    AgentCard,
+    APIKeySecurityScheme,
+    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]]:
+        """Applies authentication headers to the request if credentials are available."""
+        if (
+            agent_card is None
+            or agent_card.security is None
+            or agent_card.securitySchemes is None
+        ):
+            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.get(
+                        scheme_name
+                    )
+                    if not scheme_def_union:
+                        continue
+                    scheme_def = scheme_def_union.root
+
+                    headers = http_kwargs.get('headers', {})
+
+                    match scheme_def:
+                        # Case 1a: HTTP Bearer scheme with an if guard
+                        case HTTPAuthSecurityScheme() if (
+                            scheme_def.scheme.lower() == 'bearer'
+                        ):
+                            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
+
+                        # Case 1b: OAuth2 and OIDC schemes, which are implicitly Bearer
+                        case (
+                            OAuth2SecurityScheme()
+                            | OpenIdConnectSecurityScheme()
+                        ):
+                            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
+
+                        # Case 2: API Key in Header
+                        case APIKeySecurityScheme(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: Other cases like API keys in query/cookie are not handled and will be skipped.
+
+        return request_payload, http_kwargs