LlamaIndex
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-llamaindex adds Dynamo to LlamaIndex agents (FunctionAgent and AgentWorkflow). Every agent in a workflow gets its own capped slice of one budget. A hand-off, or an agent called as a tool, opens a child slice that can never exceed what its parent has left. A model request that would go over its slice is refused before the model is called, and the refusal stops that step.
The plugin connects with a scoped hook credential (DYNAMO_HOOK_CREDENTIAL), never an owner key. Approvals, freezes and amendments stay with the operator, who holds the owner token.
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 (pip is first upgraded from the hash-pinned scripts/py/pip-bootstrap.txt), run the plain app, provision a budget and the plugin's scoped credentials as the operator, then run the app with Dynamo. The apps use the plugin's scripted offline LLM: 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 \
node deploy/image/entry.mjs > .dynamo-local.log 2>&1 &
CORE_PID=$!
trap 'kill "$CORE_PID"' EXIT
"${PYTHON:-python3}" -m venv .venv-llamaindex
PIP_ONLY_BINARY=":all:" .venv-llamaindex/bin/python -m pip install --quiet --require-hashes -r scripts/py/pip-bootstrap.txt
PIP_ONLY_BINARY=":all:" .venv-llamaindex/bin/pip install --quiet --require-hashes -r packages/plugin-llamaindex/locks/test.txt
.venv-llamaindex/bin/pip install --quiet --no-deps ./packages/sdk-python ./packages/plugin-llamaindex
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-llamaindex/bin/python packages/plugin-llamaindex/examples/app/plain.py
eval "$(.venv-llamaindex/bin/python packages/plugin-llamaindex/examples/app/provision.py)"
.venv-llamaindex/bin/python packages/plugin-llamaindex/examples/app/with_dynamo.py
curl -s "$DYNAMO_CORE_URL/owner/v1/budgets/$DYNAMO_BUDGET_ID/tree" -H "authorization: Bearer $DYNAMO_OWNER_TOKEN"
kill "$CORE_PID"; trap - EXIT
Both apps print three sources found. Delete .venv-llamaindex and .dynamo-local/ when you are done.
Wrap an agent run in a budget
This is packages/plugin-llamaindex/examples/app/with_dynamo.py: a lead agent that hands off to a research agent, with Dynamo added. make test-plugin-llamaindex runs it, after examples/app/provision.py, against a local core (tests/test_examples.py).
# SPDX-License-Identifier: Apache-2.0
"""A small multi-agent app on LlamaIndex — with Dynamo.
A lead agent hands the request off to a research agent, which answers. The
models are the plugin's scripted offline LLM (no key, no network call); put
your own LLM in `model()`.
"""
import asyncio
from llama_index.core.agent.workflow import AgentWorkflow, FunctionAgent
from dynamoprotocol.testing import mock_prices
from dynamoprotocol_llamaindex import AgentConfig, DynamoLlamaIndex, usd
from dynamoprotocol_llamaindex.testing.mock_llm import ScriptedLLM, Text, Upstream, handoff
UPSTREAM = Upstream()
def model(agent: str, *script) -> ScriptedLLM:
llm = ScriptedLLM("mock/scripted-1", UPSTREAM, agent=agent)
llm.queue.extend(script)
return llm
async def main() -> None:
dyn = await DynamoLlamaIndex.connect(prices=mock_prices(), agents={"lead": AgentConfig(usd("1.00"), "review"), "research": AgentConfig(usd("0.40"), "research")})
lead = FunctionAgent(name="lead", description="Plans the brief and hands research off.", llm=model("lead", handoff("research")), can_handoff_to=["research"])
research = FunctionAgent(name="research", description="Finds the sources.", llm=model("research", Text("three sources found")))
dyn.gate(lead, research)
workflow = AgentWorkflow(agents=[lead, research], root_agent="lead")
result = await dyn.run(workflow, "Write a brief on grid-scale storage")
print(f"research slice left: {(await dyn.headroom('research')).remaining_cap_units} of {usd('0.40')} µUSD")
await dyn.close()
print(result)
asyncio.run(main())
connectreadsDYNAMO_CORE_URL,DYNAMO_BUDGET_IDand
DYNAMO_HOOK_CREDENTIAL, and the entry agent's root stream from DYNAMO_ENTRY_AGENT, DYNAMO_ENTRY_STREAM and DYNAMO_ENTRY_DELEGATOR. provision.py prints these as export lines.
dyn.run(workflow, prompt)replacesworkflow.run(user_msg=...).
mock_prices() prices the scripted model only. With a real model, pass your price table (for example prices="quickstart/dynamo-guard/prices.json") or set DYNAMO_PRICE_TABLE. A model with no row is refused.
What a refusal looks like
A refusal is a typed error (DynamoCapExceeded, DynamoMandateRefused, DynamoRevoked, DynamoUnpricedModel, DynamoFrozen, DynamoStopped, DynamoApprovalPending, DynamoApprovalDenied, DynamoScopeRefused) and the step does not run. DynamoScopeRefused names a step the scoped credentials cannot take: without an entry stream or an operator=, dyn.run refuses with operator_required before any model call, and an owner token passed as a credential is refused with owner_key_refused before any request.
Funding modes
- Control Mode (Live). The plugin never opens a budget: it attaches to
the one the operator provisions (DYNAMO_BUDGET_ID). The example's provision.py opens a Control Mode budget, and every test of this plugin uses one.
- A funded budget. The plugin does not refuse a stablecoin or credit
card budget, but no test runs it 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= to connect (a LayerHops from dynamoprotocol.agents: the delegator's key and each payee's own signed offer) so the plugin signs every hop it opens; the operator's entry stream needs a signed hop too.
- 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-llamaindex/KNOWN-LIMITS.md in the repository before you rely on the plugin.