fix(tracing): capture span body exceptions and export SGP status=ERROR

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 65
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-cd43ba4b554ca024dd7ee7b74e4f4700a743282c17def704a0967e6ff251c09b.yml
-openapi_spec_hash: 9369ccc9c0289e9d6f641a526d244d1c
-config_hash: 1ae003838971335aac550f3ad5872f54
+configured_endpoints: 72
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-ad493b43ecb1652a9e522451c616e33775e628c1d79c224dff34855bd82c8c7c.yml
+openapi_spec_hash: 77044dc5774eb88f1541ebbe53b413a7
+config_hash: 50803c6c42bb738099163f3f4d3cdeed

README.md

@@ -139,6 +139,23 @@ Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typ
 
 Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
 
+## Nested params
+
+Nested parameters are dictionaries, typed using `TypedDict`, for example:
+
+```python
+from agentex import Agentex
+
+client = Agentex()
+
+schedule = client.agents.schedules.create(
+    agent_id="agent_id",
+    initial_input={"content": "content"},
+    name="name",
+)
+print(schedule.initial_input)
+```
+
 ## Handling errors
 
 When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `agentex.APIConnectionError` is raised.

adk/pyproject.toml

@@ -41,7 +41,14 @@ dependencies = [
     # LLM provider integrations
     "litellm>=1.83.7,<2",
     "openai-agents>=0.14.3,<0.15",
-    "openai>=2.2,<3", # Required by openai-agents; litellm now supports openai 2.x (issue #13711 resolved: https://github.com/BerriAI/litellm/issues/13711)
+    # Cap <2.45: openai 2.45.0 makes InputTokensDetails.cache_write_tokens a
+    # required field, but openai-agents 0.14.x still builds
+    # InputTokensDetails(cached_tokens=0) (agents/usage.py), so every
+    # Runner.run_streamed raises a pydantic ValidationError at context setup.
+    # openai-agents 0.14.8 is the latest release, so there is no newer version
+    # to bump to; drop this ceiling once openai-agents ships a fix.
+    # litellm now supports openai 2.x (issue #13711 resolved: https://github.com/BerriAI/litellm/issues/13711)
+    "openai>=2.2,<2.45",
     "claude-agent-sdk>=0.1.0",
     "pydantic-ai-slim>=1.0,<2",
     "langgraph-checkpoint>=2.0.0",

api.md

@@ -69,22 +69,35 @@ Types:
 from agentex.types.agents import (
     ScheduleCreateResponse,
     ScheduleRetrieveResponse,
+    ScheduleUpdateResponse,
     ScheduleListResponse,
     SchedulePauseResponse,
+    SchedulePauseByNameResponse,
+    ScheduleResumeResponse,
+    ScheduleResumeByNameResponse,
+    ScheduleRetrieveByNameResponse,
     ScheduleTriggerResponse,
-    ScheduleUnpauseResponse,
+    ScheduleTriggerByNameResponse,
+    ScheduleUpdateByNameResponse,
 )
 ```
 
 Methods:
 
 - <code title="post /agents/{agent_id}/schedules">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">create</a>(agent_id, \*\*<a href="src/agentex/types/agents/schedule_create_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_create_response.py">ScheduleCreateResponse</a></code>
-- <code title="get /agents/{agent_id}/schedules/{schedule_name}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">retrieve</a>(schedule_name, \*, agent_id) -> <a href="./src/agentex/types/agents/schedule_retrieve_response.py">ScheduleRetrieveResponse</a></code>
+- <code title="get /agents/{agent_id}/schedules/{schedule_id}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">retrieve</a>(schedule_id, \*, agent_id) -> <a href="./src/agentex/types/agents/schedule_retrieve_response.py">ScheduleRetrieveResponse</a></code>
+- <code title="patch /agents/{agent_id}/schedules/{schedule_id}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">update</a>(schedule_id, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_update_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_update_response.py">ScheduleUpdateResponse</a></code>
 - <code title="get /agents/{agent_id}/schedules">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">list</a>(agent_id, \*\*<a href="src/agentex/types/agents/schedule_list_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_list_response.py">ScheduleListResponse</a></code>
-- <code title="delete /agents/{agent_id}/schedules/{schedule_name}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">delete</a>(schedule_name, \*, agent_id) -> <a href="./src/agentex/types/shared/delete_response.py">DeleteResponse</a></code>
-- <code title="post /agents/{agent_id}/schedules/{schedule_name}/pause">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">pause</a>(schedule_name, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_pause_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_pause_response.py">SchedulePauseResponse</a></code>
-- <code title="post /agents/{agent_id}/schedules/{schedule_name}/trigger">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">trigger</a>(schedule_name, \*, agent_id) -> <a href="./src/agentex/types/agents/schedule_trigger_response.py">ScheduleTriggerResponse</a></code>
-- <code title="post /agents/{agent_id}/schedules/{schedule_name}/unpause">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">unpause</a>(schedule_name, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_unpause_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_unpause_response.py">ScheduleUnpauseResponse</a></code>
+- <code title="delete /agents/{agent_id}/schedules/{schedule_id}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">delete</a>(schedule_id, \*, agent_id) -> <a href="./src/agentex/types/shared/delete_response.py">DeleteResponse</a></code>
+- <code title="delete /agents/{agent_id}/schedules/name/{name}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">delete_by_name</a>(name, \*, agent_id) -> <a href="./src/agentex/types/shared/delete_response.py">DeleteResponse</a></code>
+- <code title="post /agents/{agent_id}/schedules/{schedule_id}/pause">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">pause</a>(schedule_id, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_pause_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_pause_response.py">SchedulePauseResponse</a></code>
+- <code title="post /agents/{agent_id}/schedules/name/{name}/pause">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">pause_by_name</a>(name, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_pause_by_name_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_pause_by_name_response.py">SchedulePauseByNameResponse</a></code>
+- <code title="post /agents/{agent_id}/schedules/{schedule_id}/resume">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">resume</a>(schedule_id, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_resume_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_resume_response.py">ScheduleResumeResponse</a></code>
+- <code title="post /agents/{agent_id}/schedules/name/{name}/resume">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">resume_by_name</a>(name, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_resume_by_name_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_resume_by_name_response.py">ScheduleResumeByNameResponse</a></code>
+- <code title="get /agents/{agent_id}/schedules/name/{name}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">retrieve_by_name</a>(name, \*, agent_id) -> <a href="./src/agentex/types/agents/schedule_retrieve_by_name_response.py">ScheduleRetrieveByNameResponse</a></code>
+- <code title="post /agents/{agent_id}/schedules/{schedule_id}/trigger">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">trigger</a>(schedule_id, \*, agent_id) -> <a href="./src/agentex/types/agents/schedule_trigger_response.py">ScheduleTriggerResponse</a></code>
+- <code title="post /agents/{agent_id}/schedules/name/{name}/trigger">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">trigger_by_name</a>(name, \*, agent_id) -> <a href="./src/agentex/types/agents/schedule_trigger_by_name_response.py">ScheduleTriggerByNameResponse</a></code>
+- <code title="patch /agents/{agent_id}/schedules/name/{name}">client.agents.schedules.<a href="./src/agentex/resources/agents/schedules.py">update_by_name</a>(path_name, \*, agent_id, \*\*<a href="src/agentex/types/agents/schedule_update_by_name_params.py">params</a>) -> <a href="./src/agentex/types/agents/schedule_update_by_name_response.py">ScheduleUpdateByNameResponse</a></code>
 
 # Tasks
 

src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py

@@ -15,6 +15,7 @@
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.core.observability import tracing_metrics_recording as _metrics
 from agentex.lib.environment_variables import EnvironmentVariables
+from agentex.lib.core.tracing.span_error import get_span_error
 from agentex.lib.core.tracing.processors.tracing_processor_interface import (
     SyncTracingProcessor,
     AsyncTracingProcessor,
@@ -83,6 +84,9 @@ def _build_sgp_span(span: Span, env_vars: EnvironmentVariables) -> SGPSpan:
         ),
     )
     sgp_span.start_time = span.start_time.isoformat()  # type: ignore[union-attr]
+    error = get_span_error(span)
+    if error is not None:
+        sgp_span.set_error(error_type=error["type"], error_message=error["message"])
     return sgp_span
 
 

src/agentex/lib/core/tracing/span_error.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agentex.types.span import Span
+
+# Reserved key under ``Span.data`` carrying failure info for a span whose
+# context-manager body raised. Mirrors the existing ``__span_type__`` /
+# ``__source__`` reserved-key convention already read/written by the SGP
+# processor. Stored in ``data`` because the Span model is generated from the
+# OpenAPI spec and has no first-class status/error field; ``data`` is a real
+# field, so it survives ``model_copy(deep=True)`` and round-trips to both the
+# SGP and agentex-native span stores.
+SPAN_ERROR_KEY = "__error__"
+
+
+def set_span_error(span: Span, exc: BaseException) -> None:
+    """Record an exception on ``span`` under ``data[SPAN_ERROR_KEY]``.
+
+    No-op when ``span.data`` is a list (matching ``_add_source_to_span``, which
+    only attaches metadata to dict-shaped data).
+    """
+    error = {"type": type(exc).__name__, "message": str(exc)}
+    if span.data is None:
+        span.data = {}
+    if isinstance(span.data, dict):
+        span.data[SPAN_ERROR_KEY] = error
+
+
+def get_span_error(span: Span) -> dict[str, Any] | None:
+    """Return the error recorded by :func:`set_span_error`, or ``None``."""
+    if isinstance(span.data, dict):
+        value = span.data.get(SPAN_ERROR_KEY)
+        if isinstance(value, dict):
+            return value
+    return None

src/agentex/lib/core/tracing/trace.py

@@ -11,6 +11,7 @@
 from agentex.types.span import Span
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.model_utils import recursive_model_dump
+from agentex.lib.core.tracing.span_error import set_span_error
 from agentex.lib.core.tracing.span_queue import (
     SpanEventType,
     AsyncSpanQueue,
@@ -165,6 +166,9 @@ def span(
         span = self.start_span(name, parent_id, input, data, task_id=task_id)
         try:
             yield span
+        except Exception as exc:
+            set_span_error(span, exc)
+            raise
         finally:
             self.end_span(span)
 
@@ -321,5 +325,8 @@ async def span(
         span = await self.start_span(name, parent_id, input, data, task_id=task_id)
         try:
             yield span
+        except Exception as exc:
+            set_span_error(span, exc)
+            raise
         finally:
             await self.end_span(span)