OpenAI Agents JS
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 OpenAI Agents JS. It is the TypeScript twin of the Python OpenAI Agents plugin. Every agent in a run gets its own capped slice of one budget. A hand-off or an agent-as-tool call opens a child slice, which can never exceed what its parent has left. A model call that would go over its slice is refused before the model is called.
The plugin is not published. It is used from a clone of the repository.
Install and try it
These are the commands from the plugin README. They build the workspace and run the offline containment demo, which boots a local core and uses a scripted model: no provider key, no model called. You need Node 22.12 or later and pnpm 9.
cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter @dynamo/core-host... -r build
pnpm --filter "@dynamoprotocol/openai-agents..." build
node packages/plugin-openai-agents-js/examples/containment.mjs
Wrap an agent run in a budget
This is packages/plugin-openai-agents-js/examples/app/with-dynamo.mjs: a small three-agent app with Dynamo added. It needs DYNAMO_CORE_URL and DYNAMO_OWNER_TOKEN set to a running core. No test runs this file; make test-plugin-openai-agents-js tests the plugin itself (the nine shared per-call conformance scenarios against a local core).
// SPDX-License-Identifier: Apache-2.0
// A small multi-agent app on OpenAI Agents JS — with Dynamo.
// Runs offline: the scripted model stands in for a real one.
import { Agent } from "@openai/agents";
import { DynamoAgents, usd } from "@dynamoprotocol/openai-agents";
import { mockPrices } from "@dynamoprotocol/agents/testing";
import { ScriptedModelProvider } from "@dynamoprotocol/openai-agents/testing";
const provider = new ScriptedModelProvider();
provider.model.script({ kind: "handoff", to: "researcher" }, { kind: "say", text: "three sources found" });
const settings = { maxTokens: 256 };
const researcher = new Agent({ name: "researcher", model: "mock/scripted-1", modelSettings: settings });
const writer = new Agent({ name: "writer", model: "mock/scripted-1", modelSettings: settings });
const orchestrator = new Agent({ name: "orchestrator", handoffs: [researcher, writer], model: "mock/scripted-1", modelSettings: settings });
const dyn = await DynamoAgents.connect({
prices: mockPrices(), cap: usd("5"), mandate: { categories: ["research", "writing", "review"], maxDepth: 3 }, modelProvider: provider,
agents: { orchestrator: { slice: usd("5"), category: "review" }, researcher: { slice: usd("1"), category: "research" }, writer: { slice: usd("1"), category: "writing" } },
});
const result = await dyn.run(orchestrator, "Write a brief on grid-scale storage", { runConfig: { tracingDisabled: true } });
console.log(result.finalOutput);
dyn.run(agent, input, options)replacesrunner.run(agent, input, options).dyn.asTool(agent, {...})replacesagent.asTool({...}).- An agent whose
modelis aModelobject, not a name, must be wrapped:
model: dyn.model("openai/gpt-6-luna", myModel). An unwrapped one is refused.
With a real model, leave out modelProvider and pass your price table instead of mockPrices(), for example prices: "quickstart/dynamo-guard/prices.json", or set DYNAMO_PRICE_TABLE.
What a refusal looks like
A refusal is a native Agents JS error (an AgentsError subclass): DynamoCapExceeded, DynamoMandateRefused, DynamoRevoked, DynamoUnpricedModel, DynamoFrozen, DynamoStopped, DynamoApprovalPending, DynamoApprovalDenied and DynamoAmendmentRefused. Each carries reason, streamId and headroom. The provider is never called for a refused call.
A refusal does not revoke anything: you decide what happens next. An agent without modelSettings: { maxTokens: ... } and without defaultCompletionTokens is refused rather than guessed.
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 (budgetId). 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-js/KNOWN-LIMITS.md in the repository before you rely on the plugin.