fix(agent-card): add a mapping helper for the metadata filter, fix ruff

Review follow-ups on the agents.list card metadata filter.

The generated `agent_card_metadata` parameter stays `Optional[str]`. The
platform spec declares it the same way the already-shipped
`tasks.list(task_metadata=...)` filter is declared -- a nullable string
carrying a JSON-encoded object -- because the generator does not honour a
`content: application/json` query parameter and falls back to `type: string`
regardless. Widening the parameter here would be an edit the next
regeneration silently reverts, so the ergonomics live in the hand-written
layer instead: `agentex.lib.utils.metadata_filters.encode_metadata_filter`
turns a mapping into the exact wire value, with key order pinned so the same
filter always produces the same query string, and rejects NaN/Infinity up
front rather than letting the server return a 400.

The generated docstrings are updated to match the parameter description in
the spec, so a regeneration is now a no-op on these files.

Adds exercised request-level tests (respx, sync and async) asserting the
encoded mapping actually reaches the query string, and that an empty-object
filter is sent verbatim rather than dropped as falsy -- `{}` is meaningful
server-side. These use their own clients rather than the skip-guarded
mock-server fixtures, so they run in CI.

Also fixes the failing ruff import-order check in agent_card.py.

Author: declan-scale

src/agentex/lib/types/agent_card.py

@@ -5,7 +5,7 @@
 from enum import Enum
 from typing import TYPE_CHECKING, Any, get_args, get_origin
 
-from pydantic import BaseModel, Field
+from pydantic import Field, BaseModel
 
 if TYPE_CHECKING:
     from agentex.lib.sdk.state_machine.state import State
@@ -32,8 +32,9 @@ class AgentCard(BaseModel):
     input_types: list[str] = []
     output_schema: dict | None = None
     # Free-form JSON object for opt-in self-description (e.g. protocol-specific
-    # capability flags) that callers can filter agents by via
-    # ``GET /agents?agent_card_metadata=...``. Not interpreted by the platform.
+    # capability flags). Not interpreted by the platform, but callers can filter
+    # agents on it with ``agents.list(agent_card_metadata=...)`` -- see
+    # ``agentex.lib.utils.metadata_filters.encode_metadata_filter``.
     metadata: dict[str, Any] = Field(default_factory=dict)
 
     @classmethod

src/agentex/lib/utils/metadata_filters.py

@@ -0,0 +1,53 @@
+"""Helpers for the platform's JSON-encoded metadata filter query parameters.
+
+The containment filters on ``agents.list(agent_card_metadata=...)`` and
+``tasks.list(task_metadata=...)`` carry their filter as a JSON-encoded object
+inside a single query string value, so the generated clients type them as
+``str``. Encoding by hand is easy to get subtly wrong -- Python's ``json``
+happily emits ``NaN``/``Infinity``, which the server rejects with a 400 -- so
+these helpers do it once, here, in the hand-written layer where they survive
+SDK regeneration.
+
+    from agentex.lib.utils.metadata_filters import encode_metadata_filter
+
+    client.agents.list(
+        agent_card_metadata=encode_metadata_filter({"permits_capable": True}),
+    )
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping
+
+__all__ = ["encode_metadata_filter"]
+
+
+def encode_metadata_filter(metadata: Mapping[str, Any]) -> str:
+    """Encode a metadata filter mapping into the wire form the platform expects.
+
+    Args:
+        metadata: The key/value pairs the target's metadata object must contain.
+            Values may be any JSON type; matching is exact containment, so
+            ``{"permits_capable": True}`` matches a stored JSON ``true`` but not
+            the string ``"true"``. An empty mapping matches any target that has
+            a metadata object at all.
+
+    Returns:
+        A compact JSON object string, with keys sorted so the same filter always
+        produces the same query value.
+
+    Raises:
+        TypeError: If ``metadata`` is not a mapping, or contains a value that
+            isn't JSON-serializable.
+        ValueError: If a value is a non-finite float. ``NaN`` and ``Infinity``
+            aren't valid JSON and the server rejects them with a 400, so fail
+            here with a clearer message instead.
+    """
+    if not isinstance(metadata, Mapping):
+        raise TypeError(f"metadata must be a mapping, got {type(metadata).__name__}")
+
+    try:
+        return json.dumps(metadata, allow_nan=False, separators=(",", ":"), sort_keys=True)
+    except ValueError as exc:
+        raise ValueError(f"metadata filter is not encodable as JSON: {exc}") from exc

src/agentex/resources/agents/agents.py

@@ -133,9 +133,9 @@ def list(
         List all registered agents, optionally filtered by query parameters.
 
         Args:
-          agent_card_metadata: JSON-encoded object filtered against
-              ``registration_metadata.agent_card.metadata`` using exact key/value
-              containment semantics.
+          agent_card_metadata: JSON-encoded object used to filter agents on
+              `registration_metadata.agent_card.metadata` via JSONB containment. Example:
+              {"permits_capable": true}.
 
           limit: Limit
 
@@ -800,9 +800,9 @@ async def list(
         List all registered agents, optionally filtered by query parameters.
 
         Args:
-          agent_card_metadata: JSON-encoded object filtered against
-              ``registration_metadata.agent_card.metadata`` using exact key/value
-              containment semantics.
+          agent_card_metadata: JSON-encoded object used to filter agents on
+              `registration_metadata.agent_card.metadata` via JSONB containment. Example:
+              {"permits_capable": true}.
 
           limit: Limit
 

src/agentex/types/agent_list_params.py

@@ -10,8 +10,11 @@
 
 class AgentListParams(TypedDict, total=False):
     agent_card_metadata: Optional[str]
-    """JSON-encoded object filtered against ``registration_metadata.agent_card.metadata``
-    with exact key/value containment semantics."""
+    """
+    JSON-encoded object used to filter agents on
+    `registration_metadata.agent_card.metadata` via JSONB containment. Example:
+    {"permits_capable": true}.
+    """
 
     limit: int
     """Limit"""

tests/lib/test_metadata_filters.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+import respx
+import pytest
+
+from agentex import Agentex, AsyncAgentex
+from agentex.lib.utils.metadata_filters import encode_metadata_filter
+
+BASE_URL = "http://127.0.0.1:4010"
+API_KEY = "My API Key"
+
+
+class TestEncodeMetadataFilter:
+    def test_encodes_a_json_object(self) -> None:
+        assert encode_metadata_filter({"permits_capable": True}) == '{"permits_capable":true}'
+
+    def test_empty_mapping_encodes_to_an_empty_object(self) -> None:
+        assert encode_metadata_filter({}) == "{}"
+
+    def test_key_order_is_stable(self) -> None:
+        assert (
+            encode_metadata_filter({"region": "us", "permits_capable": True})
+            == encode_metadata_filter({"permits_capable": True, "region": "us"})
+            == '{"permits_capable":true,"region":"us"}'
+        )
+
+    def test_preserves_json_types_and_nesting(self) -> None:
+        encoded = encode_metadata_filter({"flag": True, "count": 3, "ratio": 1.5, "nested": {"a": [1, "two", None]}})
+        assert json.loads(encoded) == {
+            "flag": True,
+            "count": 3,
+            "ratio": 1.5,
+            "nested": {"a": [1, "two", None]},
+        }
+
+    @pytest.mark.parametrize("value", [float("nan"), float("inf"), float("-inf")])
+    def test_rejects_non_finite_floats(self, value: float) -> None:
+        # The server rejects these with a 400; fail locally with a clearer message.
+        with pytest.raises(ValueError, match="not encodable as JSON"):
+            encode_metadata_filter({"x": value})
+
+    def test_rejects_a_non_mapping(self) -> None:
+        with pytest.raises(TypeError, match="must be a mapping"):
+            encode_metadata_filter([("permits_capable", True)])  # type: ignore[arg-type]
+
+    def test_rejects_a_non_serializable_value(self) -> None:
+        with pytest.raises(TypeError):
+            encode_metadata_filter({"x": object()})
+
+
+class TestAgentCardMetadataOnTheWire:
+    """The encoded filter has to survive the client's query-string serialization.
+
+    The generated `agents.list` parameter is a plain `str` (the platform spec
+    declares a JSON-encoded string, matching the shipped `task_metadata`
+    filter), so these assert the exact query value the server will parse.
+    """
+
+    @respx.mock(base_url=BASE_URL)
+    def test_sync_client_sends_the_encoded_object(self, respx_mock: respx.MockRouter) -> None:
+        route = respx_mock.get("/agents").mock(return_value=httpx.Response(200, json=[]))
+
+        with Agentex(base_url=BASE_URL, api_key=API_KEY, _strict_response_validation=True) as client:
+            client.agents.list(
+                agent_card_metadata=encode_metadata_filter({"permits_capable": True, "region": "us"}),
+                limit=5,
+            )
+
+        params = route.calls.last.request.url.params
+        raw = params["agent_card_metadata"]
+        assert raw == '{"permits_capable":true,"region":"us"}'
+        assert json.loads(raw) == {"permits_capable": True, "region": "us"}
+        assert params["limit"] == "5"
+
+    @respx.mock(base_url=BASE_URL)
+    async def test_async_client_sends_the_encoded_object(self, respx_mock: respx.MockRouter) -> None:
+        route = respx_mock.get("/agents").mock(return_value=httpx.Response(200, json=[]))
+
+        async with AsyncAgentex(base_url=BASE_URL, api_key=API_KEY, _strict_response_validation=True) as client:
+            await client.agents.list(
+                agent_card_metadata=encode_metadata_filter({"permits_capable": True, "region": "us"}),
+                limit=5,
+            )
+
+        params = route.calls.last.request.url.params
+        raw = params["agent_card_metadata"]
+        assert raw == '{"permits_capable":true,"region":"us"}'
+        assert json.loads(raw) == {"permits_capable": True, "region": "us"}
+        assert params["limit"] == "5"
+
+    @respx.mock(base_url=BASE_URL)
+    def test_omitted_filter_is_absent_from_the_query(self, respx_mock: respx.MockRouter) -> None:
+        route = respx_mock.get("/agents").mock(return_value=httpx.Response(200, json=[]))
+
+        with Agentex(base_url=BASE_URL, api_key=API_KEY, _strict_response_validation=True) as client:
+            client.agents.list()
+
+        assert "agent_card_metadata" not in route.calls.last.request.url.params
+
+    @respx.mock(base_url=BASE_URL)
+    def test_empty_object_filter_is_sent_verbatim(self, respx_mock: respx.MockRouter) -> None:
+        """`{}` is a meaningful filter server-side (agent must have card metadata),
+        so it must reach the wire rather than being dropped as falsy."""
+        route = respx_mock.get("/agents").mock(return_value=httpx.Response(200, json=[]))
+
+        with Agentex(base_url=BASE_URL, api_key=API_KEY, _strict_response_validation=True) as client:
+            client.agents.list(agent_card_metadata=encode_metadata_filter({}))
+
+        assert route.calls.last.request.url.params["agent_card_metadata"] == "{}"