Claude Agent SDK (Python)

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

dynamoprotocol-claude-agent-sdk adds Dynamo to Anthropic's Claude Agent SDK for Python. Every agent run and every sub-agent it launches gets its own capped slice of one budget. A run's budget is reserved before the run starts, and the CLI's own hard budget is set to that reservation. A sub-agent the slice or the mandate does not allow is refused before it launches.

The plugin is not published. It installs from a clone of the repository.

Install and try it

These are the commands from the plugin README. They boot a local core in Control Mode, build a venv from the hash-checked locks/test.txt and run the offline containment demo on a scripted stand-in for the Claude Code CLI: no CLI process starts, no provider key, no model called. You need Node 22.12 or later, pnpm 9, curl, openssl and Python 3.11 (set PYTHON=python3.11 if python3 is another version). Set DYNAMO_REPO to your clone.

cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter @dynamo/core-host... -r build
export DYNAMO_OWNER_TOKEN="dp-local-owner-$(openssl rand -hex 16)"
export DYNAMO_CORE_URL="http://127.0.0.1:${DYNAMO_CORE_PORT:-8790}"
[ -s .dynamo-local.key ] || (umask 077 && openssl rand -hex 32 > .dynamo-local.key)
export CORE_KEY_ENCRYPTION_KEY="$(cat .dynamo-local.key)"
OWNER_API_TOKEN="$DYNAMO_OWNER_TOKEN" PLUGIN_WIRE_TOKEN="dp-local-wire-$(openssl rand -hex 16)" \
  OWNER_API_PORT="${DYNAMO_CORE_PORT:-8790}" CORE_DB="$PWD/.dynamo-local/core" CORE_LOG=off \
  CORE_RATE_LIMIT_RPS=200 CORE_RATE_LIMIT_BURST=400 \
  node deploy/image/entry.mjs > .dynamo-local.log 2>&1 &
CORE_PID=$!
trap 'kill "$CORE_PID"' EXIT
"${PYTHON:-python3}" -m venv .venv-claude
PIP_ONLY_BINARY=":all:" .venv-claude/bin/pip install --quiet --require-hashes -r packages/plugin-claude-agent-sdk/locks/test.txt
.venv-claude/bin/pip install --quiet --no-deps ./packages/sdk-python ./packages/plugin-claude-agent-sdk
for _ in $(seq 150); do curl -fsS "$DYNAMO_CORE_URL/healthz" > /dev/null 2>&1 && break; sleep 0.2; done
kill -0 "$CORE_PID" 2>/dev/null && curl -fsS "$DYNAMO_CORE_URL/healthz" > /dev/null || tail -n 20 .dynamo-local.log
.venv-claude/bin/python packages/plugin-claude-agent-sdk/examples/containment/run.py
kill "$CORE_PID"; trap - EXIT

The last line stops the core.

Wrap an agent run in a budget

This is packages/plugin-claude-agent-sdk/examples/app/with_dynamo.py: a lead agent with a research sub-agent, with Dynamo added. No test runs this file; make test-plugin-claude-agent-sdk tests the plugin itself (the shared spawn-scoped conformance scenarios against a local core).

# SPDX-License-Identifier: Apache-2.0
"""A lead agent with a research sub-agent on the Claude Agent SDK — with Dynamo.

Runs offline: a scripted stand-in for the Claude Code CLI replaces the real one.
"""

import asyncio

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage

from dynamoprotocol_claude_agent_sdk import AgentConfig, DynamoClaude, usd
from dynamoprotocol_claude_agent_sdk.testing import ScriptedCLI, Spawn, Text

cli = ScriptedCLI(entry="lead")
cli.script("lead", Spawn("researcher"), Text("brief written"))
cli.script("researcher", Text("three sources found"))
options = ClaudeAgentOptions(
    agents={"researcher": AgentDefinition(description="Finds sources.", prompt="You research.")},
    max_turns=8,
)


async def main():
    dyn = await DynamoClaude.connect(
        cap=usd("5"), mandate={"categories": ["research", "review"], "maxDepth": 2}, transport_factory=cli.transport,
        agents={"lead": AgentConfig(usd("5"), "review"), "researcher": AgentConfig(usd("1"), "research")},
        run_budgets={"lead": usd("0.50"), "researcher": usd("0.20")},
    )
    async for message in dyn.query("lead", prompt="Write a brief on grid-scale storage", options=options):
        if isinstance(message, ResultMessage):
            print(message.result, message.total_cost_usd)
    await dyn.close()


asyncio.run(main())

your own app, leave it out: the SDK then starts the Claude Code CLI as usual.

converts a decimal string).

Set DYNAMO_CORE_URL and DYNAMO_OWNER_TOKEN for your core.

What a refusal looks like

A refusal raises DynamoCapExceeded, DynamoMandateRefused, DynamoRevoked, DynamoFrozen, DynamoStopped, DynamoApprovalPending, DynamoApprovalDenied, DynamoAmendmentRefused or DynamoPermissionModeUnsafe, all subclasses of the SDK's ClaudeSDKError. A refusal during a run is raised after the run is settled; its result attribute holds the ResultMessage.

A run that would start in bypassPermissions mode is refused with DynamoPermissionModeUnsafe (reason permission_mode_unsafe) before anything is reserved or launched.

Funding modes

always a Control Mode budget: every check runs and no money moves. The quickstart and every test of this plugin use one.

budget by id (budget_id=). The plugin does not refuse it, but no test runs the plugin on one. In those modes the core requires signed hops by default, and a sub-agent's slice opened without its delegator's signature is refused hop_unsigned. Pass hops= (a LayerHops from dynamoprotocol.agents: the delegator's key and each payee's own signed offer) so the plugin signs every hop it opens.

operator allows it, and real-money settlement is not released.

Known limits

Read packages/plugin-claude-agent-sdk/KNOWN-LIMITS.md in the repository before you rely on the plugin.