Merge remote-tracking branch 'origin/next' into stephen/agentex-sdk-genai-metrics

# Conflicts:
#	.stats.yml
#	src/agentex/lib/utils/logging.py

Author: stephen-wang24

.release-please-manifest.json

@@ -1,4 +1,4 @@
 {
-  ".": "0.25.0",
-  "adk": "0.25.0"
+  ".": "0.26.0",
+  "adk": "0.26.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 75
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-ee0c521f0612c31b874bd595b90cd9209545bab603983552a1a7a87f38ed931e.yml
-openapi_spec_hash: 917a1ffe9e353bed2740524dec786ed2
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-fbc0683871d6abb03588f30d9468eeeeacb2b8538eb0c9002813e6df68c5802b.yml
+openapi_spec_hash: 4ecd8d496f056dccf80826264ddf8fe1
 config_hash: 593e89b291976a5e84e4c3c3f8324354

CHANGELOG.md

@@ -12,6 +12,20 @@
 
 * **tracing:** emit OTel metrics for async span queue depth, batch drain, and SGP export success/failure (HTTP status labels). Disable SDK-side recording with ``AGENTEX_TRACING_METRICS=0``.
 
+## 0.26.0 (2026-09-14)
+
+Full Changelog: [agentex-client-v0.25.0...agentex-client-v0.26.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.25.0...agentex-client-v0.26.0)
+
+### Features
+
+* **agent-card:** add metadata field and expose list filter ([#502](https://github.com/scaleapi/scale-agentex-python/issues/502)) ([55a0178](https://github.com/scaleapi/scale-agentex-python/commit/55a0178c2d210325770b56dbb58eac2f644cc14b))
+* **api:** add agent_card_metadata parameter to agents list method ([ebb632a](https://github.com/scaleapi/scale-agentex-python/commit/ebb632a4b22287e157bcf086dd98b27f26188fc5))
+* **tracing:** add opt-in commit SHA stamping for SGP spans ([#505](https://github.com/scaleapi/scale-agentex-python/issues/505)) ([76252a9](https://github.com/scaleapi/scale-agentex-python/commit/76252a98f28663e8c95777456d07e42171592c62))
+
+### Bug Fixes
+
+* keep agent output streaming alive on an unreadable line, and honor LOG_LEVEL ([#509](https://github.com/scaleapi/scale-agentex-python/issues/509)) ([0db6037](https://github.com/scaleapi/scale-agentex-python/commit/0db6037e63ca1b24b80ae0d38883f7687ae5b9e5))
+
 ## 0.25.0 (2026-08-26)
 
 Full Changelog: [agentex-client-v0.24.0...agentex-client-v0.25.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.24.0...agentex-client-v0.25.0)

adk/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.26.0 (2026-09-14)
+
+Full Changelog: [agentex-sdk-v0.25.0...agentex-sdk-v0.26.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.25.0...agentex-sdk-v0.26.0)
+
+### Chores
+
+* **agentex-sdk:** Synchronize agentex versions
+
 ## 0.25.0 (2026-08-26)
 
 Full Changelog: [agentex-sdk-v0.24.0...agentex-sdk-v0.25.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.24.0...agentex-sdk-v0.25.0)

adk/pyproject.toml

@@ -4,7 +4,7 @@
 # (agentex/{__init__.py, _*.py, types/, resources/}) ships from the slim
 # sibling package `agentex-client` which is pinned as a runtime dep.
 name = "agentex-sdk"
-version = "0.25.0"
+version = "0.26.0"
 description = "Agent Development Kit (ADK) overlay for the Agentex API — FastACP server, Temporal workflows, LLM provider integrations, observability"
 license = "Apache-2.0"
 authors = [

pyproject.toml

@@ -3,7 +3,7 @@
 # overlay (formerly `src/agentex/lib/*`) now lives in `adk/` and ships
 # as the sibling `agentex-sdk` package — see `adk/pyproject.toml`.
 name = "agentex-client"
-version = "0.25.0"
+version = "0.26.0"
 description = "The official Python REST client for the Agentex API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/agentex/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "agentex"
-__version__ = "0.25.0"  # x-release-please-version
+__version__ = "0.26.0"  # x-release-please-version

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

@@ -180,6 +180,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 = []
@@ -198,6 +199,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(
@@ -333,6 +335,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