OpenAI Agents 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-openai-agents adds Dynamo to the OpenAI Agents SDK for Python. Every agent in a run gets its own capped slice of one budget. A handoff or an agent-as-tool call opens a child slice, which can never exceed what its parent has left. A call that would go over its slice is refused before the model is called.
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, install the two Python packages into a fresh venv and run the offline containment demo on a scripted mock model: no provider key, no model called. You need Node 22.12 or later, pnpm 9, curl and Python 3.10 or later (set PYTHON, for example PYTHON=python3.11, if python3 is older). Set DYNAMO_REPO to your clone. make value-gate-dn3 runs this block verbatim from a clean copy of the repository.
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-agents
.venv-agents/bin/pip install --quiet "./packages/sdk-python[verify]" ./packages/plugin-openai-agents
for _ in $(seq 150); do curl -fsS "$DYNAMO_CORE_URL/healthz" > /dev/null 2>&1 && break; sleep 0.2; done
.venv-agents/bin/python packages/plugin-openai-agents/examples/containment/run.py
Wrap an agent run in a budget
This is packages/plugin-openai-agents/examples/app/with_dynamo.py: a small three-agent app with Dynamo added. make value-gate-dn3 counts its changed lines against examples/app/plain.py; no test runs this file. make test-py-agents tests the plugin itself.
# SPDX-License-Identifier: Apache-2.0
"""A small multi-agent app on the OpenAI Agents SDK — with Dynamo.
Runs offline: the scripted mock model stands in for a real one.
"""
import asyncio
from agents import Agent, ModelSettings, Runner, set_tracing_disabled
from dynamoprotocol_openai_agents import AgentConfig, DynamoAgents, usd
from dynamoprotocol.testing import mock_prices
from dynamoprotocol_openai_agents.testing import HandoffTo, ScriptedModel, Text, Upstream
set_tracing_disabled(True)
upstream = Upstream()
settings = ModelSettings(max_tokens=256)
def model(name, *steps):
m = ScriptedModel("mock/scripted-1", upstream, label=name)
m.queue.extend(steps)
return m
researcher = Agent(name="researcher", model=model("researcher", Text("three sources found")), model_settings=settings)
writer = Agent(name="writer", model=model("writer", Text("draft written")), model_settings=settings)
orchestrator = Agent(
name="orchestrator",
handoffs=[researcher, writer],
model=model("orchestrator", HandoffTo("researcher")),
model_settings=settings,
)
async def main():
dyn = await DynamoAgents.connect(
prices=mock_prices(), cap=usd("5"), mandate={"categories": ["research", "writing", "review"], "maxDepth": 3},
agents={"orchestrator": AgentConfig(usd("5"), "review"), "researcher": AgentConfig(usd("1"), "research"), "writer": AgentConfig(usd("1"), "writing")},
)
result = await dyn.run(orchestrator, "Write a brief on grid-scale storage")
print(result.final_output)
await dyn.close()
asyncio.run(main())
DynamoAgents.connect(...)opens a budget with your cap and mandate. It
reads DYNAMO_CORE_URL and DYNAMO_OWNER_TOKEN when you do not pass core_url and token.
dyn.run(agent, input)replacesRunner.run(agent, input). A handoff opens
a child slice for the target agent. dyn.as_tool(agent, ...) replaces agent.as_tool(...).
- Set the completion limit per agent with
ModelSettings(max_tokens=...).
With a real model, pass your price table instead of mock_prices(), for example prices="quickstart/dynamo-guard/prices.json", or set DYNAMO_PRICE_TABLE.
What a refusal looks like
A refusal is a native openai-agents exception (an AgentsException subclass): DynamoCapExceeded, DynamoMandateRefused, DynamoRevoked, DynamoUnpricedModel, DynamoFrozen, DynamoStopped, DynamoApprovalPending, DynamoApprovalDenied and DynamoAmendmentRefused. Each carries stream_id, reason and headroom. The provider is never called for a refused call.
A refusal does not revoke anything: you decide what happens next. A model with no price-table row is refused with DynamoUnpricedModel; there is no default price.
Funding modes
- Control Mode (Live). A budget the plugin opens itself (
cap=) is
always a Control Mode budget: every check runs and no money moves. The quickstart and every test of this plugin use one.
- A funded budget. You can pass an existing stablecoin or credit card
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 child 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.
- Real money (Release-gated). A core runs a money mode only when its
operator allows it, and real-money settlement is not released.
Known limits
Read packages/plugin-openai-agents/KNOWN-LIMITS.md in the repository before you rely on the plugin.