agents

Agent framework adapters

These packages run agents built with popular agent frameworks as durable Dex agent sessions. One Flow run is one session. The session runs in Step mode: every model call is one Dex Step and every tool call is its own Step, with tool calls running in parallel, so a crash repeats at most the one call that was running and never repeats a write silently. The plan is agent-framework-adapters.md.

Each language has a core package with the shared session Flow and one adapter package per framework. Every package has its own manifest and lockfile and depends on the released Dex SDK from the public registry. Inside this repository an adapter depends on its language core by path; the published adapter depends on the published core instead.

Package	Distribution	Framework
python/core	dex-agents (dex_agents)	Shared session Flow, the built-in agent loop (dex_agents.builtin_loop), the LiteLLM model client (dex_agents.litellm, extra dex-agents[litellm]), connector tools (dex_agents.connectors, extra dex-agents[connectors]), and dex_agents.testing
python/openai-agents	dex-agents-openai-agents	OpenAI Agents SDK
python/pydantic-ai	dex-agents-pydantic-ai	Pydantic AI
python/langgraph	dex-agents-langgraph	LangChain create_agent and LangGraph
python/google-adk	dex-agents-google-adk	Google ADK
python/claude-agent-sdk	dex-agents-claude-agent-sdk	Claude Agent SDK
cli/python/core	dex-agents-cli-core (dex_agents_cli_core), not published yet	Shared core of the Python CLI commands: configuration, dexcli dev, connector and local tools, terminal chat
cli/python/claude-sdk	dex-agents-claude-sdk-cli, not published yet	The dex-agents-claude-sdk command: a Claude Agent SDK agent in the terminal
cli/python/openai-sdk	dex-agents-openai-sdk-cli, not published yet	The dex-agents-openai-sdk command: an OpenAI Agents SDK agent in the terminal
cli/python/pydantic-ai	dex-agents-pydantic-ai-cli, not published yet	The dex-agents-pydantic-ai command: a Pydantic AI agent in the terminal
cli/python/deepagents	dex-agents-deepagents-cli, not published yet	The dex-agents-deepagents command: a Deep Agents agent on the LangGraph adapter in the terminal
cli/python/google-adk	dex-agents-google-adk-cli, not published yet	The dex-agents-google-adk command: a Google ADK agent in the terminal
cli/python/builtin	dex-agents-builtin-cli, not published yet	The dex-agents-builtin command: the Dex built-in agent loop on LiteLLM in the terminal
cli/python/testing	dex-agents-cli-testing, never published	Test support of the Python commands: model API stubs, fixtures, and shared terminal scenarios
typescript/core	@superdurable/dex-agents	Shared session Flow, the built-in agent loop (/builtin-loop), the AI SDK model client (/ai-sdk, optional peer ai), connector tools (/connectors, optional peer @superdurable/connectors-sdk), and /testing
go/core	github.com/superdurable/dex/agents/go/core (package dexagents), not tagged yet	Shared session Flow, the built-in agent loop (builtinloop), the OpenAI and Anthropic model clients (openaimodel, anthropicmodel), and agentstest
typescript/vercel-ai	@superdurable/dex-agents-vercel-ai	Vercel AI SDK
typescript/openai-agents	@superdurable/dex-agents-openai-agents	OpenAI Agents SDK
typescript/mastra	@superdurable/dex-agents-mastra	Mastra
typescript/claude-agent-sdk	@superdurable/dex-agents-claude-agent-sdk	Claude Agent SDK
cli/typescript/core	@superdurable/dex-agents-cli-core, not published yet	Shared core of the TypeScript CLI commands: configuration, dexcli dev, connector and local tools, terminal chat
cli/typescript/claude-sdk	@superdurable/dex-agents-claude-sdk-cli, not published yet	The dex-agents-claude-sdk command: a Claude Agent SDK agent in the terminal
cli/typescript/openai-sdk	@superdurable/dex-agents-openai-sdk-cli, not published yet	The dex-agents-openai-sdk command: an OpenAI Agents SDK agent in the terminal
cli/typescript/vercel-ai	@superdurable/dex-agents-vercel-ai-cli, not published yet	The dex-agents-vercel-ai command: a Vercel AI SDK agent in the terminal
cli/typescript/mastra	@superdurable/dex-agents-mastra-cli, not published yet	The dex-agents-mastra command: a Mastra agent in the terminal
cli/typescript/builtin	@superdurable/dex-agents-builtin-cli, not published yet	The dex-agents-builtin command: the Dex built-in agent loop without a framework in the terminal
typescript/pi	@superdurable/dex-agents-pi, not published yet	Pi: pi-ai models and Pi tools on the built-in agent loop, so Dex runs the loop, not Pi
cli/typescript/pi	@superdurable/dex-agents-pi-cli, not published yet	The dex-agents-pi command: a Pi coding agent in the terminal

UI streams

Both cores ship UI stream adapters, so a browser can render a live session from its AgentEvents Stream and resume after a reconnect with no store besides Dex. @superdurable/dex-agents/ui-stream serves an AI SDK UI message stream for useChat, with reset-step for a retried model call and tool approvals through tool-approval-request and tool-approval-response. Both @superdurable/dex-agents/ui-stream and dex_agents.ui_stream serve plain Server-Sent Events whose id is the Dex resume token, so an EventSource resumes through Last-Event-ID, and a snapshot to load on every connection. See the TypeScript core and the Python core.

Installation

Agents without a framework use the built-in agent loop in the core package. Install the core with the LiteLLM model client:

pip install 'dex-agents[litellm]'

New features ship as modules of the existing packages. A dependency that only one module needs is an extra, such as dex-agents[litellm], so no new package name is registered.

Install an adapter with its framework. The Python adapter brings in dex-agents and the Dex SDK it supports:

pip install dex-agents-pydantic-ai

On npm, the core and the Dex SDK are peer dependencies, so the application owns exactly one copy of each and errors such as ToolExecutionError keep one identity. Install them next to the adapter:

npm i @superdurable/dex-agents-vercel-ai @superdurable/dex-agents @superdurable/dex ai zod

Versions and compatibility

All twenty-six published packages share one version line, starting at 0.1.0. It is independent of the Dex SDK versions and of the Dex Skills: frameworks move faster than Dex, and the adapter API is still before 1.0, so a minor release may change it. One release publishes the whole family under one tag, agents/v<version>. Each package pins the Dex SDK it supports and keeps the framework range it was tested against.

Agents version	Dex SDK	Package	Framework range	Tested with
0.1.0	dex-python-sdk==1.30.0	dex-agents-openai-agents	openai-agents>=0.24,<0.25	0.24.0
0.1.0	dex-python-sdk==1.30.0	dex-agents-pydantic-ai	pydantic-ai-slim>=2.64,<3	2.64.0
0.1.0	dex-python-sdk==1.30.0	dex-agents-langgraph	langchain>=1.4.7,<2, langchain-core>=1.7.3,<2, langgraph>=1.2.19,<2	1.4.7, 1.7.3, 1.2.19
0.1.0	dex-python-sdk==1.30.0	dex-agents-google-adk	google-adk>=2.13,<3	2.13.0
0.1.0	dex-python-sdk==1.30.0	dex-agents-claude-agent-sdk	claude-agent-sdk>=0.2.176,<0.3	0.2.176
0.1.0	@superdurable/dex@1.30.0	@superdurable/dex-agents-vercel-ai	ai@^7.0.159	7.0.159
0.1.0	@superdurable/dex@1.30.0	@superdurable/dex-agents-openai-agents	@openai/agents@^0.21.0	0.21.0
0.1.0	@superdurable/dex@1.30.0	@superdurable/dex-agents-mastra	@mastra/core@^1.81.0	1.81.0
0.1.0	@superdurable/dex@1.30.0	@superdurable/dex-agents-claude-agent-sdk	@anthropic-ai/claude-agent-sdk@^0.3.316	0.3.316
0.2.0	dex-python-sdk==1.35.0	dex-agents-openai-agents	openai-agents>=0.24,<0.25	0.24.0
0.2.0	dex-python-sdk==1.35.0	dex-agents-pydantic-ai	pydantic-ai-slim>=2.64,<3	2.64.0
0.2.0	dex-python-sdk==1.35.0	dex-agents-langgraph	langchain>=1.4.7,<2, langchain-core>=1.7.3,<2, langgraph>=1.2.19,<2	1.4.7, 1.7.3, 1.2.19
0.2.0	dex-python-sdk==1.35.0	dex-agents-google-adk	google-adk>=2.13,<3	2.13.0
0.2.0	dex-python-sdk==1.35.0	dex-agents-claude-agent-sdk	claude-agent-sdk>=0.2.176,<0.3	0.2.176
0.2.0	@superdurable/dex@1.35.0	@superdurable/dex-agents-vercel-ai	ai@^7.0.159	7.0.159
0.2.0	@superdurable/dex@1.35.0	@superdurable/dex-agents-openai-agents	@openai/agents@^0.21.0	0.21.0
0.2.0	@superdurable/dex@1.35.0	@superdurable/dex-agents-mastra	@mastra/core@^1.81.0	1.81.0
0.2.0	@superdurable/dex@1.35.0	@superdurable/dex-agents-claude-agent-sdk	@anthropic-ai/claude-agent-sdk@^0.3.316	0.3.316
0.3.0	dex-python-sdk==1.38.0	dex-agents-openai-agents	openai-agents>=0.24,<0.25	0.24.0
0.3.0	dex-python-sdk==1.38.0	dex-agents-pydantic-ai	pydantic-ai-slim>=2.64,<3	2.64.0
0.3.0	dex-python-sdk==1.38.0	dex-agents-langgraph	langchain>=1.4.7,<2, langchain-core>=1.7.3,<2, langgraph>=1.2.19,<2	1.4.7, 1.7.3, 1.2.19
0.3.0	dex-python-sdk==1.38.0	dex-agents-google-adk	google-adk>=2.13,<3	2.13.0
0.3.0	dex-python-sdk==1.38.0	dex-agents-claude-agent-sdk	claude-agent-sdk>=0.2.176,<0.3	0.2.176
0.3.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-vercel-ai	ai@^7.0.159	7.0.159
0.3.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-openai-agents	@openai/agents@^0.21.0	0.21.0
0.3.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-mastra	@mastra/core@^1.81.0	1.81.0
0.3.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-claude-agent-sdk	@anthropic-ai/claude-agent-sdk@^0.3.316	0.3.316
0.4.0	dex-python-sdk==1.38.0	dex-agents-openai-agents	openai-agents>=0.24,<0.25	0.24.0
0.4.0	dex-python-sdk==1.38.0	dex-agents-pydantic-ai	pydantic-ai-slim>=2.64,<3	2.64.0
0.4.0	dex-python-sdk==1.38.0	dex-agents-langgraph	langchain>=1.4.7,<2, langchain-core>=1.7.3,<2, langgraph>=1.2.19,<2	1.4.7, 1.7.3, 1.2.19
0.4.0	dex-python-sdk==1.38.0	dex-agents-google-adk	google-adk>=2.13,<3	2.13.0
0.4.0	dex-python-sdk==1.38.0	dex-agents-claude-agent-sdk	claude-agent-sdk>=0.2.176,<0.3	0.2.176
0.4.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-vercel-ai	ai@^7.0.159	7.0.159
0.4.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-openai-agents	@openai/agents@^0.21.0	0.21.0
0.4.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-mastra	@mastra/core@^1.81.0	1.81.0
0.4.0	@superdurable/dex@1.38.0	@superdurable/dex-agents-claude-agent-sdk	@anthropic-ai/claude-agent-sdk@^0.3.316	0.3.316
0.5.0	dex-python-sdk==1.45.0	dex-agents-openai-agents	openai-agents>=0.24,<0.25	0.24.0
0.5.0	dex-python-sdk==1.45.0	dex-agents-pydantic-ai	pydantic-ai-slim>=2.64,<3	2.64.0
0.5.0	dex-python-sdk==1.45.0	dex-agents-langgraph	langchain>=1.4.7,<2, langchain-core>=1.7.3,<2, langgraph>=1.2.19,<2	1.4.7, 1.7.3, 1.2.19
0.5.0	dex-python-sdk==1.45.0	dex-agents-google-adk	google-adk>=2.13,<3	2.13.0
0.5.0	dex-python-sdk==1.45.0	dex-agents-claude-agent-sdk	claude-agent-sdk>=0.2.176,<0.3	0.2.176
0.5.0	@superdurable/dex@1.45.0	@superdurable/dex-agents-vercel-ai	ai@^7.0.159	7.0.159
0.5.0	@superdurable/dex@1.45.0	@superdurable/dex-agents-openai-agents	@openai/agents@^0.21.0	0.21.0
0.5.0	@superdurable/dex@1.45.0	@superdurable/dex-agents-mastra	@mastra/core@^1.81.0	1.81.0
0.5.0	@superdurable/dex@1.45.0	@superdurable/dex-agents-claude-agent-sdk	@anthropic-ai/claude-agent-sdk@^0.3.316	0.3.316
0.5.0	@superdurable/dex@1.45.0	@superdurable/dex-agents-pi	@earendil-works/pi-ai@^1.5.1	1.5.1

A Python adapter requires dex-agents==<same version>. An npm adapter peer-depends on @superdurable/dex-agents@^<same version>. Add a row for every release. Changes are listed in CHANGELOG.md.

0.2.0 uses Dex SDK v1.35.0 in every language, including the Go core (github.com/superdurable/dex/sdk-go v1.35.0). That SDK needs a Dex Server with protocol 4: server-zd v0.1.17 or later. Upgrade the server before the Workers.

0.3.0 (released 2026-11-09 as agents/v0.3.0) and 0.4.0 (released 2026-11-10 as agents/v0.4.0) use Dex SDK v1.38.0 in every language, including the Go core (github.com/superdurable/dex/sdk-go v1.38.0). That SDK also needs a Dex Server with protocol 4: server-zd v0.1.17 or later. Upgrade the server before the Workers.

0.5.0 uses Dex SDK v1.45.0 in every language, including the Go core (github.com/superdurable/dex/sdk-go v1.45.0). Before upgrading, read the breaking changes of SDK 1.43 and 1.45 in the SDK change logs. That SDK also needs a Dex Server with protocol 4: server-zd v0.1.17 or later.

Releases

Publishing a GitHub Release with the tag agents/v<version> from a commit on main publishes all twenty-six packages in dependency order: the core, the adapters, the CLI core, then the CLI commands. dex-agents-cli-testing is never published. agents-python-publish.yml uploads to PyPI and agents-typescript-publish.yml uploads to npm with provenance, both through trusted publishing. A prerelease version such as 0.2.0-rc.1 gets the npm dist-tag next. Running either workflow by hand stamps, builds, and smoke-tests without uploading unless publish is selected. A run that uploads starts from main or from the release tag agents/v<version> on main. Release changed components releases the family when agents/** changed and its agents_version input is set. It creates the tag, then runs both workflows on that tag, so they publish the released commit even if main has moved on.

Both workflows stamp the release version first with script/stamp_agents_release_version.py. It sets one version in all fourteen pyproject.toml files (the thirteen published ones and dex-agents-cli-testing) and thirteen package.json files, their lockfiles, and every constraint between agents packages: the adapters' on their core, and the CLI packages' on the core, their adapter, and the CLI core. Python pins ==<version>; npm peer-depends on ^<version>. Run it locally to bump the committed version, and pass --check to verify it.

script/smoke-test-built-packages.sh builds every package with uv build and npm pack, checks the artifacts, and installs them into fresh projects without path dependencies: the core first, then each adapter. It imports every TypeScript core subpath with and without the optional peer ai. It then runs one Pydantic AI session and one Vercel AI SDK session against dexcli dev --engine zd with a scripted model, using the adapters' own test fixtures. Last, it installs the CLI core and each CLI command from the built artifacts alone and runs each command's --help and init --yes with a scratch HOME; neither needs a model key or a Dex server. Agents CI runs it on every change, so packaging regressions fail CI:

DEXCLI=/path/to/dexcli agents/script/smoke-test-built-packages.sh all

Splitting a release across PyPI's new-project limit

PyPI accepts only about five new projects per day. A release that publishes more new PyPI names than that uploads in two runs. The first release of the CLI packages has seven new names: dex-agents-cli-core and six commands.

The PyPI workflow's skip_packages input leaves CLI command distributions out of one upload. It accepts only command names, because nothing else in the release depends on a command. It always builds and smoke-tests all thirteen distributions. A later run skips every file PyPI already has. Do not publish such a release by hand from the GitHub Releases page: the release event has no skip input and would upload all seven new names.

1. Day 1: run Release changed components from main with all three inputs. version is its required shared version for the other changed components, the next Dex release version, such as 1.45.0. agents_version is the agents version, such as 0.5.0. agents_python_skip_packages names the last two commands. It creates the Release, publishes every npm package, and uploads every other PyPI distribution:

   gh workflow run release-changed-components.yml --ref main \
     -f version=1.45.0 -f agents_version=0.5.0 \
     -f agents_python_skip_packages="dex-agents-google-adk-cli dex-agents-builtin-cli"

2. Day 2: run Publish agents Python packages to PyPI on the release tag, so it builds the released commit, with publish selected and skip_packages empty. It uploads the two skipped commands:

   gh workflow run agents-python-publish.yml --ref agents/v0.5.0 \
     -f version=0.5.0 -f publish=true

Each new name needs its PyPI pending trusted publisher before the run that uploads it.

Adding a package

1. Create agents/<language>/<package>/ with its manifest, lockfile, README, LICENSE, and tests. Python packages use uv 0.12.2, require dex-agents==<version>, and resolve it locally with dex-agents = { path = "../core", editable = true } in [tool.uv.sources]. npm packages list @superdurable/dex-agents as a ^<version> peer dependency and as a file:../core devDependency, with install-links=true in their .npmrc so the local core is copied, not linked.
2. Implement the runner contract in the Python core README.
3. Test against a real Dex Server with the core's testing utilities and a scripted model, so no model key is needed. Cover the plan's test matrix.
4. Add an executable ci.sh that installs locked dependencies, runs lint and type checks, and runs the integration tests. It reads DEXCLI, the dexcli executable; dex-server-zd sits in the same directory.

Agents CI finds every executable agents/*/*/ci.sh and runs each in its own job, so a new package needs no workflow change. Add a new package to the package lists in the stamping script, the smoke test, both publish workflows, and the tables above, in dependency order. In the scripts, the package in agents/cli/<language>/<name> is cli/<name>. A new package name needs its trusted publishing set up on PyPI or npm before the first release that publishes it. Source files use the Sustainable Use License header; make copyright-check verifies it.