docs(sdk): document server version requirement and deployment-path gap for the card filter

Adds the minimum-server note to metadata_filters (older servers ignore the
unknown query parameter and return the full agent list) and syncs the
generated agent_card_metadata docstrings with the updated OpenAPI
description from scaleapi/scale-agentex#411.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: declan-scale

src/agentex/lib/utils/metadata_filters.py

@@ -13,6 +13,11 @@
     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

src/agentex/resources/agents/agents.py

@@ -135,7 +135,10 @@ def list(
         Args:
           agent_card_metadata: JSON-encoded object used to filter agents on
               `registration_metadata.agent_card.metadata` via JSONB containment. Example:
-              {"permits_capable": true}.
+              {"permits_capable": true}. Only matches cards published through the direct
+              registration path: registrations that carry a `deployment_id` write the card
+              to the deployment record instead of `registration_metadata`, so those agents
+              never match this filter.
 
           limit: Limit
 
@@ -802,7 +805,10 @@ async def list(
         Args:
           agent_card_metadata: JSON-encoded object used to filter agents on
               `registration_metadata.agent_card.metadata` via JSONB containment. Example:
-              {"permits_capable": true}.
+              {"permits_capable": true}. Only matches cards published through the direct
+              registration path: registrations that carry a `deployment_id` write the card
+              to the deployment record instead of `registration_metadata`, so those agents
+              never match this filter.
 
           limit: Limit
 

src/agentex/types/agent_list_params.py

@@ -13,7 +13,10 @@ class AgentListParams(TypedDict, total=False):
     """
     JSON-encoded object used to filter agents on
     `registration_metadata.agent_card.metadata` via JSONB containment. Example:
-    {"permits_capable": true}.
+    {"permits_capable": true}. Only matches cards published through the direct
+    registration path: registrations that carry a `deployment_id` write the card to
+    the deployment record instead of `registration_metadata`, so those agents never
+    match this filter.
     """
 
     limit: int