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())

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.

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

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.

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.

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.