chore: release main

.release-please-manifest.json

@@ -1,4 +1,4 @@
 {
-  ".": "0.13.1",
-  "adk": "0.13.1"
+  ".": "0.14.0",
+  "adk": "0.13.2"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 64
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-dfcee301cded58822f489f034b6fcd42f392df406ca3780e7213698cec59c777.yml
-openapi_spec_hash: 3aae4790b24edf6ea9469c1680d513ae
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-ae2571b5ac5d337ba5ced527cec0ff6e3088296fa67c3c836ed5a06544b25cb8.yml
+openapi_spec_hash: 962a2f20444c7823fd3a34f95365146e
 config_hash: 138b7c0b394e7393133c8ff16a6d0eb3

CHANGELOG.md

@@ -6,6 +6,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.14.0 (2026-06-22)
+
+Full Changelog: [agentex-client-v0.13.1...agentex-client-v0.14.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.13.1...agentex-client-v0.14.0)
+
+### Features
+
+* **api:** add is error to tools ([8ddd960](https://github.com/scaleapi/scale-agentex-python/commit/8ddd9604290d23ed59586a68bd6db46bf452104b))
+* **compat:** runtime SDK↔backend version guard at ACP startup ([#408](https://github.com/scaleapi/scale-agentex-python/issues/408)) ([433c999](https://github.com/scaleapi/scale-agentex-python/commit/433c999bbdb4817d2048c5454cb65b54812950af))
+
+
+### Bug Fixes
+
+* **types:** add missing Optional import to ToolResponseContent ([3439f6e](https://github.com/scaleapi/scale-agentex-python/commit/3439f6edec9ab89d685b5b1c99e567a67c911522))
+
 ## 0.13.1 (2026-06-17)
 
 Full Changelog: [agentex-client-v0.13.0...agentex-client-v0.13.1](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.13.0...agentex-client-v0.13.1)

adk/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.13.2 (2026-06-22)
+
+Full Changelog: [agentex-sdk-v0.13.1...agentex-sdk-v0.13.2](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.13.1...agentex-sdk-v0.13.2)
+
 ## 0.13.1 (2026-06-17)
 
 Full Changelog: [agentex-sdk-v0.13.0...agentex-sdk-v0.13.1](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.13.0...agentex-sdk-v0.13.1)

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.13.1"
+version = "0.13.2"
 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.13.1"
+version = "0.14.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.13.1"  # x-release-please-version
+__version__ = "0.14.0"  # x-release-please-version

src/agentex/lib/core/compat/__init__.py

@@ -0,0 +1 @@
+

src/agentex/lib/core/compat/version_guard.py

@@ -0,0 +1,164 @@
+"""Runtime SDK ↔ backend contract-version guard.
+
+Complements the *build-time* cross-version compatibility tests (``tests/compat``):
+
+- **Build-time** (CI): is this *client* compatible with the window of supported server
+  contracts (``min-supported``..``current``)?
+- **Runtime** (this module): is the *server* the SDK is pointed at within that window?
+
+It runs once at ACP/worker startup, reads the backend's contract version (the version
+the server already reports via ``/openapi.json`` ``info.version``), and **fails fast with
+an actionable error** if the backend is older than this SDK supports — instead of the
+mismatch surfacing later as opaque 500s / missing-field errors deep in a request.
+
+``MIN_BACKEND_CONTRACT`` is the same source of truth as the ``min-supported`` server
+contract in ``tests/compat/server_specs/manifest.json``: the oldest agentex backend this
+SDK version supports. Bump both together when a breaking change raises the floor.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+import httpx
+
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+# Oldest agentex backend contract this SDK is compatible with.
+# Keep in sync with the `min-supported` spec in tests/compat (#407); the version axis
+# itself comes from scale-agentex release tags (#321). Bump on a breaking SDK change.
+MIN_BACKEND_CONTRACT = "0.1.0"
+
+SKIP_ENV = "AGENTEX_SKIP_VERSION_CHECK"
+
+# Full-string SemVer. Accepts: `1.2.3`, leading `v`, surrounding whitespace, `-prerelease`
+# (captured), `+build` (ignored). Anchored at both ends so a malformed tail (`0.1.0rc1`,
+# `0.1.0.1`) is rejected → None → "unknown, proceed", not silently coerced to stable `0.1.0`.
+_VERSION_RE = re.compile(
+    r"^\s*v?(\d+)\.(\d+)\.(\d+)"  # major.minor.patch
+    r"(?:-([0-9A-Za-z.-]+))?"  # optional -prerelease (captured)
+    r"(?:\+[0-9A-Za-z.-]+)?"  # optional +build metadata (ignored)
+    r"\s*$"
+)
+
+
+class IncompatibleBackendError(RuntimeError):
+    """Raised when the agentex backend is older than this SDK's minimum supported contract."""
+
+
+def _parse(version: str | None) -> tuple[int, int, int, str | None] | None:
+    """Parse ``major.minor.patch[-prerelease]`` → ``(major, minor, patch, prerelease)``.
+
+    ``prerelease`` is the raw dot-separated identifier string (e.g. ``"rc.1"``), or None for
+    a stable release. Build metadata (after ``+``) is ignored. Returns None if unparseable.
+    """
+    m = _VERSION_RE.match(version or "")
+    if not m:
+        return None
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3)), m.group(4) or None)
+
+
+# Comparable SemVer precedence key. The 4th element keeps a uniform shape across stable and
+# prerelease so the whole tuple is orderable: (rank, identifiers), where stable rank 1 > prerelease
+# rank 0 (and the identifier list is only ever compared when both sides are prereleases, rank 0).
+_PreKey = tuple[int, int, int, tuple[int, list[tuple[int, int, str]]]]
+
+
+def _precedence_key(parsed: tuple[int, int, int, str | None]) -> _PreKey:
+    """SemVer §11 precedence key (directly comparable with ``<``).
+
+    A stable release outranks any prerelease of the same triplet (``0.1.0-rc.1 < 0.1.0``);
+    among prereleases, numeric identifiers rank below alphanumeric and compare field-by-field,
+    with a longer identifier list outranking a shorter prefix-equal one.
+    """
+    major, minor, patch, prerelease = parsed
+    if prerelease is None:
+        return (major, minor, patch, (1, []))  # stable sorts above every prerelease
+    identifiers: list[tuple[int, int, str]] = []
+    for ident in prerelease.split("."):
+        if ident.isdigit():
+            identifiers.append((0, int(ident), ""))  # numeric: lowest class, numeric order
+        else:
+            identifiers.append((1, 0, ident))  # alphanumeric: higher class, lexical order
+    return (major, minor, patch, (0, identifiers))
+
+
+def _truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+async def fetch_backend_version(base_url: str, *, timeout: float = 5.0) -> str | None:
+    """Return the backend's reported contract version (``/openapi.json`` ``info.version``), or None."""
+    url = base_url.rstrip("/") + "/openapi.json"
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(url)
+            resp.raise_for_status()
+            return (resp.json().get("info") or {}).get("version")
+    except Exception as exc:  # noqa: BLE001 - any failure → unknown, handled by caller
+        logger.warning("backend version guard: could not fetch %s (%s)", url, exc)
+        return None
+
+
+async def assert_backend_compatible(
+    base_url: str | None,
+    *,
+    min_version: str = MIN_BACKEND_CONTRACT,
+    sdk_version: str | None = None,
+) -> None:
+    """Fail fast at startup if the backend is older than ``min_version``.
+
+    No-op (warns, does not raise) when:
+      - ``AGENTEX_SKIP_VERSION_CHECK`` is set (explicit bypass),
+      - ``base_url`` is unset,
+      - the backend version can't be determined (unreachable / unparseable) — a transient
+        blip or a contract-less server shouldn't crash startup.
+
+    Raises ``IncompatibleBackendError`` only when the backend version is *known* and older
+    than ``min_version``.
+    """
+    if _truthy(SKIP_ENV):
+        logger.warning("%s set — skipping backend version guard", SKIP_ENV)
+        return
+    if not base_url:
+        return
+
+    if sdk_version is None:
+        from agentex._version import __version__ as sdk_version  # local import to avoid cycles
+
+    backend_version = await fetch_backend_version(base_url)
+    if backend_version is None:
+        logger.warning(
+            "backend version guard: could not determine backend version at %s; proceeding "
+            "(set %s=1 to silence).",
+            base_url,
+            SKIP_ENV,
+        )
+        return
+
+    backend, minimum = _parse(backend_version), _parse(min_version)
+    if backend is None or minimum is None:
+        logger.warning(
+            "backend version guard: unparseable version(s) backend=%r min=%r; proceeding.",
+            backend_version,
+            min_version,
+        )
+        return
+
+    if _precedence_key(backend) < _precedence_key(minimum):
+        raise IncompatibleBackendError(
+            f"agentex-sdk {sdk_version} requires agentex backend >= {min_version}, "
+            f"but {base_url} reports {backend_version}. "
+            f"Upgrade the backend, or pin agentex-sdk to a version compatible with backend "
+            f"{backend_version}. (Set {SKIP_ENV}=1 to bypass at your own risk.)"
+        )
+
+    logger.info(
+        "backend version guard OK: sdk=%s backend=%s (min=%s)",
+        sdk_version,
+        backend_version,
+        min_version,
+    )

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

@@ -30,6 +30,7 @@
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.registration import register_agent
 from agentex.lib.environment_variables import EnvironmentVariables
+from agentex.lib.core.compat.version_guard import assert_backend_compatible
 
 logger = make_logger(__name__)
 
@@ -278,6 +279,10 @@ async def start_health_check_server(self):
     async def _register_agent(self):
         env_vars = EnvironmentVariables.refresh()
         if env_vars and env_vars.AGENTEX_BASE_URL:
+            # Fail fast if this worker is pointed at a backend older than the SDK supports —
+            # 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)
         else:
             logger.warning("AGENTEX_BASE_URL not set, skipping worker registration")

src/agentex/lib/sdk/fastacp/base/base_acp_server.py

@@ -33,6 +33,7 @@
 from agentex.types.task_message_update import TaskMessageUpdate, StreamTaskMessageFull
 from agentex.types.task_message_content import TaskMessageContent
 from agentex.lib.core.tracing.span_queue import shutdown_default_span_queue
+from agentex.lib.core.compat.version_guard import assert_backend_compatible
 from agentex.lib.sdk.fastacp.base.constants import (
     FASTACP_HEADER_SKIP_EXACT,
     FASTACP_HEADER_SKIP_PREFIXES,
@@ -104,6 +105,9 @@ def get_lifespan_function(self):
         async def lifespan_context(app: FastAPI):  # noqa: ARG001
             env_vars = EnvironmentVariables.refresh()
             if env_vars.AGENTEX_BASE_URL:
+                # Runtime SDK<->backend contract guard: fail fast if the backend is older
+                # than this SDK supports, instead of opaque 500s later. See compat.version_guard.
+                await assert_backend_compatible(env_vars.AGENTEX_BASE_URL)
                 await register_agent(env_vars, agent_card=self._agent_card)
                 self.agent_id = env_vars.AGENT_ID
             else:

src/agentex/resources/messages/messages.py

@@ -670,6 +670,19 @@ def list(
                         "default": null,
                         "description": "The result of the tool.",
                         "title": "Content"
+                      },
+                      "is_error": {
+                        "anyOf": [
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "default": null,
+                        "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.",
+                        "title": "Is Error"
                       }
                     },
                     "title": "ToolResponseContentEntityOptional",
@@ -1237,6 +1250,19 @@ def list_paginated(
                         "default": null,
                         "description": "The result of the tool.",
                         "title": "Content"
+                      },
+                      "is_error": {
+                        "anyOf": [
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "default": null,
+                        "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.",
+                        "title": "Is Error"
                       }
                     },
                     "title": "ToolResponseContentEntityOptional",
@@ -1943,6 +1969,19 @@ async def list(
                         "default": null,
                         "description": "The result of the tool.",
                         "title": "Content"
+                      },
+                      "is_error": {
+                        "anyOf": [
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "default": null,
+                        "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.",
+                        "title": "Is Error"
                       }
                     },
                     "title": "ToolResponseContentEntityOptional",
@@ -2510,6 +2549,19 @@ async def list_paginated(
                         "default": null,
                         "description": "The result of the tool.",
                         "title": "Content"
+                      },
+                      "is_error": {
+                        "anyOf": [
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "null"
+                          }
+                        ],
+                        "default": null,
+                        "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.",
+                        "title": "Is Error"
                       }
                     },
                     "title": "ToolResponseContentEntityOptional",

src/agentex/types/message_list_paginated_params.py

@@ -470,6 +470,19 @@ class MessageListPaginatedParams(TypedDict, total=False):
               "default": null,
               "description": "The result of the tool.",
               "title": "Content"
+            },
+            "is_error": {
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.",
+              "title": "Is Error"
             }
           },
           "title": "ToolResponseContentEntityOptional",

src/agentex/types/message_list_params.py

@@ -466,6 +466,19 @@ class MessageListParams(TypedDict, total=False):
               "default": null,
               "description": "The result of the tool.",
               "title": "Content"
+            },
+            "is_error": {
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Whether the tool call resulted in an error. `None` when the harness does not report a status.",
+              "title": "Is Error"
             }
           },
           "title": "ToolResponseContentEntityOptional",