Merge branch 'main' into restful

Author: holtskinner

.github/actions/spelling/allow.txt

@@ -39,6 +39,7 @@ genai
 getkwargs
 gle
 GVsb
+ietf
 initdb
 inmemory
 INR

scripts/format.sh

@@ -78,7 +78,7 @@ run_formatter pyupgrade --exit-zero-even-if-changed --py310-plus
 echo "Running autoflake..."
 run_formatter autoflake -i -r --remove-all-unused-imports
 echo "Running ruff check (fix-only)..."
-run_formatter ruff check --fix-only $RUFF_UNSAFE_FIXES_FLAG
+run_formatter ruff check --fix $RUFF_UNSAFE_FIXES_FLAG
 echo "Running ruff format..."
 run_formatter ruff format
 

src/a2a/_base.py

@@ -1,7 +1,3 @@
-import warnings
-
-from typing import Any, ClassVar
-
 from pydantic import BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel
 
@@ -40,64 +36,3 @@ class A2ABaseModel(BaseModel):
         serialize_by_alias=True,
         alias_generator=to_camel_custom,
     )
-
-    # Cache for the alias -> field_name mapping.
-    # It starts as None and is populated on first access.
-    _alias_to_field_name_map: ClassVar[dict[str, str] | None] = None
-
-    @classmethod
-    def _get_alias_map(cls) -> dict[str, str]:
-        """Lazily builds and returns the alias-to-field-name mapping for the class.
-
-        The map is cached on the class object to avoid re-computation.
-        """
-        if cls._alias_to_field_name_map is None:
-            cls._alias_to_field_name_map = {
-                field.alias: field_name
-                for field_name, field in cls.model_fields.items()
-                if field.alias is not None
-            }
-        return cls._alias_to_field_name_map
-
-    def __setattr__(self, name: str, value: Any) -> None:
-        """Allow setting attributes via their camelCase alias."""
-        # Get the map and find the corresponding snake_case field name.
-        field_name = type(self)._get_alias_map().get(name)  # noqa: SLF001
-
-        if field_name and field_name != name:
-            # An alias was used, issue a warning.
-            warnings.warn(
-                (
-                    f"Setting field '{name}' via its camelCase alias is deprecated and will be removed in version 0.3.0 "
-                    f"Use the snake_case name '{field_name}' instead."
-                ),
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
-        # If an alias was used, field_name will be set; otherwise, use the original name.
-        super().__setattr__(field_name or name, value)
-
-    def __getattr__(self, name: str) -> Any:
-        """Allow getting attributes via their camelCase alias."""
-        # Get the map and find the corresponding snake_case field name.
-        field_name = type(self)._get_alias_map().get(name)  # noqa: SLF001
-
-        if field_name and field_name != name:
-            # An alias was used, issue a warning.
-            warnings.warn(
-                (
-                    f"Accessing field '{name}' via its camelCase alias is deprecated and will be removed in version 0.3.0 "
-                    f"Use the snake_case name '{field_name}' instead."
-                ),
-                DeprecationWarning,
-                stacklevel=2,
-            )
-
-            # If an alias was used, retrieve the actual snake_case attribute.
-            return getattr(self, field_name)
-
-        # If it's not a known alias, it's a genuine missing attribute.
-        raise AttributeError(
-            f"'{type(self).__name__}' object has no attribute '{name}'"
-        )

src/a2a/grpc/a2a_pb2.py

@@ -277,22 +277,24 @@ class AgentExtension(_message.Message):
     def __init__(self, uri: _Optional[str] = ..., description: _Optional[str] = ..., required: bool = ..., params: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ...) -> None: ...
 
 class AgentSkill(_message.Message):
-    __slots__ = ("id", "name", "description", "tags", "examples", "input_modes", "output_modes")
+    __slots__ = ("id", "name", "description", "tags", "examples", "input_modes", "output_modes", "security")
     ID_FIELD_NUMBER: _ClassVar[int]
     NAME_FIELD_NUMBER: _ClassVar[int]
     DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
     TAGS_FIELD_NUMBER: _ClassVar[int]
     EXAMPLES_FIELD_NUMBER: _ClassVar[int]
     INPUT_MODES_FIELD_NUMBER: _ClassVar[int]
     OUTPUT_MODES_FIELD_NUMBER: _ClassVar[int]
+    SECURITY_FIELD_NUMBER: _ClassVar[int]
     id: str
     name: str
     description: str
     tags: _containers.RepeatedScalarFieldContainer[str]
     examples: _containers.RepeatedScalarFieldContainer[str]
     input_modes: _containers.RepeatedScalarFieldContainer[str]
     output_modes: _containers.RepeatedScalarFieldContainer[str]
-    def __init__(self, id: _Optional[str] = ..., name: _Optional[str] = ..., description: _Optional[str] = ..., tags: _Optional[_Iterable[str]] = ..., examples: _Optional[_Iterable[str]] = ..., input_modes: _Optional[_Iterable[str]] = ..., output_modes: _Optional[_Iterable[str]] = ...) -> None: ...
+    security: _containers.RepeatedCompositeFieldContainer[Security]
+    def __init__(self, id: _Optional[str] = ..., name: _Optional[str] = ..., description: _Optional[str] = ..., tags: _Optional[_Iterable[str]] = ..., examples: _Optional[_Iterable[str]] = ..., input_modes: _Optional[_Iterable[str]] = ..., output_modes: _Optional[_Iterable[str]] = ..., security: _Optional[_Iterable[_Union[Security, _Mapping]]] = ...) -> None: ...
 
 class AgentCardSignature(_message.Message):
     __slots__ = ("protected", "signature", "header")
@@ -332,16 +334,18 @@ class Security(_message.Message):
     def __init__(self, schemes: _Optional[_Mapping[str, StringList]] = ...) -> None: ...
 
 class SecurityScheme(_message.Message):
-    __slots__ = ("api_key_security_scheme", "http_auth_security_scheme", "oauth2_security_scheme", "open_id_connect_security_scheme")
+    __slots__ = ("api_key_security_scheme", "http_auth_security_scheme", "oauth2_security_scheme", "open_id_connect_security_scheme", "mtls_security_scheme")
     API_KEY_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     HTTP_AUTH_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     OAUTH2_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     OPEN_ID_CONNECT_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
+    MTLS_SECURITY_SCHEME_FIELD_NUMBER: _ClassVar[int]
     api_key_security_scheme: APIKeySecurityScheme
     http_auth_security_scheme: HTTPAuthSecurityScheme
     oauth2_security_scheme: OAuth2SecurityScheme
     open_id_connect_security_scheme: OpenIdConnectSecurityScheme
-    def __init__(self, api_key_security_scheme: _Optional[_Union[APIKeySecurityScheme, _Mapping]] = ..., http_auth_security_scheme: _Optional[_Union[HTTPAuthSecurityScheme, _Mapping]] = ..., oauth2_security_scheme: _Optional[_Union[OAuth2SecurityScheme, _Mapping]] = ..., open_id_connect_security_scheme: _Optional[_Union[OpenIdConnectSecurityScheme, _Mapping]] = ...) -> None: ...
+    mtls_security_scheme: MutualTlsSecurityScheme
+    def __init__(self, api_key_security_scheme: _Optional[_Union[APIKeySecurityScheme, _Mapping]] = ..., http_auth_security_scheme: _Optional[_Union[HTTPAuthSecurityScheme, _Mapping]] = ..., oauth2_security_scheme: _Optional[_Union[OAuth2SecurityScheme, _Mapping]] = ..., open_id_connect_security_scheme: _Optional[_Union[OpenIdConnectSecurityScheme, _Mapping]] = ..., mtls_security_scheme: _Optional[_Union[MutualTlsSecurityScheme, _Mapping]] = ...) -> None: ...
 
 class APIKeySecurityScheme(_message.Message):
     __slots__ = ("description", "location", "name")
@@ -364,12 +368,14 @@ class HTTPAuthSecurityScheme(_message.Message):
     def __init__(self, description: _Optional[str] = ..., scheme: _Optional[str] = ..., bearer_format: _Optional[str] = ...) -> None: ...
 
 class OAuth2SecurityScheme(_message.Message):
-    __slots__ = ("description", "flows")
+    __slots__ = ("description", "flows", "oauth2_metadata_url")
     DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
     FLOWS_FIELD_NUMBER: _ClassVar[int]
+    OAUTH2_METADATA_URL_FIELD_NUMBER: _ClassVar[int]
     description: str
     flows: OAuthFlows
-    def __init__(self, description: _Optional[str] = ..., flows: _Optional[_Union[OAuthFlows, _Mapping]] = ...) -> None: ...
+    oauth2_metadata_url: str
+    def __init__(self, description: _Optional[str] = ..., flows: _Optional[_Union[OAuthFlows, _Mapping]] = ..., oauth2_metadata_url: _Optional[str] = ...) -> None: ...
 
 class OpenIdConnectSecurityScheme(_message.Message):
     __slots__ = ("description", "open_id_connect_url")
@@ -379,6 +385,12 @@ class OpenIdConnectSecurityScheme(_message.Message):
     open_id_connect_url: str
     def __init__(self, description: _Optional[str] = ..., open_id_connect_url: _Optional[str] = ...) -> None: ...
 
+class MutualTlsSecurityScheme(_message.Message):
+    __slots__ = ("description",)
+    DESCRIPTION_FIELD_NUMBER: _ClassVar[int]
+    description: str
+    def __init__(self, description: _Optional[str] = ...) -> None: ...
+
 class OAuthFlows(_message.Message):
     __slots__ = ("authorization_code", "client_credentials", "implicit", "password")
     AUTHORIZATION_CODE_FIELD_NUMBER: _ClassVar[int]

src/a2a/grpc/a2a_pb2.pyi

@@ -1,3 +1,4 @@
+# ruff: noqa: PLC0415
 import json
 import logging
 
@@ -94,7 +95,7 @@ def __init__(
 
         if encryption_key:
             try:
-                from cryptography.fernet import Fernet  # noqa: PLC0415
+                from cryptography.fernet import Fernet
             except ImportError as e:
                 raise ImportError(
                     "DatabasePushNotificationConfigStore with encryption requires the 'cryptography' "
@@ -166,7 +167,7 @@ def _from_orm(
         payload = model_instance.config_data
 
         if self._fernet:
-            from cryptography.fernet import InvalidToken  # noqa: PLC0415
+            from cryptography.fernet import InvalidToken
 
             try:
                 decrypted_payload = self._fernet.decrypt(payload)

src/a2a/server/tasks/database_push_notification_config_store.py

@@ -164,6 +164,15 @@ class AgentSkill(A2ABaseModel):
     """
     The set of supported output MIME types for this skill, overriding the agent's defaults.
     """
+    security: list[dict[str, list[str]]] | None = Field(
+        default=None, examples=[[{'google': ['oidc']}]]
+    )
+    """
+    Security schemes necessary for the agent to leverage this skill.
+    As in the overall AgentCard.security, this list represents a logical OR of security
+    requirement objects. Each object is a set of security schemes that must be used together
+    (a logical AND).
+    """
     tags: list[str] = Field(
         ..., examples=[['cooking', 'customer support', 'billing']]
     )
@@ -730,6 +739,21 @@ class MethodNotFoundError(A2ABaseModel):
     """
 
 
+class MutualTLSSecurityScheme(A2ABaseModel):
+    """
+    Defines a security scheme using mTLS authentication.
+    """
+
+    description: str | None = None
+    """
+    An optional description for the security scheme.
+    """
+    type: Literal['mutualTLS'] = 'mutualTLS'
+    """
+    The type of the security scheme. Must be 'mutualTLS'.
+    """
+
+
 class OpenIdConnectSecurityScheme(A2ABaseModel):
     """
     Defines a security scheme using OpenID Connect.
@@ -1486,6 +1510,11 @@ class OAuth2SecurityScheme(A2ABaseModel):
     """
     An object containing configuration information for the supported OAuth 2.0 flows.
     """
+    oauth2_metadata_url: str | None = None
+    """
+    URL to the oauth2 authorization server metadata
+    [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required.
+    """
     type: Literal['oauth2'] = 'oauth2'
     """
     The type of the security scheme. Must be 'oauth2'.
@@ -1498,13 +1527,15 @@ class SecurityScheme(
         | HTTPAuthSecurityScheme
         | OAuth2SecurityScheme
         | OpenIdConnectSecurityScheme
+        | MutualTLSSecurityScheme
     ]
 ):
     root: (
         APIKeySecurityScheme
         | HTTPAuthSecurityScheme
         | OAuth2SecurityScheme
         | OpenIdConnectSecurityScheme
+        | MutualTLSSecurityScheme
     )
     """
     Defines a security scheme that can be used to secure an agent's endpoints.
@@ -1754,18 +1785,24 @@ class AgentCard(A2ABaseModel):
     This creates a binding between the main URL and its supported transport protocol.
     Clients should prefer this transport and URL combination when both are supported.
     """
-    protocol_version: str | None = '0.2.6'
+    protocol_version: str | None = '0.3.0'
     """
     The version of the A2A protocol this agent supports.
     """
     provider: AgentProvider | None = None
     """
     Information about the agent's service provider.
     """
-    security: list[dict[str, list[str]]] | None = None
+    security: list[dict[str, list[str]]] | None = Field(
+        default=None,
+        examples=[[{'oauth': ['read']}, {'api-key': [], 'mtls': []}]],
+    )
     """
     A list of security requirement objects that apply to all agent interactions. Each object
     lists security schemes that can be used. Follows the OpenAPI 3.0 Security Requirement Object.
+    This list can be seen as an OR of ANDs. Each object in the list describes one possible
+    set of security requirements that must be present on a request. This allows specifying,
+    for example, "callers must either use OAuth OR an API Key AND mTLS."
     """
     security_schemes: dict[str, SecurityScheme] | None = None
     """

src/a2a/types.py

@@ -386,6 +386,12 @@ def security_scheme(
                     flows=cls.oauth2_flows(scheme.root.flows),
                 )
             )
+        if isinstance(scheme.root, types.MutualTLSSecurityScheme):
+            return a2a_pb2.SecurityScheme(
+                mtls_security_scheme=a2a_pb2.MutualTlsSecurityScheme(
+                    description=scheme.root.description,
+                )
+            )
         return a2a_pb2.SecurityScheme(
             open_id_connect_security_scheme=a2a_pb2.OpenIdConnectSecurityScheme(
                 description=scheme.root.description,

src/a2a/utils/proto_utils.py

@@ -22,11 +22,11 @@
     FilePart,
     FileWithBytes,
     FileWithUri,
-    GetTaskPushNotificationConfigParams,
-    GetTaskPushNotificationConfigRequest,
     GetAuthenticatedExtendedCardRequest,
     GetAuthenticatedExtendedCardResponse,
     GetAuthenticatedExtendedCardSuccessResponse,
+    GetTaskPushNotificationConfigParams,
+    GetTaskPushNotificationConfigRequest,
     GetTaskPushNotificationConfigResponse,
     GetTaskPushNotificationConfigSuccessResponse,
     GetTaskRequest,
@@ -1556,7 +1556,11 @@ def test_use_get_task_push_notification_params_for_request() -> None:
     )
 
 
-def test_camelCase() -> None:
+def test_camelCase_access_raises_attribute_error() -> None:
+    """
+    Tests that accessing or setting fields via their camelCase alias
+    raises an AttributeError.
+    """
     skill = AgentSkill(
         id='hello_world',
         name='Returns hello world',
@@ -1565,6 +1569,7 @@ def test_camelCase() -> None:
         examples=['hi', 'hello world'],
     )
 
+    # Initialization with camelCase still works due to Pydantic's populate_by_name config
     agent_card = AgentCard(
         name='Hello World Agent',
         description='Just a hello world agent',
@@ -1577,21 +1582,33 @@ def test_camelCase() -> None:
         supportsAuthenticatedExtendedCard=True,  # type: ignore
     )
 
-    # Test setting an attribute via camelCase alias
-    with pytest.warns(
-        DeprecationWarning,
-        match="Setting field 'supportsAuthenticatedExtendedCard'",
+    # --- Test that using camelCase aliases raises errors ---
+
+    # Test setting an attribute via camelCase alias raises AttributeError
+    with pytest.raises(
+        ValueError,
+        match='"AgentCard" object has no field "supportsAuthenticatedExtendedCard"',
     ):
         agent_card.supportsAuthenticatedExtendedCard = False
 
-    # Test getting an attribute via camelCase alias
-    with pytest.warns(
-        DeprecationWarning, match="Accessing field 'defaultInputModes'"
+    # Test getting an attribute via camelCase alias raises AttributeError
+    with pytest.raises(
+        AttributeError,
+        match="'AgentCard' object has no attribute 'defaultInputModes'",
     ):
-        default_input_modes = agent_card.defaultInputModes
+        _ = agent_card.defaultInputModes
+
+    # --- Test that using snake_case names works correctly ---
 
-    # Assert the functionality still works as expected
+    # The value should be unchanged because the camelCase setattr failed
+    assert agent_card.supports_authenticated_extended_card is True
+
+    # Now, set it correctly using the snake_case name
+    agent_card.supports_authenticated_extended_card = False
     assert agent_card.supports_authenticated_extended_card is False
+
+    # Get the attribute correctly using the snake_case name
+    default_input_modes = agent_card.default_input_modes
     assert default_input_modes == ['text']
     assert agent_card.default_input_modes == ['text']