AgentsVille

Concepts

Usage

Usage is the number of tokens a Provider reports for one model call — a reply, a Conversation summary, a Level rating, a draft, or an embedding — input and output, written to the Usage ledger the moment the call returns.

AgentsVille records it, and can warn about it. AgentsVille never acts on it.

Recorded, never enforced

Nothing in AgentsVille reads those numbers to restrict what anybody may do. There are no quotas, no credits, no per-Player budgets, and no point at which AgentsVille stops a Conversation because it has cost enough. That is a deliberate non-goal, not a feature that has not shipped yet.

Two reasons.

First, usage cannot be reconstructed later. You cannot backfill tokens you never recorded, so AgentsVille writes them at the moment the Provider reports them — and that is worth doing whether or not anything ever reads them.

Second, an in-app counter cannot stop a Provider from charging. Quota machinery would guard against people the Operator invited personally, while doing nothing about the only number that actually bills. See ADR 0003.

Usage limits

An NPC's owner can give it a Usage limit on the Model step of its form: a number of tokens in the last 24 hours, 7 days or 30 days. The Operator can set one for the whole Village under Settings, Font and Usage.

Crossing a limit puts a warning above the composer in that NPC's chats (in every chat, for the Village limit) and turns the figure red on the Usage pages. The next message still sends and the reply still runs: a Usage limit warns, it never refuses. See ADR 0040.

Where the real ceiling is

The spend cap in your Anthropic or OpenAI console. That is the limit that exists, it is the one that works, and AgentsVille is not a substitute for setting it.

If you are running a Village for other people, set the cap before you hand out the invite code.

Interrupted replies still cost

Usage is written on the paths that go wrong, not only the clean one. A reply you stopped halfway was still generated up to that point, and it was still billed, so what the Provider produced is what gets stored — partial text, partial Parts, and the tokens that paid for them.

The same applies when a Provider errors mid-reply.

What actually spends tokens

In rough order of how much difference they make:

  • Thinking. Reasoning is billed. It is off by default on every NPC, per NPC, and the cost is stated where you switch it on.
  • Tool results. A tool result goes into the history and is re-sent on later turns. A Conversation full of file contents costs more per turn than one full of paragraphs.
  • Party hops. Each NPC-to-NPC handoff is another turn against another model.
  • Long Conversations. Trimmed before they are sent, so this is bounded rather than unbounded — but the window is large.

The bounds that do exist

None of these is a quota. They exist so a loop cannot run away with an afternoon:

  • Twelve Tool steps per turn by default.
  • Six NPC-to-NPC hops per message you send, configurable by the Operator.
  • A history window, with what falls off the front folded into a rolling summary.

Each one says so when it ends a turn, rather than going quiet.

Reading it

Open Usage in the header. Day shows the last 30 days, Week the last 12 weeks, Month the last 12 months, each cut at your own midnight. The Operator sees the whole Village; every other Player sees the calls their own turns caused. Below the chart, each NPC's share, largest first. Drafts and Level ratings belong to no NPC and are listed together.

An NPC's own Usage is in its chat menu, under Usage.

The ledger is the token_usage table (see Database schema). It has no foreign keys: deleting a Conversation or an NPC never removes what it used, and regenerating a reply keeps the old reply's tokens.

For what you are actually being charged, read your Provider's console. That is the authoritative number, and it includes everything AgentsVille's record cannot see.

Next