Turn on Cost X-Ray: route your model calls through ACP

There are two places ACP can sit in your agent, and they capture different things. Most integration guides wire up the first. If you want to see cost, you need the second.

For Claude Code, the hook already prices spend — it reads the transcript Claude Code hands it and prices each model turn from that, no launcher needed. For harnesses whose hook gets no transcript, only the model proxy — sitting in front of the LLM API, counting and pricing tokens on every call — can show it, and it also adds policy on the model call itself and the declared tool surface.

This matters most for autonomous, API-metered agents — the ones running unattended against a paid API, where nobody is watching the bill in real time. That’s exactly where a surprise cost shows up a month later instead of the moment it happens.

The change

Point your model client at the ACP proxy and authenticate with an ACP key. Get a key (format gsk_yourslug_xxxxxxxxxxxx) from cloud.agenticcontrolplane.com — the slug encodes your workspace, so the key resolves the tenant automatically.

OpenAI-compatible agents

Most agent frameworks speak the OpenAI Chat Completions API under the hood. Swap the base URL:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.agenticcontrolplane.com/v1",
    api_key=os.environ["ACP_API_KEY"],          # gsk_yourslug_...
    default_headers={
        # Optional: tag this agent so the dashboard groups its calls
        # as a distinct row. Use a different name per agent/role.
        "x-acp-agent-name": "my-agent",
    },
)

Anything that lets you set an OpenAI-compatible base URL — the openai SDK, LangChain’s ChatOpenAI, CrewAI, an OPENAI_BASE_URL environment variable — routes through the proxy with this one change. The proxy is multi-provider and routes by model id, so gpt-4o, claude-*, and gemini-* all work through the same endpoint.

Anthropic-native agents

If your agent calls the Anthropic Messages API directly, point it at the Anthropic-shaped proxy instead:

export ANTHROPIC_BASE_URL="https://api.agenticcontrolplane.com/anthropic/v1"
export ANTHROPIC_AUTH_TOKEN="gsk_yourslug_..."   # an ACP key, not an Anthropic key

What you’ll see

Within minutes of your agent running, cloud.agenticcontrolplane.com shows, per model call:

• Cost — tokens in / out, priced to dollars, per call and rolled up per run and per agent
• Prompt-cache hit rate — so you can catch a cold cache silently doubling your bill
• The loop-vs-leaf X-ray — how much you spend driving the orchestration loop vs. doing leaf work
• Policy checks on the tool calls the model emits — the proxy sees the tool_use blocks in the model’s output, so you get policy enforcement on tools even without a separate tool hook

This is a live Claude Code session running through the proxy — every model call a row with its model, tokens, cache hits, and priced cost, interleaved with the tool calls it drove, each stamped with the policy decision and priced cost:

And it rolls up. The Cost page is one screen: what the week cost against the week before, spend by day stacked by model, where the dollars go by billing class, and the sessions that account for most of it, each named by the directory it ran in:

Then it tells you what to change. Every lever is measured from your own calls, in recorded dollars, with a session that shows it. Side-model calls your harness makes on its own, the prompt prefix being rebuilt, long sessions whose last third costs more per turn than their first, recovery turns after failed or denied calls, and one harness caching worse than another:

Which one do I need?

There’s no menu here — there’s a default and an upgrade.

Everyone starts with the control install — the one command in your runtime’s integration guide (curl | bash for the coding agents, pip install acp-hermes for Hermes). It hooks tool calls at the point of execution: policy enforcement, full audit trail, identity attribution. It does not sit in your model’s data path — your prompts and completions never touch ACP. Zero configuration decisions.

Add the cost X-ray when you want spend visibility. This is the step this page documents, and it’s a deliberate opt-in, because it means something specific: your model calls route through ACP’s proxy. Here’s exactly what that does and doesn’t mean:

• Your provider still bills you directly. ACP forwards your own credential (subscription OAuth or API key) upstream — we never substitute or hold it.
• What we persist is metadata: model, token counts, cache-hit rates, priced cost, and policy decisions. Prompt and completion content transits the proxy and is scanned in-memory (PII, policy) — it is not stored unless you explicitly turn on content previews in your logging settings.
• The escape hatch stays open. The install never replaces your plain client. claude keeps its policy-checked hooks either way; claude-acp only adds the model-call routing that makes the X-ray possible. Unset one env var and Hermes talks to its provider directly again.

If routing model traffic through anyone is off the table for you — some teams’ policies say exactly that — the hook alone is a complete control and audit story, and the cost X-ray will be waiting if that changes.

Per-integration notes

Every integration guide covers the control install for that runtime. To add cost metering, apply the base-URL change above wherever that runtime configures its model endpoint. A few specifics:

• Coding agents: the hook policy-checks tools; a <harness>-acp launcher adds the priced model path for one launch. Every launcher is the same file generated from one template by the installer, so they all behave identically: workspace key from ~/.acp/credentials, the ACP provider selected for that launch only, plain harness untouched, and fail-open (if the gateway is unreachable, the plain harness starts with a one-line note; ACP_FAIL_MODE=closed refuses instead). The installer also writes a short directive into the file each harness’s agent reads at session start, so an agent setting things up for its user finds the launcher there.

“Not possible” rows are limits of the harness, not of ACP, and get the full tool-governance install like everything else. Every launcher row is exercised by the installer’s sandbox test (scripts/test-install-sandbox.sh in the site repo): a real install into a throwaway HOME, twice, then every launcher run against stub binaries and a stub gateway, then the gateway killed to prove fail-open.

• Framework agents (CrewAI, LangGraph, AutoGen, Pydantic AI, Vercel AI SDK): these use an OpenAI- or Anthropic-compatible client directly — the base-URL swap is the whole integration.
• Hosted agents (Bedrock, Vertex, Foundry): route the model endpoint through the proxy where the platform allows a custom base URL.

curl -sf https://agenticcontrolplane.com/install.sh | bash

irm https://agenticcontrolplane.com/install.ps1 | iex