feat(agent-card): add metadata field and expose list filter (#502)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: declan-scale

src/agentex/lib/core/temporal/workers/worker.py

@@ -178,6 +178,7 @@ def __init__(
         metrics_headers: dict[str, str] | None = None,
         metrics_use_http: bool = False,
         metrics_temporality_delta: bool = False,
+        agent_card: Any | None = None,
     ):
         self.task_queue = task_queue
         self.activity_handles = []
@@ -196,6 +197,7 @@ def __init__(
         self.metrics_temporality_delta = metrics_temporality_delta
         self.payload_codec = payload_codec
         self.data_converter = data_converter
+        self.agent_card = agent_card
 
     @overload
     async def run(
@@ -312,6 +314,6 @@ async def _register_agent(self):
             # the worker process never goes through the ACP server lifespan, so it needs its
             # own guard (mirrors base_acp_server.lifespan_context).
             await assert_backend_compatible(env_vars.AGENTEX_BASE_URL)
-            await register_agent(env_vars)
+            await register_agent(env_vars, agent_card=self.agent_card)
         else:
             logger.warning("AGENTEX_BASE_URL not set, skipping worker registration")

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
+from pydantic import Field, BaseModel
 
 if TYPE_CHECKING:
     from agentex.lib.sdk.state_machine.state import State
@@ -31,6 +31,11 @@ class AgentCard(BaseModel):
     data_events: list[str] = []
     input_types: list[str] = []
     output_schema: dict | None = None
+    # Free-form JSON object for opt-in self-description (e.g. protocol-specific
+    # 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
     def from_states(
@@ -40,6 +45,7 @@ def from_states(
         output_event_model: type[BaseModel] | None = None,
         extra_input_types: list[str] | None = None,
         queries: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
     ) -> AgentCard:
         """Build an AgentCard directly from a list[State] + initial_state.
 
@@ -81,6 +87,7 @@ def from_states(
             data_events=data_events,
             input_types=sorted(derived_input_types | set(extra_input_types or [])),
             output_schema=output_schema,
+            metadata=metadata or {},
         )
 
     @classmethod
@@ -90,6 +97,7 @@ def from_state_machine(
         output_event_model: type[BaseModel] | None = None,
         extra_input_types: list[str] | None = None,
         queries: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
     ) -> AgentCard:
         """Build an AgentCard from a StateMachine instance. Delegates to from_states()."""
         lifecycle = state_machine.get_lifecycle()
@@ -125,6 +133,7 @@ def from_state_machine(
             data_events=data_events,
             input_types=sorted(derived_input_types | set(extra_input_types or [])),
             output_schema=output_schema,
+            metadata=metadata or {},
         )
 
 

src/agentex/lib/utils/metadata_filters.py

@@ -0,0 +1,58 @@
+"""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}),
+    )
+
+The ``agent_card_metadata`` filter requires an Agentex server that includes
+scaleapi/scale-agentex#411. Older servers ignore the unknown query parameter
+and return the full unfiltered agent list rather than erroring, and the SDK's
+startup backend-contract check does not guard against this.
+"""
+
+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

tests/lib/core/temporal/workers/test_worker_version_guard.py

@@ -40,7 +40,7 @@ async def test_guard_runs_before_register_agent(monkeypatch):
     await _worker()._register_agent()
 
     guard.assert_awaited_once_with("http://backend")
-    register.assert_awaited_once_with(env)
+    register.assert_awaited_once_with(env, agent_card=None)
     assert order == ["guard", "register"]  # guard must precede registration
 
 

tests/lib/test_agent_card.py

@@ -189,13 +189,42 @@ def test_defaults(self):
         assert card.data_events == []
         assert card.input_types == []
         assert card.output_schema is None
+        assert card.metadata == {}
 
     def test_serialization_roundtrip(self):
         card = AgentCard(input_types=["text"], data_events=["result"])
         dumped = card.model_dump()
         restored = AgentCard.model_validate(dumped)
         assert restored == card
 
+    def test_metadata_accepts_arbitrary_json_object(self):
+        card = AgentCard(
+            metadata={
+                "permits_capable": True,
+                "supported_workflows": ["submit", "review"],
+                "limits": {"max_batch": 5},
+            }
+        )
+        assert card.metadata == {
+            "permits_capable": True,
+            "supported_workflows": ["submit", "review"],
+            "limits": {"max_batch": 5},
+        }
+
+    def test_metadata_serialization_roundtrip(self):
+        card = AgentCard(metadata={"permits_capable": True})
+        dumped = card.model_dump()
+        assert dumped["metadata"] == {"permits_capable": True}
+        restored = AgentCard.model_validate(dumped)
+        assert restored == card
+
+    def test_metadata_default_instances_are_independent(self):
+        """Each default metadata is its own dict, not a shared class-level object."""
+        card_a = AgentCard()
+        card_b = AgentCard()
+        card_a.metadata["mutated"] = True
+        assert card_b.metadata == {}
+
 
 # --- AgentCard.from_states ---
 
@@ -247,6 +276,14 @@ def test_state_fields(self, sample_states):
         assert waiting.accepts == ["text", "doc_upload"]
         assert waiting.transitions == ["processing"]
 
+    def test_metadata_forwarded(self, sample_states):
+        card = AgentCard.from_states(
+            initial_state=SampleState.WAITING,
+            states=sample_states,
+            metadata={"permits_capable": True},
+        )
+        assert card.metadata == {"permits_capable": True}
+
     def test_matches_from_state_machine(self, sample_states, sample_sm):
         """from_states and from_state_machine should produce identical cards."""
         card_states = AgentCard.from_states(
@@ -315,6 +352,13 @@ def test_no_output_model(self, sample_sm):
         assert card.data_events == []
         assert card.output_schema is None
 
+    def test_metadata_forwarded(self, sample_sm):
+        card = AgentCard.from_state_machine(
+            state_machine=sample_sm,
+            metadata={"permits_capable": True},
+        )
+        assert card.metadata == {"permits_capable": True}
+
 
 # --- register_agent agent_card merging ---
 
@@ -370,6 +414,20 @@ async def test_agent_card_merged_into_metadata(self, mock_env_vars):
             assert metadata["agent_card"]["input_types"] == ["text"]
             assert metadata["agent_card"]["data_events"] == ["result"]
 
+    async def test_agent_card_metadata_propagates_through_registration(self, mock_env_vars):
+        card = AgentCard(metadata={"permits_capable": True})
+        mock_client = self._make_mock_client()
+
+        with patch("agentex.lib.utils.registration.httpx.AsyncClient", return_value=mock_client):
+            from agentex.lib.utils.registration import register_agent
+
+            await register_agent(mock_env_vars, agent_card=card)
+
+            sent_data = mock_client.post.call_args.kwargs["json"]
+            metadata = sent_data["registration_metadata"]
+
+            assert metadata["agent_card"]["metadata"] == {"permits_capable": True}
+
     async def test_none_preserved_when_no_card(self, mock_env_vars):
         mock_client = self._make_mock_client()