Wrap your model call once, then hand the wrapped version to your agent.

from tokenops import ControlPlaneClient, tokenops_run
from tokenops.control import Halt, wrap_complete
from tokenops.providers import complete

client = ControlPlaneClient.from_env()

with tokenops_run(client=client, service="my-agent", intent="research",
                  provider="openai", model="gpt-4o") as bound:
    governed = wrap_complete(
        bound.governor, bound.controls, bound.attr,
        provider="openai", model="gpt-4o",
        dispatch=complete, service="my-agent",
    )
    try:
        agent.run(..., complete_fn=governed)   # <-- pass `governed`, not `complete`
    except Halt as stopped:
        print(f"run stopped: {stopped}")

Pass governed to your agent instead of complete; nothing else changes. wrap_complete checks the budget before each call and raises Halt when the run is out, even from another process.

git clone https://github.com/theagentplane/tokenops && cd tokenops
make install
make run          # control plane :7700 + Admin/Dashboard :8501

Then open localhost:8501 to see spend and governance per agent.

Each is a real multi-agent stack sharing one run ledger. One target starts the plane, the agents, and the Admin UI.

cp .env.example .env first if you want them to call real models. See examples/README.md for the bench profiles.

export TOKENOPS_URL=http://localhost:7700
export TOKENOPS_DB=tokenops.db   # plane and every agent read the same file

TOKENOPS_EMBEDDED=1 overrides TOKENOPS_URL. Leave it unset here, or each process silently falls back to its own local ledger and gets the full budget.

PyPI name is agent-tokenops; the import is tokenops. Extras: pip install "agent-tokenops[examples]" for the LangChain benches, ".[dev,examples]" from source. Releases: RELEASING.md.

TokenOps is two layers that share one artifact, the run: a control plane that registers runs and stores budgets/policies, and an in-process SDK that enforces at every boundary crossing.

flowchart LR
    subgraph PLANE["Control plane (:7700)"]
        R["POST /v1/runs"] --> DB[("SQLite TOKENOPS_DB<br/>registrations · budgets · policies · ledger")]
        UI["Admin + Dashboard"] --> DB
    end

    subgraph AGENTS["Agent processes (SDK)"]
        E["Entry agent<br/>tokenops_run"] -->|"register_run"| R
        E -->|"X-TokenOps-Run-Id"| D["Downstream agents<br/>tokenops_run"]
        E & D -->|"wrap_complete"| G["Governor<br/>pre_call → detect → decide → apply"]
        E & D -->|"@boundary + crossing hook"| G
        G --> L["Shared ledger<br/>(same run_id)"]
    end

    L --> DB
    DB -->|"governance_config_for"| G

Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See Chronicle for record-and-replay.

TOKENOPS_URL also accepts the aliases CONTROL_PLANE_URL and TOKENOPS_CONTROL_PLANE_URL.

Production / multi-process: set TOKENOPS_URL; agents must not mount /v1/runs. Tests: TOKENOPS_EMBEDDED=1 (or omit URL).

Precedence. ControlPlaneClient.from_env takes the HTTP path only when a URL is set and TOKENOPS_EMBEDDED is not 1. Setting both falls back to a local SQLite file with no warning, and every process then gets its own full budget. Check with print("embedded" if client.embedded else client.url).

Only src/tokenops/ is the installable package. Demos and benches stay under examples/.

src/tokenops/              # installable package
├── server/                # control plane (:7700, POST /v1/runs)
├── control/               # SDK: ledger, policies, wrap_complete, crossing hook
├── providers/             # OpenAI / Anthropic complete dispatch
├── config/                # default.yaml governance seed
└── ui/                    # Admin + Dashboard (Streamlit)
examples/                  # A2A benches (two-agent, triad, brief) + Chat/Simulator
benchmarking/              # MetaGPT / browser-use live harness
docs/                      # architecture, policies, guides, product
tests/                     # unit + e2e

• Onboarding: prereqs, minimum integration, FAQ, current limits
• Field guide: a triad walked through, with screenshots
• Policies: one page per policy
• Run attribution - control plane deploy - status
• Examples - comparison - shared ledger