feat(packaging)!: introduce slim agentex-sdk-client + heavy agentex-sdk split

Stacks on #371 (which moved protocol types to agentex.protocol.*).
Together they enable REST-only consumers to install just the slim
package and use typed protocol types without pulling the full ADK stack.

Two-package layout:

- agentex-sdk-client (slim, root pyproject.toml)
    * 6 deps: httpx, pydantic, typing-extensions, anyio, distro, sniffio
    * Ships agentex/{__init__.py, _*.py, _utils/, types/, resources/,
      protocol/, py.typed}
    * requires-python >= 3.11
    * Stainless-managed
    * Slim wheel excludes src/agentex/lib/**

- agentex-sdk (heavy, adk/pyproject.toml)
    * Depends on agentex-sdk-client>=0.11.4,<0.12 (lockstep, see comment)
    * Plus 31 ADK deps: temporalio, fastapi, redis, MCP, LLM providers,
      observability, CLI surface
    * Ships only agentex/lib/* via hatchling force-include from
      ../src/agentex/lib (lib/ stays at its historical location)
    * requires-python >= 3.12 (lib uses `from typing import override`,
      a 3.12+ stdlib API)
    * Hand-authored overlay; entire adk/ directory must be preserved
      across Stainless codegen via `keep_files: ["adk/**"]`

Existing consumers (`pip install agentex-sdk`) see no change: heavy
depends on slim, so the slim deps install transitively. Both packages
contribute disjoint files to the agentex.* namespace.

Release / publish wiring:

- bin/publish-pypi publishes slim BEFORE heavy. Heavy depends on slim,
  so if the slim publish errors we abort before shipping a broken
  heavy that pins an unreleased slim. (Staff-engineer review fix.)
- bin/check-release-environment validates BOTH PyPI tokens, with the
  legacy PYPI_TOKEN as a back-compat fallback.
- .github/workflows/publish-pypi.yml passes AGENTEX_SDK_CLIENT_PYPI_TOKEN
  and AGENTEX_PYPI_TOKEN to the script.
- release-please-config.json: two-package mode with components
  (agentex-sdk-client at root, agentex-sdk at adk/), and
  include-component-in-tag=true so tags become
  e.g. `agentex-sdk-client-v0.11.4` and `agentex-sdk-v0.11.4`.
- .release-please-manifest.json: seeds adk/ at 0.11.4 so the first
  release produces matched versions.

CI build job runs `rye build --wheel` for both packages; --wheel only
(not sdist) because adk's wheel uses cross-directory force-include
which can't resolve from inside an unpacked sdist tarball.

Tag scheme breakage flagged with `!` in commit/PR title — downstream
tooling that filters by raw `v*` tags will need updates.

Required maintainer follow-ups before this can ship:
- Stainless dashboard: add `adk/**` to keep_files; reduce dashboard
  dep-list to the 6 slim-base deps so codegen doesn't re-add the 31
  ADK deps to root pyproject's `dependencies = [...]`.
- PyPI: claim `agentex-sdk-client` package name; add
  AGENTEX_SDK_CLIENT_PYPI_TOKEN to repo secrets.
- (Defer to a follow-up PR) post-codegen CI guardrail that asserts root
  pyproject's `dependencies = [...]` matches the 6-dep slim set.

Verified locally:
- Both wheels build cleanly via `rye build --wheel`
- Slim ships agentex/protocol/* and excludes agentex/lib/*
- Heavy ships only agentex/lib/* (incl. the back-compat shims from #371)
- Dual install on Python 3.13: from agentex import Agentex AND from
  agentex.protocol.acp import RPCMethod AND from agentex.lib.utils.logging
  import make_logger AND from agentex.lib.types.acp import RPCMethod
  (shim) — all resolve; shim and canonical identity-check as the same
  class objects.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: max-parke-scale

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
           RYE_INSTALL_OPTION: '--yes'
 
       - name: Install dependencies
-        run: rye sync --all-features
+        run: ./scripts/bootstrap
 
       - name: Run lints
         run: ./scripts/lint
@@ -57,10 +57,19 @@ jobs:
           RYE_INSTALL_OPTION: '--yes'
 
       - name: Install dependencies
-        run: rye sync --all-features
+        run: ./scripts/bootstrap
+
+      - name: Run build (slim agentex-sdk-client)
+        # --wheel only: avoid the sdist intermediate step, which would
+        # otherwise force the heavy build below to resolve cross-directory
+        # paths from inside a sdist tarball.
+        run: rye build --wheel
 
-      - name: Run build
-        run: rye build
+      - name: Run build (ADK overlay agentex-sdk)
+        # Heavy wheel uses hatchling force-include to pull
+        # ../src/agentex/lib into agentex/lib. Building --wheel directly
+        # (vs sdist-then-wheel) keeps the relative path resolvable.
+        run: (cd adk && rye build --wheel)
 
       - name: Get GitHub OIDC Token
         if: |-

.github/workflows/publish-pypi.yml

@@ -28,4 +28,11 @@ jobs:
         run: |
           bash ./bin/publish-pypi
         env:
+          # Heavy `agentex-sdk` package token (existing PyPI name).
+          AGENTEX_PYPI_TOKEN: ${{ secrets.AGENTEX_PYPI_TOKEN }}
+          # Slim `agentex-sdk-client` package token (new PyPI name; needs
+          # to be added to repo secrets when the slim is registered).
+          AGENTEX_SDK_CLIENT_PYPI_TOKEN: ${{ secrets.AGENTEX_SDK_CLIENT_PYPI_TOKEN }}
+          # Back-compat fallback — used by bin/publish-pypi when the
+          # dedicated tokens above are unset.
           PYPI_TOKEN: ${{ secrets.AGENTEX_PYPI_TOKEN || secrets.PYPI_TOKEN }}

.release-please-manifest.json

@@ -1,3 +1,4 @@
 {
-  ".": "0.11.4"
+  ".": "0.11.4",
+  "adk": "0.11.4"
 }

adk/README.md

@@ -0,0 +1,32 @@
+# agentex-sdk
+
+The Agent Development Kit (ADK) overlay for the Agentex API.
+
+## What's in here
+
+This package ships everything under `agentex.lib.*`:
+
+- **ACP server** (`agentex.lib.sdk.fastacp`) — FastAPI-based agent control plane.
+- **Temporal workflows** (`agentex.lib.core.temporal`) — durable agent execution.
+- **CLI** (`agentex.lib.cli`) — `agentex init`, `agentex run`, deploy helpers.
+- **LLM provider integrations** (`agentex.lib.adk.providers`, `agentex.lib.core.temporal.plugins`) — OpenAI Agents, Claude Agent SDK, pydantic-ai, langgraph, litellm.
+- **Observability** (`agentex.lib.core.tracing`, `agentex.lib.core.observability`) — SGP, Datadog, OpenTelemetry tracing processors.
+
+## Installation
+
+```sh
+pip install agentex-sdk
+```
+
+This automatically pulls in [`agentex-sdk-client`](../) (the slim Stainless-generated REST client) so `from agentex import Agentex, AsyncAgentex` works the same as before.
+
+## When to use this vs `agentex-sdk-client`
+
+- **`agentex-sdk`** — you're authoring agents. Pulls everything: ACP server, Temporal, MCP, LLM providers, observability, CLI. ~37 deps.
+- **`agentex-sdk-client`** — you only need to call the Agentex REST API. No agent authoring, no Temporal workflows, no FastACP server, no provider integrations. 6 deps.
+
+The two packages contribute disjoint files to the `agentex.*` namespace — `agentex/lib/*` ships only from `agentex-sdk`.
+
+## Repo layout
+
+This package is hand-authored and lives at `adk/` inside [scaleapi/scale-agentex-python](https://github.com/scaleapi/scale-agentex-python). The Stainless generator preserves `adk/**` via `keep_files` so its codegen never touches anything here. The sibling `agentex-sdk-client` package lives at the repo root and IS Stainless-generated.

adk/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+# Hand-authored ADK overlay for agentex. This package contributes only
+# `agentex/lib/*` to the agentex.* namespace; the REST client surface
+# (agentex/{__init__.py, _*.py, types/, resources/}) ships from the slim
+# sibling package `agentex-sdk-client` which is pinned as a runtime dep.
+#
+# This entire `adk/` directory must be preserved across Stainless codegen
+# via `keep_files: ["adk/**"]` in the Stainless dashboard config.
+name = "agentex-sdk"
+version = "0.11.4"
+description = "Agent Development Kit (ADK) overlay for the Agentex API — FastACP server, Temporal workflows, LLM provider integrations, observability"
+license = "Apache-2.0"
+authors = [
+  { name = "Agentex", email = "roxanne.farhad@scale.com" },
+]
+readme = "README.md"
+
+dependencies = [
+    # Lockstep with this package's own version — both are co-released. The
+    # heavy package imports from `agentex.types.*` and `agentex.protocol.*`
+    # which ship from the slim, so a slim bump that drops/renames anything
+    # imported here would silently break heavy. Bump this range whenever the
+    # slim's major/minor changes.
+    "agentex-sdk-client>=0.11.4,<0.12",
+    # CLI surface (agentex.lib.cli.*, agentex.lib.sdk.config.*)
+    "typer>=0.16,<0.17",
+    "questionary>=2.0.1,<3",
+    "rich>=13.9.2,<14",
+    "yaspin>=3.1.0",
+    "pyyaml>=6.0.2,<7",
+    "python-on-whales>=0.73.0,<0.74",
+    "kubernetes>=25.0.0,<36.0.0",
+    "jsonref>=1.1.0,<2",
+    "jsonschema>=4.23.0,<5",
+    "jinja2>=3.1.3,<4",
+    "watchfiles>=0.24.0,<1.0",
+    # ACP server (FastAPI app surface)
+    "fastapi>=0.115.0",
+    "starlette>=0.49.1",
+    "uvicorn>=0.31.1",
+    "aiohttp>=3.10.10,<4",
+    # Temporal workflows
+    "temporalio>=1.26.0,<2",
+    "cloudpickle>=3.1.1",
+    # Async streaming infra
+    "redis>=5.2.0,<8",
+    # LLM provider integrations
+    "litellm>=1.83.7,<2",
+    "openai-agents==0.14.1",
+    "openai>=2.2,<3", # Required by openai-agents; litellm now supports openai 2.x (issue #13711 resolved: https://github.com/BerriAI/litellm/issues/13711)
+    "claude-agent-sdk>=0.1.0",
+    "pydantic-ai-slim>=1.0,<2",
+    "langgraph-checkpoint>=2.0.0",
+    "scale-gp>=0.1.0a59",
+    "scale-gp-beta>=0.2.0",
+    "mcp>=1.4.1",
+    # Observability
+    "ddtrace>=3.13.0",
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "json_log_formatter>=1.1.1",
+]
+
+# agentex/lib/* uses `from typing import override` (3.12+) in 19 files.
+# The slim agentex-sdk-client keeps 3.11 support.
+requires-python = ">= 3.12,<4"
+classifiers = [
+  "Typing :: Typed",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "License :: OSI Approved :: Apache Software License",
+]
+
+[project.urls]
+Homepage = "https://github.com/scaleapi/scale-agentex-python"
+Repository = "https://github.com/scaleapi/scale-agentex-python"
+
+[project.scripts]
+agentex = "agentex.lib.cli.commands.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Ship only agentex/lib/*, pulled in from the parent repo's `src/agentex/lib`
+# tree. The rest of agentex.* (the Stainless-generated client) ships from the
+# sibling agentex-sdk-client package, which this package pins as a runtime dep.
+# Stainless explicitly preserves `src/agentex/lib/` across codegen (per
+# CONTRIBUTING.md), so it's safe to keep the source where it is.
+[tool.hatch.build.targets.wheel]
+bypass-selection = true
+
+[tool.hatch.build.targets.wheel.force-include]
+"../src/agentex/lib" = "agentex/lib"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/pyproject.toml",
+  "/README.md",
+  "/../src/agentex/lib/**",
+]

bin/check-release-environment

@@ -1,9 +1,21 @@
 #!/usr/bin/env bash
 
+# This script is run by Release Doctor to validate the release environment.
+# After the dual-package split (slim agentex-sdk-client + heavy agentex-sdk),
+# both PyPI tokens must be present — one for each package name. If only
+# PYPI_TOKEN is set, fall back to using it for both (back-compat for legacy
+# single-token setups, which forces an account-scoped token).
+
 errors=()
 
-if [ -z "${PYPI_TOKEN}" ]; then
-  errors+=("The PYPI_TOKEN secret has not been set. Please set it in either this repository's secrets or your organization secrets.")
+# Heavy `agentex-sdk` token (existing PyPI name).
+if [ -z "${AGENTEX_PYPI_TOKEN}" ] && [ -z "${PYPI_TOKEN}" ]; then
+  errors+=("The AGENTEX_PYPI_TOKEN secret has not been set (and no fallback PYPI_TOKEN). Add it in repo secrets so the heavy 'agentex-sdk' package can be published.")
+fi
+
+# Slim `agentex-sdk-client` token (new PyPI name).
+if [ -z "${AGENTEX_SDK_CLIENT_PYPI_TOKEN}" ] && [ -z "${PYPI_TOKEN}" ]; then
+  errors+=("The AGENTEX_SDK_CLIENT_PYPI_TOKEN secret has not been set (and no fallback PYPI_TOKEN). Add it in repo secrets so the slim 'agentex-sdk-client' package can be published. Falling back to PYPI_TOKEN requires an account-scoped token.")
 fi
 
 lenErrors=${#errors[@]}

bin/publish-pypi

@@ -1,6 +1,34 @@
 #!/usr/bin/env bash
 
+# Publish both the Stainless-managed slim `agentex-sdk-client` package (built
+# from this repo's root) and the hand-authored `agentex-sdk` ADK overlay
+# (built from adk/). The two packages contribute disjoint files to the same
+# `agentex.*` namespace; `agentex-sdk` pins `agentex-sdk-client` as a runtime
+# dep so installing `agentex-sdk` transitively pulls in the slim client.
+#
+# Publish ORDER matters: slim first, then heavy. Heavy's dep on slim means
+# anyone installing `agentex-sdk` hits resolver failure if slim hasn't shipped
+# yet. Failing the slim publish before the heavy gives us a chance to abort
+# without leaving an inconsistent registry state.
+#
+# Tokens:
+#   - $AGENTEX_SDK_CLIENT_PYPI_TOKEN — auths publishing the slim client
+#   - $AGENTEX_PYPI_TOKEN (alias $PYPI_TOKEN for back-compat) — auths
+#     publishing the heavy ADK overlay (which continues to claim the
+#     `agentex-sdk` name on PyPI)
+
 set -eux
+
+# Slim Stainless-managed client (root) — new `agentex-sdk-client` PyPI name.
 mkdir -p dist
 rye build --clean
-rye publish --yes --token=$PYPI_TOKEN
+rye publish --yes --token="${AGENTEX_SDK_CLIENT_PYPI_TOKEN:-$PYPI_TOKEN}"
+
+# Heavy ADK overlay (adk/) — keeps the existing `agentex-sdk` PyPI name.
+# Pins `agentex-sdk-client` which the previous step just published.
+(
+  cd adk
+  mkdir -p dist
+  rye build --clean
+  rye publish --yes --token="${AGENTEX_PYPI_TOKEN:-$PYPI_TOKEN}"
+)

pyproject.toml

@@ -1,7 +1,15 @@
 [project]
-name = "agentex-sdk"
+# This is the Stainless-generated REST client. The hand-authored ADK
+# overlay (formerly `src/agentex/lib/*`) now lives in `adk/` and ships
+# as the sibling `agentex-sdk` package — see `adk/pyproject.toml`.
+#
+# Stainless dashboard config must:
+#   - Rename `package_name` from `agentex-sdk` to `agentex-sdk-client`
+#   - Reduce the dep list to the 6 bare-client deps below
+#   - Add `adk/**` to `keep_files` so the ADK overlay persists across codegen
+name = "agentex-sdk-client"
 version = "0.11.4"
-description = "The official Python library for the agentex API"
+description = "The official Python REST client for the Agentex API"
 dynamic = ["readme"]
 license = "Apache-2.0"
 authors = [
@@ -15,37 +23,6 @@ dependencies = [
     "anyio>=3.5.0, <5",
     "distro>=1.7.0, <2",
     "sniffio",
-    "typer>=0.16,<0.17",
-    "questionary>=2.0.1,<3",
-    "rich>=13.9.2,<14",
-    "fastapi>=0.115.0",
-    "starlette>=0.49.1",
-    "uvicorn>=0.31.1",
-    "watchfiles>=0.24.0,<1.0",
-    "python-on-whales>=0.73.0,<0.74",
-    "pyyaml>=6.0.2,<7",
-    "jsonschema>=4.23.0,<5",
-    "jsonref>=1.1.0,<2",
-    "temporalio>=1.26.0,<2",
-    "aiohttp>=3.10.10,<4",
-    "redis>=5.2.0,<8",
-    "litellm>=1.83.7,<2",
-    "kubernetes>=25.0.0,<36.0.0",
-    "jinja2>=3.1.3,<4",
-    "mcp>=1.4.1",
-    "scale-gp>=0.1.0a59",
-    "openai-agents==0.14.1",
-    "pydantic-ai-slim>=1.0,<2",
-    "json_log_formatter>=1.1.1",
-    "scale-gp-beta>=0.2.0",
-    "openai>=2.2,<3", # Required by openai-agents; litellm now supports openai 2.x (issue #13711 resolved: https://github.com/BerriAI/litellm/issues/13711)
-    "cloudpickle>=3.1.1",
-    "ddtrace>=3.13.0",
-    "yaspin>=3.1.0",
-    "claude-agent-sdk>=0.1.0",
-    "langgraph-checkpoint>=2.0.0",
-    "opentelemetry-sdk>=1.20.0",
-    "opentelemetry-api>=1.20.0",
 ]
 
 requires-python = ">= 3.11,<4"
@@ -75,8 +52,14 @@ dev = [
     "ruff>=0.3.4",
 ]
 
-[project.scripts]
-agentex = "agentex.lib.cli.commands.main:app"
+# The `agentex` CLI entry point ships from the ADK package — see
+# `adk/pyproject.toml`. The slim client has no CLI surface.
+
+[tool.rye.workspace]
+# `rye sync` from the root installs both this slim package and the ADK
+# overlay editably. `src/agentex/lib/` is shared source: the slim wheel
+# excludes it; the heavy wheel includes it via hatchling force-include.
+members = ["adk"]
 
 [tool.rye]
 managed = true
@@ -144,13 +127,11 @@ include = [
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/agentex"]
-# Don't ship internal test files in the wheel. `lib/cli/templates/**/test_agent.py.j2`
-# is intentionally kept — those render into user projects.
+# agentex/lib/* ships from the sibling agentex-sdk package (see adk/pyproject.toml).
+# Excluding it here keeps the slim wheel disjoint from the heavy wheel so both
+# can install into the same site-packages/agentex/ without file conflicts.
 exclude = [
-  "src/agentex/lib/**/tests/**",
-  "src/agentex/lib/**/test_*.py",
-  "src/agentex/lib/**/conftest.py",
-  "src/agentex/lib/**/pytest.ini",
+  "src/agentex/lib/**",
 ]
 
 [tool.hatch.build.targets.sdist]

release-please-config.json

@@ -1,10 +1,15 @@
 {
   "packages": {
-    ".": {}
+    ".": {
+      "component": "agentex-sdk-client"
+    },
+    "adk": {
+      "component": "agentex-sdk"
+    }
   },
   "$schema": "https://raw.githubusercontent.com/stainless-api/release-please/main/schemas/config.json",
   "include-v-in-tag": true,
-  "include-component-in-tag": false,
+  "include-component-in-tag": true,
   "versioning": "prerelease",
   "prerelease": true,
   "bump-minor-pre-major": true,

tests/test_function_tool.py

@@ -6,7 +6,7 @@
 import pytest
 from pydantic import ValidationError
 
-from src.agentex.lib.core.temporal.activities.adk.providers.openai_activities import (  # type: ignore[import-untyped]
+from agentex.lib.core.temporal.activities.adk.providers.openai_activities import (
     FunctionTool,
 )