# AI agent metering

AI agent metering is recording, for every model call and tool call an agent makes, what it used, what it cost and who it was for. With that record you can say what a customer, a user or a single request cost, set a limit that holds, and see where spend goes before the bill arrives.

This page is about the cost side of metering: what your agents spend on models and tools, and on whose behalf. Agent Pulse is built to do it, and the examples here are how it works.

## Why an agent needs a meter of its own

One thing a user asks for often makes many model and tool calls, across several agents. Each call is billed on its own, by the token, and nothing in a provider's bill says which of your customers, which feature or which request a call was for. Google's bill, for example, comes by the hour and by the model.

Three things make an agent's spend hard to read without a meter:

- **Calls multiply.** A retry, a tool loop or an agent calling another agent turns one request into many calls. Without a record that ties them together, the cost of the request cannot be added up.
- **Failures cost money.** A failed call is usually still billed for the work the provider did before it failed. A meter that only counts what worked understates the bill.
- **Prices change.** Providers change their rates and add models. A figure for last month has to stay what it was, at last month's prices.

## What to record about each call

A useful record answers four questions: who the call was for, what made it, what it used, and how it went. In Agent Pulse every model or tool call is one record with these fields:

| Question | Fields |
| --- | --- |
| Who it was for | The workspace, which is your customer; the user; the request; the session |
| What made it | The agent, and the service, component or skill in your product |
| What it used | The model and who bills for it; input, output, cached, cache-write and reasoning tokens |
| How it went | How long it took, how it ended, and the error code if it failed |
| What it cost | The estimated cost, and the billed cost where your bill confirms it |

The cost is worked out on the server from the token counts, so an agent never states its own cost. See [how cost is calculated](/docs/how-cost-is-calculated) and the [full list of fields](/docs/what-is-recorded).

## What to leave out

A meter needs counts, not content. Agent Pulse never records:

- prompts and completions;
- tool arguments and tool results, of which only the size is recorded;
- error messages, which often quote the prompt back, so a failure is kept as its code;
- names and email addresses on a record, which carries only the identifier your sign-in issued.

This is not a setting: a record has no field a prompt could go in. More on [what is recorded, and what never is](/docs/what-is-recorded) and on [security](/docs/security).

## Where the meter sits

A meter must never be the reason an agent fails. The Agent Pulse recorder runs inside your agent but is never in the path of your model calls, which go straight to the provider.

- Records go into a queue in your process and are sent in the background. Recording never waits on the network and never raises an error into your code.
- If the queue fills, new records are dropped rather than slowing your agent, and the drop is counted and reported, so a figure that is incomplete says so.
- Where a budget can stop calls, each call asks first. With no answer within 1.5 seconds, the call goes ahead, except a call a budget stopped within the last hour, which stays stopped.

See [when Agent Pulse is unavailable](/docs/when-agent-pulse-is-unavailable).

## What metering lets you do

### Cost per customer, user and request

Say once per request who it is for, where your code has checked the sign-in, and every model and tool call inside it is counted against that customer and user:

```python
with agentpulse.scope(
    request=request_id,
    workspace=account.slug,
    user=agentpulse.User(id=claims.subject, name=claims.name),
):
    handle(request)
```

```ts
await scope(
  {
    request: requestId,
    workspace: account.slug,
    user: { id: claims.sub, name: claims.name },
  },
  () => handle(req),
);
```

```go
ctx = recorder.WithWorkspace(ctx, account.Slug)
ctx = recorder.WithUser(recorder.WithRequest(ctx, requestID), recorder.User{
    ID:   claims.Subject,
    Name: claims.Name,
})
```

The console then shows spend by customer and by user, and can open one request and show every call in it, in order, with what each cost. See [track cost per customer and user](/docs/cost-per-customer).

### Cost per outcome

An outcome is a result your product counts, such as a booking made or a report finished. Attached to the request that produced it, it turns cost per call into cost per outcome. See [organisations, workspaces and requests](/docs/requests-and-workspaces).

### Budgets that hold

A budget is a limit over a period, for the whole organisation, one agent, a set of users or a set of workspaces. You are alerted as spend approaches it. At the limit, an enforced budget stops covered model calls and a warn-only budget lets them continue and alerts you. Behind the [LiteLLM proxy](/docs/litellm), a budget can instead send a call to a cheaper model from the same provider. See [set a budget that warns or stops calls](/docs/budgets).

### Spend on failures

Spend on failed calls and retries is kept apart from spend that worked, and grouped by kind, such as rate limits or timeouts, with the provider's error codes. See [find what is failing](/docs/failures).

## How to start

- **See what you would get first.** [Assess your codebase](/docs/assess) gives your coding agent a prompt that reads your repository, without changing it, and writes a report on what Agent Pulse would show you and what it would take to connect.
- **Connect one agent.** The [quickstart](/docs/quickstart) records an agent's first model call in Python, TypeScript or Go.
- **Use the framework you have.** There are guides for [LangChain and LangGraph](/docs/langchain), [Google ADK](/docs/google-adk), the [OpenAI Agents SDK](/docs/openai-agents), the [Vercel AI SDK](/docs/vercel-ai-sdk), the [LiteLLM proxy](/docs/litellm), [OpenTelemetry](/docs/opentelemetry) and the [OpenAI, Anthropic and Gemini clients](/docs/model-clients), with every other framework in the [docs](/docs).

How the cost of each call is worked out, and how to read it, is on [LLM cost tracking](/llm-cost-tracking).