Google ADK

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-adk adds Dynamo to Google's Agent Development Kit. Every agent in a run gets its own capped slice of one budget. A transfer_to_agent hand-off or an AgentTool 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 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 mock model: 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-adk
PIP_ONLY_BINARY=":all:" .venv-adk/bin/pip install --quiet --require-hashes -r packages/plugin-adk/locks/test.txt
.venv-adk/bin/pip install --quiet --no-deps ./packages/sdk-python ./packages/plugin-adk
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-adk/bin/python packages/plugin-adk/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-adk/examples/app/with_dynamo.py: a small three-agent app with Dynamo added. No test runs this file; make test-plugin-adk tests the plugin itself (the shared per-call conformance scenarios and the ADK transfer tests against a local core).

# SPDX-License-Identifier: Apache-2.0
"""A small multi-agent app on Google ADK — with Dynamo.

Runs offline: the scripted mock model stands in for a real one.
"""

import asyncio

from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

from dynamoprotocol_adk import AgentConfig, DynamoADK, usd
from dynamoprotocol.testing import mock_prices
from dynamoprotocol_adk.testing import ScriptedLlm, Text, Transfer, Upstream

upstream = Upstream()
config = types.GenerateContentConfig(max_output_tokens=256)


def model(name, *steps):
    return ScriptedLlm(model="mock/scripted-1", upstream=upstream, label=name, queue=list(steps))


researcher = LlmAgent(name="researcher", model=model("researcher", Text("three sources found")), generate_content_config=config)
writer = LlmAgent(name="writer", model=model("writer", Text("draft written")), generate_content_config=config)
orchestrator = LlmAgent(
    name="orchestrator",
    sub_agents=[researcher, writer],
    model=model("orchestrator", Transfer("researcher")),
    generate_content_config=config,
)


async def main():
    dyn = await DynamoADK.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")},
    )
    sessions = InMemorySessionService()
    runner = Runner(app=App(name="brief", root_agent=orchestrator, plugins=[dyn.plugin]), session_service=sessions)
    session = await sessions.create_session(app_name="brief", user_id="me")
    ask = types.Content(role="user", parts=[types.Part(text="Write a brief on grid-scale storage")])
    async for event in dyn.run_async(runner, user_id="me", session_id=session.id, new_message=ask):
        if event.is_final_response():
            print(event.content.parts[0].text)
    await dyn.close()


asyncio.run(main())

In your own app, pass your real price table (prices="prices.json" or DYNAMO_PRICE_TABLE) instead of the test-only mock_prices(), and set DYNAMO_CORE_URL and DYNAMO_OWNER_TOKEN for your core. An unknown model is refused.

What a refusal looks like

A refusal raises DynamoCapExceeded, DynamoMandateRefused, DynamoRevoked, DynamoUnpricedModel, DynamoFrozen, DynamoStopped, DynamoApprovalPending, DynamoApprovalDenied or DynamoAmendmentRefused, all subclasses of DynamoADKError. It is raised in before_model_callback, before the model is called. A transfer that would widen what the transferring agent holds is refused before the target runs, and nothing is allocated.

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 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.

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

Known limits

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