Merge branch 'next' into maxparke/agx1-418-build-provenance-capture

Author: max-parke-scale

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
   lint:
     timeout-minutes: 10
     name: lint
-    runs-on: ${{ github.repository == 'stainless-sdks/agentex-sdk-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -44,7 +44,7 @@ jobs:
     permissions:
       contents: read
       id-token: write
-    runs-on: ${{ github.repository == 'stainless-sdks/agentex-sdk-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
@@ -87,7 +87,7 @@ jobs:
   test:
     timeout-minutes: 10
     name: test
-    runs-on: ${{ github.repository == 'stainless-sdks/agentex-sdk-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    runs-on: ${{ startsWith(github.repository, 'stainless-sdks/') && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

.release-please-manifest.json

@@ -1,4 +1,4 @@
 {
-  ".": "0.18.0",
-  "adk": "0.18.0"
+  ".": "0.20.0",
+  "adk": "0.20.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 74
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-f3f1b47fa785a0d7b4e1cce1932a2ab0c0b6531d67d499e6188292ea2a00c9d8.yml
-openapi_spec_hash: 77044dc5774eb88f1541ebbe53b413a7
-config_hash: 5c4e326f797c879e72d6bf32fc1ea49d
+configured_endpoints: 75
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-644a4ec06aa1f055c614cbef3379684819a4edd84eeb20d2fb29ae01663622a3.yml
+openapi_spec_hash: a6a4dc0c09691ac9783bf38e9653a464
+config_hash: 593e89b291976a5e84e4c3c3f8324354

CHANGELOG.md

@@ -12,6 +12,30 @@
 
 * **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.20.0 (2026-07-16)
+
+Full Changelog: [agentex-client-v0.19.0...agentex-client-v0.20.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.19.0...agentex-client-v0.20.0)
+
+### Features
+
+* **api:** add interrupt task ([936a2b1](https://github.com/scaleapi/scale-agentex-python/commit/936a2b1d28a5409bd7548d59b0f18491495c805b))
+* **api:** add task/interrupt method and INTERRUPTED status to agents/tasks ([4f1c093](https://github.com/scaleapi/scale-agentex-python/commit/4f1c09348c2ddffeb8c78738fb9b7aa14ed4b752))
+* **interrupt:** task/interrupt hook + protocol + resume-safe session capture (AGX1-391) ([#462](https://github.com/scaleapi/scale-agentex-python/issues/462)) ([eaa3dd5](https://github.com/scaleapi/scale-agentex-python/commit/eaa3dd526b88c454fc604d0e617f7191b66952bb))
+
+## 0.19.0 (2026-07-14)
+
+Full Changelog: [agentex-client-v0.18.0...agentex-client-v0.19.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.18.0...agentex-client-v0.19.0)
+
+### Features
+
+* **tracing:** emit token usage on spans for SGP billing ([#458](https://github.com/scaleapi/scale-agentex-python/issues/458)) ([7d19ada](https://github.com/scaleapi/scale-agentex-python/commit/7d19ada2db5d1eca5268a10fe04dfc85a367cf7f))
+
+
+### Bug Fixes
+
+* **internal:** resolve build failures ([9245b70](https://github.com/scaleapi/scale-agentex-python/commit/9245b700ceee95be9a0c478e518d9c06228d4b9f))
+* **tracing:** capture span body exceptions and export SGP status=ERROR ([#460](https://github.com/scaleapi/scale-agentex-python/issues/460)) ([6c23d76](https://github.com/scaleapi/scale-agentex-python/commit/6c23d7625ccf58ac9793dcf5219e4f7f4de38353))
+
 ## 0.18.0 (2026-07-10)
 
 Full Changelog: [agentex-client-v0.17.0...agentex-client-v0.18.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.17.0...agentex-client-v0.18.0)

adk/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.20.0 (2026-07-16)
+
+Full Changelog: [agentex-sdk-v0.19.0...agentex-sdk-v0.20.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.19.0...agentex-sdk-v0.20.0)
+
+### Chores
+
+* **agentex-sdk:** Synchronize agentex versions
+
+## 0.19.0 (2026-07-14)
+
+Full Changelog: [agentex-sdk-v0.18.0...agentex-sdk-v0.19.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.18.0...agentex-sdk-v0.19.0)
+
+### Chores
+
+* **agentex-sdk:** Synchronize agentex versions
+
 ## 0.18.0 (2026-07-10)
 
 Full Changelog: [agentex-sdk-v0.17.0...agentex-sdk-v0.18.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.17.0...agentex-sdk-v0.18.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.18.0"
+version = "0.20.0"
 description = "Agent Development Kit (ADK) overlay for the Agentex API — FastACP server, Temporal workflows, LLM provider integrations, observability"
 license = "Apache-2.0"
 authors = [

api.md

@@ -126,6 +126,7 @@ Methods:
 - <code title="post /tasks/{task_id}/complete">client.tasks.<a href="./src/agentex/resources/tasks.py">complete</a>(task_id, \*\*<a href="src/agentex/types/task_complete_params.py">params</a>) -> <a href="./src/agentex/types/task.py">Task</a></code>
 - <code title="delete /tasks/name/{task_name}">client.tasks.<a href="./src/agentex/resources/tasks.py">delete_by_name</a>(task_name) -> <a href="./src/agentex/types/shared/delete_response.py">DeleteResponse</a></code>
 - <code title="post /tasks/{task_id}/fail">client.tasks.<a href="./src/agentex/resources/tasks.py">fail</a>(task_id, \*\*<a href="src/agentex/types/task_fail_params.py">params</a>) -> <a href="./src/agentex/types/task.py">Task</a></code>
+- <code title="post /tasks/{task_id}/interrupt">client.tasks.<a href="./src/agentex/resources/tasks.py">interrupt</a>(task_id, \*\*<a href="src/agentex/types/task_interrupt_params.py">params</a>) -> <a href="./src/agentex/types/task.py">Task</a></code>
 - <code title="get /tasks/{task_id}/query/{query_name}">client.tasks.<a href="./src/agentex/resources/tasks.py">query_workflow</a>(query_name, \*, task_id) -> <a href="./src/agentex/types/task_query_workflow_response.py">TaskQueryWorkflowResponse</a></code>
 - <code title="get /tasks/name/{task_name}">client.tasks.<a href="./src/agentex/resources/tasks.py">retrieve_by_name</a>(task_name, \*\*<a href="src/agentex/types/task_retrieve_by_name_params.py">params</a>) -> <a href="./src/agentex/types/task_retrieve_by_name_response.py">TaskRetrieveByNameResponse</a></code>
 - <code title="get /tasks/{task_id}/stream">client.tasks.<a href="./src/agentex/resources/tasks.py">stream_events</a>(task_id) -> object</code>

examples/tutorials/10_async/00_base/030_tracing/README.md

@@ -41,6 +41,39 @@ await adk.tracing.end_span(
 
 Spans create a hierarchical view of agent execution, making it easy to see which operations take time and where errors occur.
 
+## Token Usage & Cost Tracking
+
+Token usage on spans is what the backend bills from, and it reads two shapes:
+
+- **Per-turn aggregate** — `span.data["usage"]` + `span.data["cost_usd"]`. Emit at most
+  once per turn, holding that turn's own usage (not a session-cumulative total). When a
+  trace has an aggregate, the backend keeps it and de-dups all per-call spans against it.
+- **Per-call detail** — `span.output["usage"]`. Optional; the SDK's LLM adapters
+  (litellm, OpenAI Agents SDK, LangGraph) emit this automatically. Summed only when no
+  aggregate exists in the trace.
+
+Record the turn rollup with `adk.tracing.turn_span()` instead of hand-writing usage keys.
+It accepts the harness `TurnUsage` that every turn adapter reports (`LangGraphTurn.usage()`,
+`run_turn(...).usage`, `ClaudeCodeTurn.usage()`, ...), cost included:
+
+```python
+async with adk.tracing.turn_span(
+    trace_id=task.id,
+    name="turn",
+    input={"prompt": prompt},
+    task_id=task.id,
+) as turn:
+    result = await run_turn(...)
+    turn.output = {"response": result.final_output}
+    turn.record_usage(result.usage)  # TurnUsage; cost_usd stamped automatically
+```
+
+**Never put usage on both a rollup span's `output` and its per-call children's
+`output`** — that double-counts. `turn_span` writes the aggregate to `data`, so child
+spans stay safe to emit. Recognized token keys: `input_tokens`/`prompt_tokens`,
+`output_tokens`/`completion_tokens`, `cached_input_tokens`/`cached_tokens`,
+`reasoning_tokens`; cost is `cost_usd`.
+
 ## When to Use
 - Debugging complex agent behaviors
 - Performance optimization and bottleneck identification

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.18.0"
+version = "0.20.0"
 description = "The official Python REST client for the Agentex API"
 dynamic = ["readme"]
 license = "Apache-2.0"

scripts/lint

@@ -13,7 +13,7 @@ else
 fi
 
 echo "==> Running pyright"
-uv run pyright
+uv run pyright -p .
 
 echo "==> Making sure it imports"
 uv run python -c 'import agentex'