@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +111 -0
- package/dist/act-B9hLQls6.mjs +19 -0
- package/dist/act-CrX0JwWY.cjs +42 -0
- package/dist/ai-sdk.cjs +63 -7
- package/dist/ai-sdk.d.cts +13 -3
- package/dist/ai-sdk.d.mts +13 -3
- package/dist/ai-sdk.mjs +63 -7
- package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
- package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
- package/dist/decision-object-B5zGSPFp.d.mts +15 -0
- package/dist/decision-object-DBcLWVvv.d.cts +15 -0
- package/dist/{run-agent-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
- package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
- package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
- package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
- package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
- package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
- package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
- package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
- package/dist/index.cjs +660 -286
- package/dist/index.d.cts +168 -9
- package/dist/index.d.mts +168 -9
- package/dist/index.mjs +639 -271
- package/dist/internal-C3Lqu538.d.cts +43 -0
- package/dist/internal-DUcdhk-i.d.mts +43 -0
- package/dist/log.cjs +2 -2
- package/dist/log.d.cts +1 -1
- package/dist/log.d.mts +1 -1
- package/dist/log.mjs +2 -2
- package/dist/machines.cjs +457 -41
- package/dist/machines.d.cts +114 -43
- package/dist/machines.d.mts +114 -43
- package/dist/machines.mjs +457 -42
- package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
- package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
- package/dist/openai.cjs +149 -36
- package/dist/openai.d.cts +28 -10
- package/dist/openai.d.mts +28 -10
- package/dist/openai.mjs +149 -36
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-BGdx5913.d.mts → run-agent-BcQ-9NRT.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.d.mts} +91 -9
- package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
- package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BIKcbVXV.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
- package/dist/tanstack-ai.cjs +62 -4
- package/dist/tanstack-ai.d.cts +18 -6
- package/dist/tanstack-ai.d.mts +18 -6
- package/dist/tanstack-ai.mjs +62 -4
- package/dist/testing.cjs +399 -20
- package/dist/testing.d.cts +196 -255
- package/dist/testing.d.mts +196 -255
- package/dist/testing.mjs +395 -20
- package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
- package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
- package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
- package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
- package/dist/{usage-BDiJKyv9.d.cts → usage-DoP0Oi84.d.mts} +1 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -1
- package/dist/utils-7lSa4H-i.d.cts +403 -0
- package/dist/utils-CBbKw2fM.d.mts +403 -0
- package/dist/validate.cjs +44 -12
- package/dist/validate.d.cts +6 -6
- package/dist/validate.d.mts +6 -6
- package/dist/validate.mjs +44 -12
- package/dist/verify-Bink-Drw.cjs +2304 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
- package/dist/verify-Dpz1u5Pe.mjs +2251 -0
- package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
- package/dist/with-model-calls-BkOwdroS.mjs +213 -0
- package/docs/act.md +102 -0
- package/docs/advanced.md +105 -0
- package/docs/any-stack.md +62 -0
- package/docs/choosing-a-run-mode.md +55 -0
- package/docs/debugging.md +29 -0
- package/docs/decisions.md +473 -0
- package/docs/environment-and-policy.md +188 -0
- package/docs/evals.md +509 -0
- package/docs/event-log.md +311 -0
- package/docs/from-a-loop.md +528 -0
- package/docs/generate-machines.md +110 -0
- package/docs/hosts.md +414 -0
- package/docs/human-in-the-loop.md +177 -0
- package/docs/index.md +48 -0
- package/docs/judgments.md +281 -0
- package/docs/langgraph-comparison.md +198 -0
- package/docs/machines-as-data.md +454 -0
- package/docs/machines-presets.md +198 -0
- package/docs/machines.md +497 -0
- package/docs/messages.md +67 -0
- package/docs/meta.json +52 -0
- package/docs/models-and-providers.md +268 -0
- package/docs/multi-agent.md +68 -0
- package/docs/observability.md +109 -0
- package/docs/patterns.md +31 -0
- package/docs/persistence.md +136 -0
- package/docs/quickstart.md +121 -0
- package/docs/roadmap.md +22 -0
- package/docs/scope.md +75 -0
- package/docs/statechart-policy-examples.md +69 -0
- package/docs/steps.md +54 -0
- package/docs/strangler-fig.md +323 -0
- package/docs/text-requests.md +250 -0
- package/docs/thinking-in-state-machines.md +324 -0
- package/docs/tools.md +249 -0
- package/docs/upgrading.md +37 -0
- package/docs/usage-and-budgets.md +516 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +487 -0
- package/docs/xstate-4-and-5-apps.md +161 -0
- package/llms.txt +53 -0
- package/package.json +10 -3
- package/readme.md +30 -15
- package/skills/add-evals/SKILL.md +3 -1
- package/skills/add-traces/SKILL.md +6 -1
- package/skills/build-machine/SKILL.md +81 -0
- package/skills/generate-machine/SKILL.md +1 -1
- package/skills/graph-engineering/SKILL.md +13 -3
- package/skills/improve-machine/SKILL.md +21 -2
- package/skills/loop-to-machine/SKILL.md +147 -192
- package/skills/loop-to-machine/reference.md +260 -0
- package/dist/utils-BnXdWih3.d.mts +0 -108
- package/dist/utils-ebVpCYoF.d.cts +0 -108
- package/dist/verify-Bpahmr34.mjs +0 -1241
- package/dist/verify-DCLZa9R0.cjs +0 -1288
- package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
- package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
|
@@ -0,0 +1,516 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Usage and budgets
|
|
3
|
+
description: Read token usage off a run, cap runaway loops with maxModelCalls, and enforce turn and token budgets as ordinary machine guards.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
> **Alpha:** `@statelyai/agent` 2.0 is in alpha. APIs can change between releases; pin an exact version. Feedback: [github.com/statelyai/agent](https://github.com/statelyai/agent/issues).
|
|
7
|
+
|
|
8
|
+
This page covers how to read token usage from a run and how to enforce budgets on it.
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
Usage is available at three layers, listed from coarsest to finest.
|
|
13
|
+
|
|
14
|
+
- After the run, `result.usage` gives the aggregated model-call usage for that run.
|
|
15
|
+
- During the run, on the host side, `onResult` and `onTrace` see each call's usage as it lands.
|
|
16
|
+
- During the run, on the machine side, the reserved `@agent.usage` event delivers each call's tokens to the machine. Budgets then live in `context` and are enforced by ordinary guards.
|
|
17
|
+
|
|
18
|
+
The first two layers are observational. Only the third can change what the agent does.
|
|
19
|
+
|
|
20
|
+
<!-- viz: usage flow: executor result -> runToQuiescence aggregation into result.usage, -> onResult/onTrace on the host, -> @agent.usage event into machine context and guards -->
|
|
21
|
+
|
|
22
|
+
## The usage result
|
|
23
|
+
|
|
24
|
+
<!-- AgentUsage from src/text-logic.ts; aggregation in src/run-agent.ts -->
|
|
25
|
+
|
|
26
|
+
Every settled `AgentRunResult` carries `usage`, on all three variants: `done`, `idle`, and `error`.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
|
|
30
|
+
|
|
31
|
+
result.usage.modelCalls; // number, always present
|
|
32
|
+
result.usage.totalTokens; // number | undefined (only calls that reported it)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
| Field | Meaning |
|
|
36
|
+
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
|
37
|
+
| `modelCalls` | Model and decision calls this run made. Always a number. Each decision retry and each tool-loop step counts separately. |
|
|
38
|
+
| `inputTokens`, `outputTokens`, `totalTokens`, `reasoningTokens`, `cachedInputTokens` | Partial sums. See the notes below. |
|
|
39
|
+
|
|
40
|
+
Four things affect how you read these numbers.
|
|
41
|
+
|
|
42
|
+
- Token fields are partial sums. Each field sums only the calls that reported it, and is `undefined` only when no call reported it. A run that mixes a real SDK executor, which reports usage, with a scripted mock, which does not, yields a sum over the reporting subset only. Do not treat a token total as the whole run unless every executor reports usage.
|
|
43
|
+
- `modelCalls` is always present, even when nothing reports tokens.
|
|
44
|
+
- Usage is per run, not per conversation. A resumed run counts only its own calls, not the history behind `snapshot` or `events`. Add prior results' totals yourself for a conversation-wide figure.
|
|
45
|
+
- A tool loop is one request but several model calls. An executor reports its steps as `modelCalls` on its result, and the adapters do. An executor that reports none counts as one call.
|
|
46
|
+
- Judgments are not counted. An `experimental_decide` actor is an ordinary actor, so its calls appear in neither `usage` nor `maxModelCalls`. See [Judgments](judgments.md).
|
|
47
|
+
- Usage comes from your executor. `runToQuiescence` reads `usage` from the raw executor result. That is the `usage` field alongside `result`, on the flat field names the AI SDK also uses, from an adapter or any custom executor following that shape. Non-finite values are dropped.
|
|
48
|
+
|
|
49
|
+
### Billing
|
|
50
|
+
|
|
51
|
+
`result.usage` is the authoritative record of what a run spent. Usage folds into the totals before the machine is involved, so a call counts even when its `@agent.usage` event is never delivered. A straggler that settles after the run resolved counts, and so does a call whose event no active state accepts. Only the machine event is dropped, and the drop is traced as `usage.dropped`. Counters in `context` are control flow, not billing: they only see the calls the machine reacted to.
|
|
52
|
+
|
|
53
|
+
Two caveats apply.
|
|
54
|
+
|
|
55
|
+
- `modelCalls` counts only calls admitted by the budget. A call rejected by `maxModelCalls` is not counted, because it was never made.
|
|
56
|
+
- Usage covers this run only. A resumed run does not re-add the history behind `snapshot` or `events`.
|
|
57
|
+
|
|
58
|
+
Summing across a resume chain is host code.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
function addUsage(a: AgentUsage, b: AgentUsage): AgentUsage {
|
|
62
|
+
const sum = (x?: number, y?: number) =>
|
|
63
|
+
x === undefined && y === undefined ? undefined : (x ?? 0) + (y ?? 0);
|
|
64
|
+
return {
|
|
65
|
+
modelCalls: a.modelCalls + b.modelCalls,
|
|
66
|
+
inputTokens: sum(a.inputTokens, b.inputTokens),
|
|
67
|
+
outputTokens: sum(a.outputTokens, b.outputTokens),
|
|
68
|
+
totalTokens: sum(a.totalTokens, b.totalTokens),
|
|
69
|
+
reasoningTokens: sum(a.reasoningTokens, b.reasoningTokens),
|
|
70
|
+
cachedInputTokens: sum(a.cachedInputTokens, b.cachedInputTokens),
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Per-call usage
|
|
76
|
+
|
|
77
|
+
Two callbacks report usage per call. Both are live and read-only.
|
|
78
|
+
|
|
79
|
+
- `onResult(request, { result, raw })`: `raw` is your executor's verbatim result, so `raw.usage` is that call's usage in whatever shape the executor produced.
|
|
80
|
+
- `onTrace` on a `request.end` event: `usage?: AgentCallUsage` is normalized, and present only when the executor reported usage. See [Observability](observability.md#trace-one-run).
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
await runToQuiescence(
|
|
84
|
+
createAgentRuntime(machine, {
|
|
85
|
+
executors,
|
|
86
|
+
onResult: (request, { raw }) => {
|
|
87
|
+
const usage = (raw as { usage?: AgentCallUsage }).usage;
|
|
88
|
+
if (usage) {
|
|
89
|
+
console.log(request.kind, request.id, usage);
|
|
90
|
+
}
|
|
91
|
+
},
|
|
92
|
+
onTrace: (event) => {
|
|
93
|
+
if (event.type === "request.end" && event.usage) {
|
|
94
|
+
console.log(event.request.id, event.usage.totalTokens);
|
|
95
|
+
}
|
|
96
|
+
},
|
|
97
|
+
}),
|
|
98
|
+
{ input },
|
|
99
|
+
);
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Use these for dashboards, per-tenant metering, and cost alerts. Neither can stop the run. To deliver usage to the machine, use [`@agent.usage`](#the-agentusage-event).
|
|
103
|
+
|
|
104
|
+
## The global backstop: `maxModelCalls`
|
|
105
|
+
|
|
106
|
+
`maxModelCalls` caps the number of model and decision calls one run may make. The default is `100`. Decision retries count separately.
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
const result = await runToQuiescence(
|
|
110
|
+
createAgentRuntime(machine, { executors, maxModelCalls: 20 }),
|
|
111
|
+
{ input },
|
|
112
|
+
);
|
|
113
|
+
|
|
114
|
+
if (result.status === "error" && result.cause === "max-model-calls") {
|
|
115
|
+
result.usage.modelCalls; // 20
|
|
116
|
+
result.snapshot; // resume from here after raising the cap
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- The overrun is thrown into the invoke that would have made the call, as an `AgentMaxModelCallsExceededError` with `code: 'max-model-calls'`. If nothing handles it, the run settles as `{ status: 'error', cause: 'max-model-calls' }`, with `usage`, `snapshot`, and `events` intact.
|
|
121
|
+
- An `onError` on that invoke catches the overrun like any other failure. Branch on the code to route the budget breach separately from a model or tool failure.
|
|
122
|
+
- A blanket `onError: { target: 'someState' }` also catches the overrun, so the run settles `done` at the cap instead of `error`. That is a valid choice, as long as it is deliberate.
|
|
123
|
+
- `maxModelCalls` counts calls, not tokens or dollars. A tool loop's steps are counted after its request returns, so the loop can pass the cap and the next call is the one refused.
|
|
124
|
+
- The machine reads the budget from [`@agent.usage`](#the-agentusage-event): each event carries `budget.modelCalls` and `budget.maxModelCalls`. Guard on the difference to keep a call in reserve, such as for a final report. Under `provideExecutors`, which has no budget, `budget` is absent. A decision's `@agent.usage` arrives after the event it chose, so a budget guard that reads it cannot reject that event; when the event ends the machine, the context counter never sees that call, but `result.usage` does.
|
|
125
|
+
|
|
126
|
+
### A budget across turns
|
|
127
|
+
|
|
128
|
+
`maxModelCalls` is per run. For a conversation that resumes once per turn, pass the calls earlier turns spent as `modelCallsSpent`. They count against `maxModelCalls` and appear in `budget.modelCalls`, but not in this run's `usage.modelCalls`.
|
|
129
|
+
|
|
130
|
+
```ts no-check
|
|
131
|
+
const result = await runToQuiescence(
|
|
132
|
+
createAgentRuntime(machine, { executors, maxModelCalls: 30, modelCallsSpent: thread.modelCalls }),
|
|
133
|
+
{ snapshot, event },
|
|
134
|
+
);
|
|
135
|
+
thread.modelCalls += result.usage.modelCalls;
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`runAgent` with `onIdle` does this between its passes, so `maxModelCalls` bounds the whole call.
|
|
139
|
+
|
|
140
|
+
```ts no-check
|
|
141
|
+
onError: [
|
|
142
|
+
{
|
|
143
|
+
guard: ({ event }) => event.error?.code === "max-model-calls",
|
|
144
|
+
target: "budgetSpent",
|
|
145
|
+
},
|
|
146
|
+
{ target: "failed" },
|
|
147
|
+
];
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Use `maxModelCalls` as a runaway-loop backstop. Put anything the machine's own logic should react to in a guard.
|
|
151
|
+
|
|
152
|
+
## Retries and executor budgets
|
|
153
|
+
|
|
154
|
+
Transport-level retries, such as retries for 429 responses, timeouts, and backoff, belong in the executor or the SDK it wraps, not in the machine. The AI SDK's `maxRetries` handles them, as do the equivalent options on the OpenAI and Anthropic clients. `maxRetries` keeps AI SDK semantics: it is the number of retries made after the first attempt, so `maxRetries: 2` allows up to three attempts. A raw-`fetch` executor adds its own loop. The machine never sees a transient network failure.
|
|
155
|
+
|
|
156
|
+
Machine-level retry is different. An authored `onError` transition that re-enters a state after a semantic failure, such as a validation rejection or an exhausted decision, is control flow you model explicitly.
|
|
157
|
+
|
|
158
|
+
For finer budgets than `maxModelCalls`, such as a token cap or a per-request-`src` call count, wrap the executors. A child machine's requests inherit the parent's executors, so one wrapper counts the whole tree.
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
function withBudget(base: AgentRequestExecutors, maxCalls: number): AgentRequestExecutors {
|
|
162
|
+
const calls = new Map<string, number>();
|
|
163
|
+
return {
|
|
164
|
+
...base,
|
|
165
|
+
generateText: async (request, info) => {
|
|
166
|
+
const name = request.name ?? "(anonymous)";
|
|
167
|
+
const n = (calls.get(name) ?? 0) + 1;
|
|
168
|
+
calls.set(name, n);
|
|
169
|
+
if (n > maxCalls) throw new Error(`Budget exceeded for '${name}'`);
|
|
170
|
+
return base.generateText!(request, info);
|
|
171
|
+
},
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
await runToQuiescence(createAgentRuntime(machine, { executors: withBudget(executors, 20) }), {
|
|
176
|
+
input,
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
A wrapper is still host-side. The machine cannot read its counts or react to them. For that, use `@agent.usage` and a guard.
|
|
181
|
+
|
|
182
|
+
## The `@agent.usage` event
|
|
183
|
+
|
|
184
|
+
<!-- AGENT_USAGE_EVENT_TYPE and AgentUsageEvent from src/usage.ts -->
|
|
185
|
+
|
|
186
|
+
`@agent.usage` is a reserved event that carries one model call's tokens into the machine. These rules govern it.
|
|
187
|
+
|
|
188
|
+
- You declare nothing for it. `setupAgent` and `createAgentSchemas` register `'@agent.usage'` and its payload schema in every agent's events, so the handler is typed and `event.usage.totalTokens` narrows. Declaring it yourself is an error, because the `@agent.` namespace is reserved. Pass `events` to `setupAgent`, even `events: {}`: without it every event type is accepted and every handler's event, `@agent.usage` and `xstate.error.actor` included, is typed with no payload.
|
|
189
|
+
- Usage reaches the root before the completion of the call that reported it, also from a request inside a child machine. A budget guard on the call's `onDone` sees its tokens.
|
|
190
|
+
- Delivery is opt-in. The event is delivered only when an active state declares a transition that matches it, either `'@agent.usage'` or the wildcard `'*'`. Otherwise no usage event is sent to the machine. Wildcard matching follows XState semantics, so a catch-all `on: { '*': … }` does receive `@agent.usage`. Narrow the handler on `event.type` when the catch-all is meant for other events.
|
|
191
|
+
- Declare the handler at machine level. A root `on: { '@agent.usage': … }` catches every call regardless of which state made it. A state-scoped handler drops calls made in other states.
|
|
192
|
+
- Delivery goes to the run's root machine, including usage from requests inside an invoked child machine. Attribute those calls with `id`, `src`, and `model`.
|
|
193
|
+
|
|
194
|
+
The payload has this shape.
|
|
195
|
+
|
|
196
|
+
```ts no-check
|
|
197
|
+
{
|
|
198
|
+
type: '@agent.usage',
|
|
199
|
+
usage: { inputTokens?, outputTokens?, totalTokens?, reasoningTokens?, cachedInputTokens? },
|
|
200
|
+
kind?: 'text' | 'decision', // which request reported it
|
|
201
|
+
id?: string, // the request's durable invoke id
|
|
202
|
+
src?: string, // the request's invoke src
|
|
203
|
+
model?: string, // the model ref it targeted
|
|
204
|
+
name?: string, // a text request's registered name
|
|
205
|
+
budget?: { modelCalls, maxModelCalls }, // counted against maxModelCalls so far, this call included
|
|
206
|
+
}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Why the event exists
|
|
210
|
+
|
|
211
|
+
Model-call results reach the machine with usage stripped out.
|
|
212
|
+
|
|
213
|
+
- A text invoke's `onDone` receives `{ result, messages }` only: the validated result and the executor's response messages. The runner drops the rest of the executor result, including usage (`src/run-agent.ts`).
|
|
214
|
+
- A decision delivers only the chosen event. `resolveDecision` returns the validated event and drops the executor's `usage` (`src/decision.ts`).
|
|
215
|
+
|
|
216
|
+
`@agent.usage` carries the tokens instead. After every settled model call that reported usage, `runToQuiescence` delivers the event to the machine, so `context` can fold it and guards can read it. You can then keep both counters in `context`: increment turns in `onDone`, and fold tokens in the `@agent.usage` handler.
|
|
217
|
+
|
|
218
|
+
### Rules
|
|
219
|
+
|
|
220
|
+
| Area | Rule |
|
|
221
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
222
|
+
| **Not model-facing** | The `@agent.*` namespace is excluded from `getAcceptedEvents` and `parseAgentEvent`. The event is never a decision candidate, even under `allowedEvents: ['*']`, and cannot be forged from a wire message. |
|
|
223
|
+
| **Durability** | The event is folded into machine context, so a native snapshot from `result.persist()` retains the counters when a later runtime resumes with `{ snapshot }`. |
|
|
224
|
+
| **Run scope** | `result.usage` counts calls made during that run only. Persist cumulative counters in machine context when they must survive snapshot resume. |
|
|
225
|
+
| **Stragglers** | A call that settles after a `runToQuiescence` leg resolved still folds into `result.usage`, but its machine event is dropped. Watch `usage.dropped` on `onTrace` if a counter looks short. |
|
|
226
|
+
| **Coverage** | Only usage your executor reports is delivered. No `usage` on the result means no event. [`simulateAgent`](verify.md) scripts return no usage, so a token counter stays `0` under simulation. Test budgets with `runToQuiescence` and a usage-reporting mock. |
|
|
227
|
+
|
|
228
|
+
Opt in with a transition.
|
|
229
|
+
|
|
230
|
+
```ts no-check
|
|
231
|
+
import { AGENT_USAGE_EVENT_TYPE, setupAgent } from "@statelyai/agent";
|
|
232
|
+
|
|
233
|
+
const agentSetup = setupAgent({ schemas });
|
|
234
|
+
|
|
235
|
+
const machine = agentSetup.createMachine({
|
|
236
|
+
// …context, states
|
|
237
|
+
on: {
|
|
238
|
+
// Typed from the default registration: `event.usage`, `event.kind`, …
|
|
239
|
+
[AGENT_USAGE_EVENT_TYPE]: ({ context, event }) => ({
|
|
240
|
+
context: { tokens: context.tokens + (event.usage.totalTokens ?? 0) },
|
|
241
|
+
}),
|
|
242
|
+
},
|
|
243
|
+
});
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
## Budgets as guards
|
|
247
|
+
|
|
248
|
+
A budget is data in `context`, not a separate runtime feature.
|
|
249
|
+
|
|
250
|
+
- Limits enter through `input` and land in `context`, as fields such as `maxTurns`, `maxTokens`, and `maxDollars`.
|
|
251
|
+
- Counters live in `context` and are folded in by the transitions that carry the data.
|
|
252
|
+
- Guards are ordinary transition functions. When over budget, return a transition into a final `outOfBudget` state, or return `undefined` so the expensive event cannot be taken at all.
|
|
253
|
+
|
|
254
|
+
None of this is agent-specific. It is the same [guard](machines.md#transitions) mechanism the rest of the machine uses, so it composes with decisions. A candidate event whose transition returns `undefined` is never offered to the model.
|
|
255
|
+
|
|
256
|
+
### Turn and token budget
|
|
257
|
+
|
|
258
|
+
A machine-level `@agent.usage` handler folds every call's tokens into `context`. An ordinary guard stops the loop when the budget is spent.
|
|
259
|
+
|
|
260
|
+
<!-- viz: budget machine: researching -> checkingBudget -> researching loop, exiting to final outOfBudget when turns or tokens exceed their limits, with @agent.usage folding tokens at machine level -->
|
|
261
|
+
|
|
262
|
+
```ts
|
|
263
|
+
import { z } from "zod";
|
|
264
|
+
import {
|
|
265
|
+
AGENT_USAGE_EVENT_TYPE,
|
|
266
|
+
createAgentSchemas,
|
|
267
|
+
createTextLogic,
|
|
268
|
+
runToQuiescence,
|
|
269
|
+
setupAgent,
|
|
270
|
+
} from "@statelyai/agent";
|
|
271
|
+
|
|
272
|
+
const researchStep = createTextLogic({
|
|
273
|
+
schemas: { input: z.object({ topic: z.string(), turn: z.number() }), output: z.string() },
|
|
274
|
+
model: "openai/gpt-6-luna",
|
|
275
|
+
prompt: ({ input }) => `Research ${input.topic}. Turn ${input.turn}. One new fact.`,
|
|
276
|
+
});
|
|
277
|
+
|
|
278
|
+
const schemas = createAgentSchemas({
|
|
279
|
+
// Limits arrive as input.
|
|
280
|
+
input: z.object({ topic: z.string(), maxTurns: z.number(), maxTokens: z.number() }),
|
|
281
|
+
context: z.object({
|
|
282
|
+
topic: z.string(),
|
|
283
|
+
notes: z.array(z.string()),
|
|
284
|
+
turns: z.number(),
|
|
285
|
+
tokens: z.number(),
|
|
286
|
+
maxTurns: z.number(),
|
|
287
|
+
maxTokens: z.number(),
|
|
288
|
+
}),
|
|
289
|
+
output: z.object({
|
|
290
|
+
notes: z.array(z.string()),
|
|
291
|
+
turns: z.number(),
|
|
292
|
+
tokens: z.number(),
|
|
293
|
+
stoppedBy: z.string(),
|
|
294
|
+
}),
|
|
295
|
+
});
|
|
296
|
+
|
|
297
|
+
const agentSetup = setupAgent({ schemas, actors: { researchStep } });
|
|
298
|
+
|
|
299
|
+
const machine = agentSetup.createMachine({
|
|
300
|
+
// Limits become plain context data.
|
|
301
|
+
context: ({ input }) => ({
|
|
302
|
+
topic: input.topic,
|
|
303
|
+
notes: [],
|
|
304
|
+
turns: 0,
|
|
305
|
+
tokens: 0,
|
|
306
|
+
maxTurns: input.maxTurns,
|
|
307
|
+
maxTokens: input.maxTokens,
|
|
308
|
+
}),
|
|
309
|
+
// Machine-level, so every model call's tokens are folded.
|
|
310
|
+
on: {
|
|
311
|
+
[AGENT_USAGE_EVENT_TYPE]: ({ context, event }) => ({
|
|
312
|
+
context: { tokens: context.tokens + (event.usage.totalTokens ?? 0) },
|
|
313
|
+
}),
|
|
314
|
+
},
|
|
315
|
+
initial: "researching",
|
|
316
|
+
states: {
|
|
317
|
+
researching: {
|
|
318
|
+
invoke: {
|
|
319
|
+
id: "research",
|
|
320
|
+
src: "researchStep",
|
|
321
|
+
input: ({ context }) => ({ topic: context.topic, turn: context.turns + 1 }),
|
|
322
|
+
// Tokens arrive through `@agent.usage`, so only turns are folded here.
|
|
323
|
+
onDone: ({ context, output }) => ({
|
|
324
|
+
target: "checkingBudget",
|
|
325
|
+
context: { notes: [...context.notes, output.result], turns: context.turns + 1 },
|
|
326
|
+
}),
|
|
327
|
+
// No onError, so a maxModelCalls overrun surfaces as the run's error
|
|
328
|
+
// result instead of being handled here.
|
|
329
|
+
},
|
|
330
|
+
},
|
|
331
|
+
checkingBudget: {
|
|
332
|
+
always: ({ context }) =>
|
|
333
|
+
context.turns >= context.maxTurns || context.tokens >= context.maxTokens
|
|
334
|
+
? { target: "outOfBudget" }
|
|
335
|
+
: { target: "researching" },
|
|
336
|
+
},
|
|
337
|
+
outOfBudget: {
|
|
338
|
+
type: "final",
|
|
339
|
+
output: ({ context }) => ({
|
|
340
|
+
notes: context.notes,
|
|
341
|
+
turns: context.turns,
|
|
342
|
+
tokens: context.tokens,
|
|
343
|
+
stoppedBy: context.tokens >= context.maxTokens ? "tokens" : "turns",
|
|
344
|
+
}),
|
|
345
|
+
},
|
|
346
|
+
},
|
|
347
|
+
});
|
|
348
|
+
|
|
349
|
+
// Scripted executor. Returning `usage` is what feeds `@agent.usage`.
|
|
350
|
+
let call = 0;
|
|
351
|
+
const executors = {
|
|
352
|
+
generateText: async () => ({
|
|
353
|
+
result: `fact ${++call}`,
|
|
354
|
+
usage: { totalTokens: 520 },
|
|
355
|
+
}),
|
|
356
|
+
};
|
|
357
|
+
|
|
358
|
+
const result = await runToQuiescence(
|
|
359
|
+
createAgentRuntime(machine, { maxModelCalls: 20, executors }),
|
|
360
|
+
{ input: { topic: "otter migration", maxTurns: 5, maxTokens: 1500 } },
|
|
361
|
+
);
|
|
362
|
+
|
|
363
|
+
if (result.status === "done") {
|
|
364
|
+
result.output.stoppedBy; // 'tokens' (3 calls, 1560 >= 1500)
|
|
365
|
+
}
|
|
366
|
+
result.usage; // { totalTokens: 1560, modelCalls: 3 }
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
Two details of this shape matter.
|
|
370
|
+
|
|
371
|
+
- The loop runs `researching -> checkingBudget -> researching`. A transition targeting its own state does not re-enter it, so a self-targeting `onDone` would not re-run the invoke. Route through a check state instead.
|
|
372
|
+
- The tokens land between the call settling and its `onDone`, so `checkingBudget` always reads a counter that includes the most recent call.
|
|
373
|
+
|
|
374
|
+
### Guarding a decision
|
|
375
|
+
|
|
376
|
+
The same guard removes an over-budget choice from the decision entirely. An event whose transition returns `undefined` is not a legal candidate, so the model is never offered it.
|
|
377
|
+
|
|
378
|
+
```ts no-check
|
|
379
|
+
deciding: {
|
|
380
|
+
invoke: {
|
|
381
|
+
id: 'chooseNext',
|
|
382
|
+
src: 'agent.decide',
|
|
383
|
+
input: {
|
|
384
|
+
model: 'openai/gpt-6-luna',
|
|
385
|
+
prompt: 'Research more, or summarize what we have?',
|
|
386
|
+
allowedEvents: ['RESEARCH_MORE', 'SUMMARIZE'],
|
|
387
|
+
},
|
|
388
|
+
},
|
|
389
|
+
on: {
|
|
390
|
+
// Over budget this returns undefined, so RESEARCH_MORE is not takeable.
|
|
391
|
+
RESEARCH_MORE: ({ context }) =>
|
|
392
|
+
context.tokens < context.maxTokens ? { target: 'researching' } : undefined,
|
|
393
|
+
SUMMARIZE: { target: 'summarizing' },
|
|
394
|
+
},
|
|
395
|
+
}
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
## Usage without runToQuiescence
|
|
399
|
+
|
|
400
|
+
### Uncontrolled: `provideExecutors` + `createActor`
|
|
401
|
+
|
|
402
|
+
Delivery is built in, but it follows the binding boundary. `provideExecutors` does not descend into invoked child machines, so a child with its own agent invokes needs its own `provideExecutors(...)` call. Until it has one, its calls report no usage anywhere. `runToQuiescence` rebinds children and reports their usage to the root. A [long-lived actor](choosing-a-run-mode.md#long-lived-actor) has no run cycle, so no stragglers are dropped either.
|
|
403
|
+
|
|
404
|
+
```ts no-check
|
|
405
|
+
import { createActor, toPromise } from "xstate";
|
|
406
|
+
import { provideExecutors } from "@statelyai/agent";
|
|
407
|
+
|
|
408
|
+
// `machine` declares `on: { '@agent.usage': … }` as above.
|
|
409
|
+
const actor = createActor(provideExecutors(machine, { generateText }), {
|
|
410
|
+
input: { topic: "otters", maxTokens: 1500 },
|
|
411
|
+
});
|
|
412
|
+
actor.start();
|
|
413
|
+
|
|
414
|
+
const output = await toPromise(actor); // stoppedBy: 'tokens'
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
### Plain XState: manual send
|
|
418
|
+
|
|
419
|
+
In a hand-rolled loop over `actor.send`, `@agent.usage` is an ordinary event.
|
|
420
|
+
|
|
421
|
+
```ts
|
|
422
|
+
const result = await generateText(request);
|
|
423
|
+
if (result.usage) {
|
|
424
|
+
actor.send({ type: "@agent.usage", usage: result.usage });
|
|
425
|
+
}
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
A `setupAgent` machine already declares `'@agent.usage'` in its event union. A machine built with a plain `setup()` must declare it.
|
|
429
|
+
|
|
430
|
+
```ts
|
|
431
|
+
import { z } from "zod";
|
|
432
|
+
import { createActor, setup } from "xstate";
|
|
433
|
+
|
|
434
|
+
const machine = setup({
|
|
435
|
+
schemas: {
|
|
436
|
+
context: z.object({ tokens: z.number() }),
|
|
437
|
+
events: {
|
|
438
|
+
// The reserved type, declared by hand.
|
|
439
|
+
"@agent.usage": z.object({ usage: z.object({ totalTokens: z.number().optional() }) }),
|
|
440
|
+
GO: z.object({}),
|
|
441
|
+
},
|
|
442
|
+
},
|
|
443
|
+
}).createMachine({
|
|
444
|
+
context: { tokens: 0 },
|
|
445
|
+
on: {
|
|
446
|
+
"@agent.usage": ({ context, event }) => ({
|
|
447
|
+
context: { tokens: context.tokens + (event.usage.totalTokens ?? 0) },
|
|
448
|
+
}),
|
|
449
|
+
},
|
|
450
|
+
// …states
|
|
451
|
+
});
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
## Cost estimation
|
|
455
|
+
|
|
456
|
+
The library ships no price data and never estimates cost. Keep a price table in host code.
|
|
457
|
+
|
|
458
|
+
```ts
|
|
459
|
+
// USD per 1M tokens. Fill in from your provider's pricing page.
|
|
460
|
+
const PRICES: Record<string, { input: number; output: number }> = {
|
|
461
|
+
"openai/gpt-6-luna": { input: 0, output: 0 },
|
|
462
|
+
};
|
|
463
|
+
|
|
464
|
+
function estimateCost(model: string, usage: AgentUsage | AgentCallUsage): number {
|
|
465
|
+
const price = PRICES[model];
|
|
466
|
+
if (!price) {
|
|
467
|
+
throw new Error(`No price for model '${model}'.`);
|
|
468
|
+
}
|
|
469
|
+
const input = ((usage.inputTokens ?? 0) - (usage.cachedInputTokens ?? 0)) * price.input;
|
|
470
|
+
const output = (usage.outputTokens ?? 0) * price.output;
|
|
471
|
+
return (input + output) / 1_000_000;
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
estimateCost("openai/gpt-6-luna", result.usage);
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
`result.usage` is aggregated across every model the run used, so a per-model figure needs per-call attribution.
|
|
478
|
+
|
|
479
|
+
```ts no-check
|
|
480
|
+
let spentUsd = 0;
|
|
481
|
+
|
|
482
|
+
await runToQuiescence(
|
|
483
|
+
createAgentRuntime(machine, {
|
|
484
|
+
executors,
|
|
485
|
+
onTrace: (event) => {
|
|
486
|
+
if (event.type !== "request.end" || !event.usage) {
|
|
487
|
+
return;
|
|
488
|
+
}
|
|
489
|
+
// A decision carries `model` directly; a text request carries it on `input`.
|
|
490
|
+
const model =
|
|
491
|
+
event.request.kind === "decision" ? event.request.model : event.request.input.model;
|
|
492
|
+
spentUsd += estimateCost(model, event.usage);
|
|
493
|
+
},
|
|
494
|
+
}),
|
|
495
|
+
{ input },
|
|
496
|
+
);
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
`@agent.usage` carries the same `model` attribution, so the machine can keep a per-model spend counter in `context` and guard on it, instead of only reporting one from the host.
|
|
500
|
+
|
|
501
|
+
Cached input tokens are usually billed at a discount rather than free. Subtracting them as shown above gives a floor, not an exact invoice. Reconcile against your provider's billing and treat these numbers as budget signals.
|
|
502
|
+
|
|
503
|
+
## Legacy: usage in the request output
|
|
504
|
+
|
|
505
|
+
Before `@agent.usage` existed, tokens reached `context` by declaring a `usage` field on a request's own output schema and having the executor fill it. Prefer `@agent.usage`.
|
|
506
|
+
|
|
507
|
+
The older form still has two uses. The tokens arrive inside `onDone`, in the same transition as the output, and they survive `simulateAgent` because a script can return them. It only works for output shapes you own, so it cannot cover a shared request, a third-party executor, or a decision.
|
|
508
|
+
|
|
509
|
+
## Related
|
|
510
|
+
|
|
511
|
+
- [Observability](observability.md): the trace stream `request.end` usage rides on.
|
|
512
|
+
- [Persistence](persistence.md): storing the machine context that folded delivered usage events.
|
|
513
|
+
- [Machines](machines.md#transitions): guards as return values.
|
|
514
|
+
- [Decisions](decisions.md): why a guarded-out event is never offered to the model.
|
|
515
|
+
- [Human in the loop](human-in-the-loop.md): pausing and resuming across run boundaries.
|
|
516
|
+
- [Hosts](hosts.md): where executors, and executor-level budgets, are supplied.
|