@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
package/docs/hosts.md
ADDED
|
@@ -0,0 +1,414 @@
|
|
|
1
|
+
# Hosts and executors
|
|
2
|
+
|
|
3
|
+
The machine owns agent control flow. A host supplies model request executors.
|
|
4
|
+
|
|
5
|
+
```ts no-check
|
|
6
|
+
const result = await runToQuiescence(
|
|
7
|
+
createAgentRuntime(machine, {
|
|
8
|
+
executors: {
|
|
9
|
+
generateText: async (request, { signal }) => {
|
|
10
|
+
const response = await mySdk.generate({
|
|
11
|
+
model: request.model,
|
|
12
|
+
prompt: request.prompt,
|
|
13
|
+
signal,
|
|
14
|
+
});
|
|
15
|
+
return { result: response.text, messages: response.messages };
|
|
16
|
+
},
|
|
17
|
+
},
|
|
18
|
+
}),
|
|
19
|
+
{ input },
|
|
20
|
+
);
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Text, stream, and decision executors all receive `(request, info)`; cancellation is `info.signal`.
|
|
24
|
+
|
|
25
|
+
## Idempotency keys
|
|
26
|
+
|
|
27
|
+
Execution is at-least-once. A host runs the request and then journals its completion, so a crash between the two re-executes the request on resume. `createAgentRuntime(machine, { store, threadId })` makes the log durable _before_ each call, which bounds the duplicate to the one call that was in flight; it does not remove it.
|
|
28
|
+
|
|
29
|
+
`info.callKey` makes the duplicate safe to drop. Its format is `<executionId>:<requestId>#<n>`:
|
|
30
|
+
|
|
31
|
+
- `executionId` is the log's lineage id, pinned in the reserved `@agent.init` entry's `metadata` and inherited by every resume.
|
|
32
|
+
- `requestId` is the invoke site, and `n` is the invocation's ordinal there: how many times a fold of the log has started that invoke, a cancelled invocation included. Each iteration of a looped state gets its own key, and so does a call re-entered after a cancel. A run whose log cannot be folded counts the site's completions instead, a decision counting once its chosen event is journaled.
|
|
33
|
+
- A call inside an invoked child machine names the child's path: `<executionId>:<childId>/<requestId>#<n>`, one `/` segment per nesting level. A `%` or `/` inside an id is escaped as `%25` or `%2F`. The child's own entries (its `actorPath`) are folded too, so `n` keeps counting across turns and across invocations of the child.
|
|
34
|
+
- A decision retry appends its attempt ordinal: `<executionId>:<requestId>#<n>.<attempt>`, where `attempt` is the number of prior failed attempts. Each retry is a different request, so it gets a different key.
|
|
35
|
+
- A [decision strategy](decisions.md#decision-strategies)'s sub-calls append their role: `<executionId>:<requestId>#<n>.<attempt>.pick`, `.group`, or `.fill`.
|
|
36
|
+
- A resumed run re-executing an in-flight request passes the same `callKey` as the original attempt.
|
|
37
|
+
- A fork mints its own lineage id (see [Fork](event-log.md#fork)), so none of its calls shares a key with its parent's.
|
|
38
|
+
- It is `undefined` off the `runToQuiescence` path (a bare `provideExecutors` bind) and on a run with no event log.
|
|
39
|
+
- Only model calls get one. A plain actor (`createAsyncLogic`, a tool) in flight at a crash runs again on resume with no key. Derive an idempotency key from the domain (an order id, a booking key) and dedupe inside the effect.
|
|
40
|
+
|
|
41
|
+
The key names the call _site_, not the request. A version bridge keeps the lineage id, so a migrated machine that asks something else at the same invoke site produces the same key for a different request. Cache on `callKey` **and** a fingerprint of the request, and reuse the cached result only when the request also matches. Pass `callKey` to a provider as its dedupe key for that identical request:
|
|
42
|
+
|
|
43
|
+
```ts no-check
|
|
44
|
+
const executors = {
|
|
45
|
+
generateText: async (request, info) => {
|
|
46
|
+
const fingerprint = JSON.stringify([request.model, request.prompt, request.messages]);
|
|
47
|
+
const cached = info.callKey ? results.get(info.callKey) : undefined;
|
|
48
|
+
if (cached?.fingerprint === fingerprint) return cached.result;
|
|
49
|
+
const result = await callProvider(request, { idempotencyKey: info.callKey });
|
|
50
|
+
if (info.callKey) results.set(info.callKey, { fingerprint, result });
|
|
51
|
+
return result;
|
|
52
|
+
},
|
|
53
|
+
};
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
See [The event log](event-log.md).
|
|
57
|
+
|
|
58
|
+
## AI SDK adapter
|
|
59
|
+
|
|
60
|
+
```ts no-check
|
|
61
|
+
import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
|
|
62
|
+
|
|
63
|
+
const models = { fast: openai("gpt-6-luna") };
|
|
64
|
+
const agent = setupAgent({ models /* schemas and requests */ });
|
|
65
|
+
|
|
66
|
+
await runToQuiescence(
|
|
67
|
+
createAgentRuntime(machine, { executors: createAiSdkExecutors({ models }) }),
|
|
68
|
+
{ input },
|
|
69
|
+
);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Passing the same `models` map to `setupAgent({ models })` types the machine's model refs, so a request naming a model the host does not have is a compile error. Executors are always passed explicitly. Core does not import or require the AI SDK at runtime.
|
|
73
|
+
|
|
74
|
+
`decideMode` sets how a language model answers a decision: `'object'` for one structured-output object, or `'tool'` for one tool per candidate event. The default is object mode when every payload can be represented as object variants, otherwise tool mode. In tool mode, parallel tool calls are turned off with `providerOptions` (`openai.parallelToolCalls: false`, `anthropic.disableParallelToolUse: true`), merged under the host's own settings. Decision models are unaffected. See [Coercion](decisions.md#coercion).
|
|
75
|
+
|
|
76
|
+
## OpenAI SDK adapter
|
|
77
|
+
|
|
78
|
+
`@statelyai/agent/openai` maps the same three executors onto the raw `openai` package, with no AI SDK in between.
|
|
79
|
+
|
|
80
|
+
- By default, calls that carry function tools use the Responses API: `generateText` with tools, and `decide` under `decideMode: 'tool'`. Reasoning models such as `gpt-6-luna` reject function tools on Chat Completions.
|
|
81
|
+
- Tool-free calls use Chat Completions: `generateText` without tools, `streamText`, and `decide` in object mode.
|
|
82
|
+
- `api` pins every call to one API. See the table below.
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
pnpm add openai
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import OpenAI from "openai";
|
|
90
|
+
import { createOpenAiExecutors } from "@statelyai/agent/openai";
|
|
91
|
+
|
|
92
|
+
const executors = createOpenAiExecutors({
|
|
93
|
+
client: new OpenAI(),
|
|
94
|
+
resolveModel: (modelRef) => (modelRef === "deep" ? "gpt-6.1-sol" : "gpt-6-luna"),
|
|
95
|
+
settings: {
|
|
96
|
+
deep: { reasoning_effort: "high" },
|
|
97
|
+
},
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`client` is injected, so the API key, base URL, and transport stay with the host. `openai` 5 or newer is required. It is an optional peer dependency with no version range, so an app on `openai` 4 still installs the core, and it is imported for types only. A client wrapper must forward both `responses.create` and `chat.completions.create` unless `api` pins one of them.
|
|
104
|
+
|
|
105
|
+
| `api` | Calls with function tools | Tool-free calls and object-mode `decide` |
|
|
106
|
+
| ------------- | ------------------------- | ---------------------------------------- |
|
|
107
|
+
| unset | `responses.create` | `chat.completions.create` |
|
|
108
|
+
| `"chat"` | `chat.completions.create` | `chat.completions.create` |
|
|
109
|
+
| `"responses"` | `responses.create` | `responses.create` |
|
|
110
|
+
|
|
111
|
+
- `"chat"` is for a model or OpenAI-compatible server without `/v1/responses`. `generateText` runs its tool loop on Chat Completions, and a tool-mode decision sends `tools` with `tool_choice: 'required'`.
|
|
112
|
+
- `"responses"` is for a host whose recorded traffic uses the Responses API.
|
|
113
|
+
|
|
114
|
+
`resolveModel` maps a machine's model ref to a real OpenAI model id. It defaults to identity, for machines whose refs are already ids.
|
|
115
|
+
|
|
116
|
+
`settings` carries the provider knobs that belong to the host rather than the machine, such as `reasoning_effort` or `service_tier`. Key it by model ref to give a ref a persona, or pass a function of the request to vary settings per call. Settings merge under what the request declared, so a request that set `maxOutputTokens` wins. Settings use Chat Completions names. On Responses calls:
|
|
117
|
+
|
|
118
|
+
- `reasoning_effort` becomes `reasoning.effort`.
|
|
119
|
+
- `max_completion_tokens` becomes `max_output_tokens`.
|
|
120
|
+
- `verbosity` becomes `text.verbosity`.
|
|
121
|
+
- Settings the Responses API shares by name, such as `temperature` and `service_tier`, pass through.
|
|
122
|
+
- Chat-only settings, such as `seed`, `stop`, `logprobs`, and `prediction`, are dropped. This includes a request's `seed` and `stopSequences`. Each dropped key logs one `console.warn` per `createOpenAiExecutors` instance.
|
|
123
|
+
- `store` defaults to `false`, matching Chat Completions.
|
|
124
|
+
- A sampling setting the model rejects, such as `temperature` or `top_p` on a reasoning model like `gpt-6-luna`, is dropped for that model after its first 400. The call is retried without it, and one warning is logged. The rejected request still counts against an HTTP-level budget.
|
|
125
|
+
|
|
126
|
+
Structured output sends the declared schema wrapped as `{ result, reasoning? }`, as `response_format: { type: 'json_schema' }` on Chat Completions or `text.format` on the Responses API. The parsed `result` is what the machine validates.
|
|
127
|
+
|
|
128
|
+
Decisions follow `decideMode`:
|
|
129
|
+
|
|
130
|
+
- `'object'` (default for compatible object payloads): one structured-output call whose schema is the decision object, sent with `strict: false`, since the adapter validates the answer itself.
|
|
131
|
+
- `'tool'`: one function tool per candidate event, with `tool_choice: 'required'` and `parallel_tool_calls: false`. Function tools are sent with `strict: false`, since the Responses API defaults strict mode on and arbitrary JSON Schema may fall outside it.
|
|
132
|
+
- An answer the adapter cannot read as one event comes back as `rejected`, and the runtime retries it. See [Coercion](decisions.md#coercion).
|
|
133
|
+
|
|
134
|
+
`generateText` runs the tool loop host-side. Each step that comes back with function calls runs the request's tools, appends the calls and one `function_call_output` item per result, and asks again. The replay is stateless: calls go back without their item ids, and reasoning items are left out. An incomplete turn, such as one cut off at `max_output_tokens`, never runs its calls, and an incomplete decision throws instead of choosing. A `failed` response throws on both paths, with its error code and message. The request's `maxSteps` bounds the number of OpenAI calls; the default is one, so a single-step request behaves as before. A tool that throws, a call to a tool the request did not offer, and arguments that are not JSON go back to the model as error results. The loop also ends early on a tool with no `execute` — a client-side tool, whose call is handed back with `finishReason: 'tool-calls'` and the raw response. Every step's `usage` is summed onto the one result the run aggregates. `modelCalls` reports the steps, and a loop that throws after a step records them on the error, so the run's budget counts them.
|
|
135
|
+
|
|
136
|
+
`toolChoice` maps onto `tool_choice`: `'auto'`, `'none'`, and `'required'` pass through, and `{ type: 'tool', name }` becomes `{ type: 'function', name }`. It is sent on the first step only, so a forced choice cannot re-fire every step and burn the step budget.
|
|
137
|
+
|
|
138
|
+
Messages map part by part. Text and image parts become OpenAI content parts (`image_url`, or `input_image` on the Responses API, with bytes and bare base64 wrapped in a data URL). Assistant tool-call parts become `tool_calls`, or `function_call` items. Tool results become tool messages carrying their `tool_call_id`, or `function_call_output` items. A part the adapter cannot carry, such as a file part, throws rather than being dropped.
|
|
139
|
+
|
|
140
|
+
`streamText` is text-only. A request that declares tools or a structured output schema is refused, not silently downgraded; route it to `generateText`.
|
|
141
|
+
|
|
142
|
+
Every result reports `usage` on the flat `AgentCallUsage` field names, with `reasoning_tokens` and `cached_tokens` folded onto `reasoningTokens` and `cachedInputTokens`, plus the normalized `finishReason` and the untouched response on `raw`. A Responses API response has no `finish_reason`: an `incomplete` status maps `max_output_tokens` to `'length'`, and a completed response with function calls maps to `'tool-calls'`. Streams ask for `stream_options: { include_usage: true }`, so a stream reports usage too.
|
|
143
|
+
|
|
144
|
+
## TanStack AI adapter
|
|
145
|
+
|
|
146
|
+
`@statelyai/agent/tanstack-ai` maps the same three executors onto [TanStack AI](https://tanstack.com/ai)'s `chat()` activity. Any TanStack AI text adapter works as a model: `openaiText`, `anthropicText`, `geminiText`, `ollamaText`, and the rest.
|
|
147
|
+
|
|
148
|
+
```sh
|
|
149
|
+
pnpm add @tanstack/ai @tanstack/ai-openai
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
```ts no-check
|
|
153
|
+
import { openaiText } from "@tanstack/ai-openai";
|
|
154
|
+
import { anthropicText } from "@tanstack/ai-anthropic";
|
|
155
|
+
import { createTanStackAiExecutors } from "@statelyai/agent/tanstack-ai";
|
|
156
|
+
|
|
157
|
+
const executors = createTanStackAiExecutors({
|
|
158
|
+
models: {
|
|
159
|
+
quick: openaiText("gpt-6-luna"),
|
|
160
|
+
deep: {
|
|
161
|
+
adapter: anthropicText("claude-sonnet-5"),
|
|
162
|
+
settings: { modelOptions: { thinking: { type: "enabled", budget_tokens: 4096 } } },
|
|
163
|
+
},
|
|
164
|
+
},
|
|
165
|
+
});
|
|
166
|
+
|
|
167
|
+
await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The options mirror `createAiSdkExecutors`:
|
|
171
|
+
|
|
172
|
+
- `models` maps model refs to text adapters, or to `{ adapter, settings }` pairs that give a ref a persona.
|
|
173
|
+
- `resolveModel` resolves refs dynamically, and wins over `models` when both are set.
|
|
174
|
+
- `settings` carries `chat()` options that belong to the host, such as `modelOptions`, `middleware`, or `metadata`. Pass an object for every call, or a function of the request.
|
|
175
|
+
- `decideMode` sets how a decision is answered: `'object'` (the compatible-payload default) or `'tool'`. See [Coercion](decisions.md#coercion).
|
|
176
|
+
|
|
177
|
+
Precedence is global `settings`, then the model entry's `settings`, then the request's own generation settings. `modelOptions` merge key by key.
|
|
178
|
+
|
|
179
|
+
TanStack AI has no portable sampling or tool-choice options; each provider adapter names its own `modelOptions`. The adapter maps a request's `temperature`, `topP`, `topK`, `maxOutputTokens`, `seed`, `stopSequences`, and `toolChoice` by provider:
|
|
180
|
+
|
|
181
|
+
- `openai`: `temperature`, `top_p`, `max_output_tokens`, and `tool_choice`. The Responses API has no `top_k`, `seed`, or `stop`, so those are dropped. TanStack AI's OpenAI adapter also drops `temperature` and `top_p` for reasoning models.
|
|
182
|
+
- `anthropic`: `temperature`, `top_p`, `top_k`, `max_tokens`, `stop_sequences`, and `tool_choice`. `seed` is dropped.
|
|
183
|
+
- `gemini`: `temperature`, `topP`, `topK`, `maxOutputTokens`, `seed`, `stopSequences`, and `toolConfig`.
|
|
184
|
+
- Any other provider gets none of them. Map them in a `settings` function, which receives the request.
|
|
185
|
+
|
|
186
|
+
The rest of the contract matches the other adapters:
|
|
187
|
+
|
|
188
|
+
- Structured output passes the declared schema, wrapped as `{ result, reasoning? }`, as `chat()`'s `outputSchema`. A structured run cut off by the token limit is an `AgentTruncatedError`.
|
|
189
|
+
- Tools run in `chat()`'s own loop, in `generateText` and `streamText` alike. The request's `maxSteps` bounds the model turns; the default is one. A tool with no `execute` stops the run at its call, with `finishReason: 'tool-calls'`.
|
|
190
|
+
- A forced `toolChoice` applies to the first model turn only, so the model can answer after the tool runs.
|
|
191
|
+
- `generateText` and `streamText` return the run's response `messages`: each turn's assistant text and tool calls, and the tool results fed back. Append them to a conversation and they replay into the next request.
|
|
192
|
+
- Decisions with compatible object payloads use one structured-output object by default; incompatible payloads default to tool mode. Under `decideMode: 'tool'` they offer one tool per candidate event, with no `execute`, so the run stops at the model's first call. The tool choice is forced where the provider supports it, and an answer with more than one call is rejected.
|
|
193
|
+
- System messages and the request's `system` become `systemPrompts`, since TanStack AI messages have no `system` role. Image parts become `url` or base64 `data` sources; other part types throw.
|
|
194
|
+
- Every result reports `usage` summed over the run's model turns, the normalized `finishReason`, and every chunk the run produced on `raw`. A provider error arrives as a `RUN_ERROR` chunk and is thrown with its `code`.
|
|
195
|
+
|
|
196
|
+
`@tanstack/ai` is an optional peer dependency. To stream a run to a `useChat` client over TanStack AI's wire protocol, see [tanstack-ai-stream](https://github.com/statelyai/agent/blob/next/examples/tanstack-ai-stream).
|
|
197
|
+
|
|
198
|
+
## Finish reasons and truncation
|
|
199
|
+
|
|
200
|
+
An executor result may report `finishReason`, normalized to `'stop'`, `'length'`, `'tool-calls'`, `'content-filter'`, or `'other'`. Map the provider's own vocabulary onto those five and leave the raw value on `raw`. `runToQuiescence` lifts the normalized reason onto the `request.end` trace event, beside `usage`.
|
|
201
|
+
|
|
202
|
+
A `'length'` finish is the host's to interpret, because only the host sees it:
|
|
203
|
+
|
|
204
|
+
- Text request: return the text the model did produce, with `finishReason: 'length'`. Do not throw.
|
|
205
|
+
- Structured request: there is no usable output, so throw `AgentTruncatedError` with the `cause` and, when the model produced something, `partialOutput`.
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
import { AgentTruncatedError } from "@statelyai/agent";
|
|
209
|
+
import type { AgentRequestExecutorInfo, AgentTextRequest } from "@statelyai/agent";
|
|
210
|
+
|
|
211
|
+
function onTruncated(
|
|
212
|
+
request: AgentTextRequest,
|
|
213
|
+
info: AgentRequestExecutorInfo | undefined,
|
|
214
|
+
cause: unknown,
|
|
215
|
+
partialText?: string,
|
|
216
|
+
): never {
|
|
217
|
+
// `request.name` is optional, and `requestName` is required. `partialOutput`
|
|
218
|
+
// is set only when the provider returned some text, so the error shape
|
|
219
|
+
// stays the same whether or not there was a partial answer.
|
|
220
|
+
const requestName = request.name ?? "(unnamed)";
|
|
221
|
+
throw new AgentTruncatedError(`Request '${requestName}' hit the output token limit.`, {
|
|
222
|
+
requestName,
|
|
223
|
+
requestId: info?.requestId,
|
|
224
|
+
...(partialText !== undefined ? { partialOutput: partialText } : {}),
|
|
225
|
+
cause,
|
|
226
|
+
});
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
The error's code is `'truncated'`, which is what a machine's `onError` branches on. Core never throws it.
|
|
231
|
+
|
|
232
|
+
## Executor-owned structured retries
|
|
233
|
+
|
|
234
|
+
Retry policy belongs to the SDK or host executor. For example, a host may retry a tool-free AI SDK structured-output failure once while preserving the runner's abort signal:
|
|
235
|
+
|
|
236
|
+
```ts no-check
|
|
237
|
+
import { NoObjectGeneratedError } from "ai";
|
|
238
|
+
|
|
239
|
+
const aiSdk = createAiSdkExecutors({ models });
|
|
240
|
+
const executors = {
|
|
241
|
+
...aiSdk,
|
|
242
|
+
generateText: async (request, info) => {
|
|
243
|
+
try {
|
|
244
|
+
return await aiSdk.generateText(request, info);
|
|
245
|
+
} catch (error) {
|
|
246
|
+
const hasTools = Object.keys(request.tools ?? {}).length > 0;
|
|
247
|
+
if (hasTools || !NoObjectGeneratedError.isInstance(error)) throw error;
|
|
248
|
+
return aiSdk.generateText(request, info);
|
|
249
|
+
}
|
|
250
|
+
},
|
|
251
|
+
};
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Tool-bearing calls are not retried here because tools may have side effects. Use the framework's own interruption and retry facilities when available; Stately Agent forwards messages and execution to it.
|
|
255
|
+
|
|
256
|
+
## Resume events off the wire
|
|
257
|
+
|
|
258
|
+
A host that resumes a run from an HTTP request or a socket frame parses the payload at the boundary, then hands the parsed event to `runToQuiescence`:
|
|
259
|
+
|
|
260
|
+
```ts no-check
|
|
261
|
+
let event;
|
|
262
|
+
try {
|
|
263
|
+
event = parseAgentEvent(machine, await request.json());
|
|
264
|
+
} catch (error) {
|
|
265
|
+
return Response.json({ error: String(error) }, { status: 400 });
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
const result = await runToQuiescence(createAgentRuntime(machine, { store, threadId, executors }), {
|
|
269
|
+
event,
|
|
270
|
+
});
|
|
271
|
+
|
|
272
|
+
if (result.ignored) {
|
|
273
|
+
return Response.json(
|
|
274
|
+
{ error: `'${result.ignored.type}' does not apply right now` },
|
|
275
|
+
{ status: 409 },
|
|
276
|
+
);
|
|
277
|
+
}
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
- `parseAgentEvent(machineOrSnapshot, payload)` takes `unknown` and returns the event typed as the machine's event union. Give it the machine to read the event schemas `setupAgent` registered, or any snapshot of it.
|
|
281
|
+
- It throws `AgentInvalidEventPayloadError` (code `invalid-event-payload`) for a payload that is not an object with a string `type`, a reserved `@agent.*` type, or fields that fail the schema. That is the 400.
|
|
282
|
+
- It does not ask whether the current state handles the event, and `runToQuiescence` adds no check of its own.
|
|
283
|
+
- An event the resumed state has no transition for is ignored: the run settles normally and `result.ignored` holds the event. Answer 409 if the client should know nothing happened.
|
|
284
|
+
|
|
285
|
+
See [Persistence](persistence.md#resume-with-an-event-off-the-wire).
|
|
286
|
+
|
|
287
|
+
## Write your own host loop
|
|
288
|
+
|
|
289
|
+
`runAgent(machine, options)` is `createAgentRuntime(machine, options)` driven by this loop:
|
|
290
|
+
|
|
291
|
+
```ts
|
|
292
|
+
const init = { snapshot, event: { type: "APPROVE" } };
|
|
293
|
+
const runtime = createAgentRuntime(machine, { executors });
|
|
294
|
+
|
|
295
|
+
let [state, effects] = await runtime.start(init);
|
|
296
|
+
await runtime.execute(effects);
|
|
297
|
+
if (init.event !== undefined && state.status === "active") {
|
|
298
|
+
[state, effects] = runtime.transition(state, init.event);
|
|
299
|
+
await runtime.execute(effects);
|
|
300
|
+
}
|
|
301
|
+
for (let event; (event = await runtime.nextEvent());) {
|
|
302
|
+
[state, effects] = runtime.transition(state, event);
|
|
303
|
+
await runtime.execute(effects);
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
const result = await runtime.finish();
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Write the loop yourself when `runAgent` cannot express the host:
|
|
310
|
+
|
|
311
|
+
- **Non-blocking durable host.** A Durable Object woken by alarms runs one leg per wake-up and cannot await a whole run.
|
|
312
|
+
- **Events pushed mid-run with a custom loop.** A socket delivers user events while requests are in flight; hand each one to `runtime.send(event)`. Without a custom loop, `runAgent`'s [`inbox`](#runagent-inbox) does the same.
|
|
313
|
+
- **Custom stop or checkpoint policy.** Persist after selected transitions, or stop before `nextEvent()` returns `undefined`.
|
|
314
|
+
|
|
315
|
+
Each operation is described in [The runtime loop](steps.md).
|
|
316
|
+
|
|
317
|
+
### Host events mid-run
|
|
318
|
+
|
|
319
|
+
`runtime.send(event)` puts a host event in the run's mailbox, behind whatever already arrived. A `nextEvent()` parked on a pending request resolves with it; the loop applies it with `transition` like any other event.
|
|
320
|
+
|
|
321
|
+
```ts no-check
|
|
322
|
+
const runtime = createAgentRuntime(machine, { executors });
|
|
323
|
+
socket.on("message", (event) => runtime.send(event));
|
|
324
|
+
cancelButton.onclick = () => runtime.send({ type: "CANCEL" });
|
|
325
|
+
|
|
326
|
+
let [state, effects] = await runtime.start({ input });
|
|
327
|
+
await runtime.execute(effects);
|
|
328
|
+
for (let event; (event = await runtime.nextEvent());) {
|
|
329
|
+
[state, effects] = runtime.transition(state, event);
|
|
330
|
+
await runtime.execute(effects);
|
|
331
|
+
}
|
|
332
|
+
const result = await runtime.finish();
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
- **Ordering.** One FIFO with request completions, child messages, and timers. A send during a pending invoke is handed out by the next `nextEvent()`; the invoke keeps running unless the transition leaves its state, which aborts its `signal`.
|
|
336
|
+
- **Journal.** A sent event is a log entry, the same as `runAgent({ event })`. Replaying `result.events` lands on the same state.
|
|
337
|
+
- **Unhandled.** A sent event the state has no transition for is reported as `result.ignored`.
|
|
338
|
+
- **Before `start`.** Queued; the first `nextEvent()` hands it out. Returns `true`.
|
|
339
|
+
- **After the run stopped or the machine left `active`.** Dropped. Returns `false`.
|
|
340
|
+
- **After `finish`.** Throws `AgentError` `runtime-finished`.
|
|
341
|
+
- **Not read.** A send after `nextEvent()` returned `undefined` waits for another `nextEvent()`; `finish` drops it.
|
|
342
|
+
|
|
343
|
+
`send` is asynchronous: the machine moves when the loop's next `transition` applies the event. For a cancel that must take effect before the caller returns, call `transition` from outside the loop on the loop's own `state`:
|
|
344
|
+
|
|
345
|
+
```ts no-check
|
|
346
|
+
let state, effects;
|
|
347
|
+
[state, effects] = await runtime.start({ input });
|
|
348
|
+
await runtime.execute(effects);
|
|
349
|
+
|
|
350
|
+
async function cancelAll() {
|
|
351
|
+
if (state.status !== "active") return;
|
|
352
|
+
[state, effects] = runtime.transition(state, { type: "CANCEL" });
|
|
353
|
+
await runtime.execute(effects);
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
for (let event; (event = await runtime.nextEvent());) {
|
|
357
|
+
[state, effects] = runtime.transition(state, event);
|
|
358
|
+
await runtime.execute(effects);
|
|
359
|
+
}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Invariants for a direct `transition`:
|
|
363
|
+
|
|
364
|
+
- **One `state`.** The loop and the out-of-band caller read and write the same variable; a stale `state` forks the run.
|
|
365
|
+
- **Effects executed.** Pass every returned `effects` to `execute`.
|
|
366
|
+
- **Active only.** No `transition` once `state.status` is not `active`.
|
|
367
|
+
- **Loop exits on its own.** A parked `nextEvent()` returns `undefined` once the cancel stops the in-flight work.
|
|
368
|
+
|
|
369
|
+
### Abort through the machine
|
|
370
|
+
|
|
371
|
+
`options.signal` alone is a hard stop: the run settles `{ status: "error", cause: "aborted" }` and the machine sees nothing. Add `abortWith` to let the machine handle the abort, for a `cancelled` final state, cleanup invokes, or an `afterRun` hook:
|
|
372
|
+
|
|
373
|
+
```ts no-check
|
|
374
|
+
const result = await runAgent(machine, {
|
|
375
|
+
executors,
|
|
376
|
+
input,
|
|
377
|
+
signal: request.signal,
|
|
378
|
+
abortWith: { event: { type: "CANCEL" }, timeout: 5_000 },
|
|
379
|
+
});
|
|
380
|
+
// result.status === "done", result.snapshot.value === "cancelled"
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
- **On abort.** `event` is sent into the run (`runtime.send`); the run continues until the machine settles.
|
|
384
|
+
- **Abort first.** Until the machine has applied `event`, the host's direct `transition` events are dropped, including `runAgent`'s own `event`. A signal already aborted at start therefore applies `event` before anything else.
|
|
385
|
+
- **Fallback.** `cause: "aborted"` as without `abortWith` when:
|
|
386
|
+
- the state has no transition for `event`;
|
|
387
|
+
- the loop never applies it;
|
|
388
|
+
- the machine handled it but settles still `active` (an idle wait nothing will answer), immediately and without waiting for `timeout`;
|
|
389
|
+
- `timeout` ms pass while the machine is still active and working.
|
|
390
|
+
- **Journal.** The abort event is a log entry; replay reaches the same final state.
|
|
391
|
+
|
|
392
|
+
### runAgent inbox
|
|
393
|
+
|
|
394
|
+
`runAgent` returns a promise, so a host holds no runtime to `send` into. Pass an `inbox` from `createAgentInbox` instead:
|
|
395
|
+
|
|
396
|
+
```ts no-check
|
|
397
|
+
const inbox = createAgentInbox<EventOf<typeof machine>>();
|
|
398
|
+
const run = runAgent(machine, { executors, input, inbox });
|
|
399
|
+
cancelButton.onclick = () => inbox.send({ type: "CANCEL" });
|
|
400
|
+
const result = await run;
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
- **Same as `runtime.send`.** Each `inbox.send` goes to the run's mailbox and returns the same boolean. See [Host events mid-run](#host-events-mid-run).
|
|
404
|
+
- **Before start.** Queued; delivered after the init event and after `runAgent`'s own `event`. Returns `true`.
|
|
405
|
+
- **While idle.** An inbox event resumes the run, ahead of a pending `onIdle` answer; that answer is dropped. Without `onIdle`, `runAgent` returns at the first idle.
|
|
406
|
+
- **Ignored.** An inbox event the state does not handle is reported as `result.ignored`. Unlike an ignored `onIdle` answer, it does not end the `onIdle` loop.
|
|
407
|
+
- **After `runAgent` returns.** Returns `false`.
|
|
408
|
+
- **One call.** An inbox serves one `runAgent` call; reusing it throws `AgentError` `inbox-in-use`.
|
|
409
|
+
|
|
410
|
+
## Uncontrolled XState actor
|
|
411
|
+
|
|
412
|
+
`provideExecutors(machine, executors)` binds the executors onto the machine so a plain `createActor` runs it, for an application that owns the actor or embeds the agent machine in a larger XState system. See [Advanced](advanced.md).
|
|
413
|
+
|
|
414
|
+
Framework-owned concerns—storage, durable execution, retries, queues, and tool-loop interruption recovery—remain with the framework.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# Human in the loop
|
|
2
|
+
|
|
3
|
+
A human wait is an ordinary XState state with accepted events. Once no child,
|
|
4
|
+
request, or in-process timer remains active, `runToQuiescence` settles as
|
|
5
|
+
`idle`. Use `isAgentIdle(snapshot)` afterward to distinguish an intentional
|
|
6
|
+
human wait from a stuck machine.
|
|
7
|
+
|
|
8
|
+
A wait with an `after` timer (an SLA, a reminder) is not idle while that timer
|
|
9
|
+
is armed in process: the run keeps waiting for it to fire. A host that answers
|
|
10
|
+
the wait later passes `timers: { schedule, cancel }` so the run settles idle
|
|
11
|
+
with the timer handed to the host. See
|
|
12
|
+
[Host-owned timers](steps.md#host-owned-timers).
|
|
13
|
+
|
|
14
|
+
```ts no-check
|
|
15
|
+
awaitingApproval: {
|
|
16
|
+
meta: {
|
|
17
|
+
interaction: {
|
|
18
|
+
label: "Approve {draft.subject}?",
|
|
19
|
+
events: {
|
|
20
|
+
APPROVE: { label: "Approve", style: "primary" },
|
|
21
|
+
REJECT: { label: "Reject", style: "danger" }
|
|
22
|
+
},
|
|
23
|
+
textEvent: "REJECT"
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
on: {
|
|
27
|
+
APPROVE: { target: "sending" },
|
|
28
|
+
REJECT: { target: "revising" }
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Type the metadata
|
|
34
|
+
|
|
35
|
+
`setupAgent` types every state's `meta` as `AgentInteractionMeta` by default, keyed by the machine's declared events. A choice or `textEvent` that names an event the machine never declared is a compile error:
|
|
36
|
+
|
|
37
|
+
```ts no-check
|
|
38
|
+
const agentSetup = setupAgent({
|
|
39
|
+
context: contextSchema,
|
|
40
|
+
events: { APPROVE: z.object({}), REJECT: z.object({ reason: z.string() }) },
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
agentSetup.createMachine({
|
|
44
|
+
// ...
|
|
45
|
+
states: {
|
|
46
|
+
review: {
|
|
47
|
+
meta: {
|
|
48
|
+
interaction: {
|
|
49
|
+
label: "Approve {subject}?",
|
|
50
|
+
events: { APPROVE: "Approve", DECLINE: "Decline" }, // error: DECLINE is not an event
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
},
|
|
54
|
+
},
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The descriptor is an optional `interaction` with a `label` (a string with `{context.path}` interpolation, or a function of the context), an `events` map of choices, payload `choices` (an array, or a context path), and a `textEvent`. A machine that declares its own `meta` schema replaces the default; `interactionMetaSchema` is the runtime schema for the interaction shape when you build a schema pack by hand with `createAgentSchemas`.
|
|
59
|
+
|
|
60
|
+
## Payload choices
|
|
61
|
+
|
|
62
|
+
An `events` entry is one button per event type. When one event type needs several buttons, one per payload, declare `choices` instead. Each choice is a label and the full event it sends:
|
|
63
|
+
|
|
64
|
+
```ts no-check
|
|
65
|
+
voting: {
|
|
66
|
+
meta: {
|
|
67
|
+
interaction: {
|
|
68
|
+
label: "Who is the chameleon?",
|
|
69
|
+
choices: [
|
|
70
|
+
{ label: "Seat 1", event: { type: "ACCUSE", seat: 1 } },
|
|
71
|
+
{ label: "Seat 2", event: { type: "ACCUSE", seat: 2 } },
|
|
72
|
+
{ label: "Pass", event: { type: "PASS" }, style: "danger" }
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
},
|
|
76
|
+
on: { ACCUSE: { target: "revealing" }, PASS: { target: "revealing" } }
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
When the choices depend on context, keep them in a context array of the same shape and set `choices` to its path. The refund desk computes this turn's proposals on entry to `deciding`:
|
|
81
|
+
|
|
82
|
+
```ts no-check
|
|
83
|
+
deciding: {
|
|
84
|
+
entry: ({ context }) => ({ context: { choices: deskChoices(context) } }),
|
|
85
|
+
meta: {
|
|
86
|
+
interaction: {
|
|
87
|
+
label: "Turn {turn}: {notice} Choose the next step.",
|
|
88
|
+
choices: "choices" // [{ label: "Refund $240", event: { type: "ISSUE_REFUND", amount: 240 } }, ...]
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`getInteraction(snapshot).choices` lists the declared choices, inline or read from the context path:
|
|
95
|
+
|
|
96
|
+
- Labels interpolate `{context.path}` like the interaction label.
|
|
97
|
+
- Each event is checked against the machine's event schema and `snapshot.can(event)`. Only the choices the machine takes right now are listed.
|
|
98
|
+
- `choices` is present only when the state declares `choices`. The `events` list is unchanged.
|
|
99
|
+
|
|
100
|
+
Convert a pressed button back with its index in `choices`, or its label. A label that several listed choices share throws; pass the index instead:
|
|
101
|
+
|
|
102
|
+
```ts no-check
|
|
103
|
+
const first = eventFromInteraction(paused.snapshot, { choice: 0 });
|
|
104
|
+
const refund = eventFromInteraction(paused.snapshot, { choice: "Refund $240" });
|
|
105
|
+
// { type: "ISSUE_REFUND", amount: 240 }
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Free-text field
|
|
109
|
+
|
|
110
|
+
`textEvent: "REJECT"` puts the text in a `text` field. Name another field with `{ type, field }`:
|
|
111
|
+
|
|
112
|
+
```ts no-check
|
|
113
|
+
asking: {
|
|
114
|
+
meta: {
|
|
115
|
+
interaction: {
|
|
116
|
+
label: "Please confirm your identity.",
|
|
117
|
+
textEvent: { type: "IDENTITY_CLAIM", field: "claim" }
|
|
118
|
+
}
|
|
119
|
+
},
|
|
120
|
+
on: { IDENTITY_CLAIM: { target: "verifying" } }
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`getInteraction` reports `textEvent: "IDENTITY_CLAIM"` and `textField: "claim"`, and `eventFromInteraction(snapshot, { text })` returns `{ type: "IDENTITY_CLAIM", claim: text }`. `textField` is absent when the field is `text`.
|
|
125
|
+
|
|
126
|
+
## Render and validate
|
|
127
|
+
|
|
128
|
+
```ts no-check
|
|
129
|
+
const paused = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
|
|
130
|
+
|
|
131
|
+
if (paused.status === "idle") {
|
|
132
|
+
const interaction = getInteraction(paused.snapshot);
|
|
133
|
+
const event = eventFromInteraction(paused.snapshot, { type: "APPROVE" });
|
|
134
|
+
|
|
135
|
+
await storage.put(id, paused.persist());
|
|
136
|
+
return { interaction, event };
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`getInteraction` interpolates labels, collapses whitespace, and filters choices and `textEvent` through XState's currently accepted events. `eventFromInteraction` preserves fixed fields declared in interaction metadata and validates the chosen payload against the machine's event schema.
|
|
141
|
+
|
|
142
|
+
Both read event schemas from `setupAgent`, or from a plain XState machine's own `setup({ schemas: { events } })`.
|
|
143
|
+
|
|
144
|
+
Whitespace collapses because labels are usually authored as multi-line template literals and interpolated context can carry newlines of its own. Pass `{ preserveWhitespace: true }` when the label is deliberately multi-line, such as a rendered diff:
|
|
145
|
+
|
|
146
|
+
```ts no-check
|
|
147
|
+
const interaction = getInteraction(paused.snapshot, { preserveWhitespace: true });
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Both functions are typed off the snapshot, so `eventFromInteraction` returns the machine's own event union. No cast is needed to send the result back:
|
|
151
|
+
|
|
152
|
+
```ts no-check
|
|
153
|
+
const event = eventFromInteraction(paused.snapshot, { type: "APPROVE" });
|
|
154
|
+
await runToQuiescence(createAgentRuntime(machine, { executors }), {
|
|
155
|
+
snapshot: paused.persist(),
|
|
156
|
+
event,
|
|
157
|
+
});
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
When the answer arrives over the wire instead of from your own code, parse it at the boundary with `parseAgentEvent(machine, await request.json())` and pass the result as `event`. A bad payload throws, which is a 400; an event the paused state has no transition for is ignored and comes back as `result.ignored`. See [Persistence](persistence.md#resume-with-an-event-off-the-wire).
|
|
161
|
+
|
|
162
|
+
## Drive several turns
|
|
163
|
+
|
|
164
|
+
```ts no-check
|
|
165
|
+
let result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
|
|
166
|
+
|
|
167
|
+
while (result.status === "idle") {
|
|
168
|
+
const snapshot = result.persist();
|
|
169
|
+
await storage.put(id, snapshot);
|
|
170
|
+
const event = await promptUser(getInteraction(result.snapshot));
|
|
171
|
+
result = await runToQuiescence(createAgentRuntime(machine, { executors }), { snapshot, event });
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
For HTTP or queue-based applications, persist `result.persist()` and resume in
|
|
176
|
+
a later request with a fresh runtime and `{ snapshot, event }`. Storage remains
|
|
177
|
+
framework-owned.
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Stately Agent
|
|
2
|
+
|
|
3
|
+
Stately Agent is XState plus typed model requests, decisions, and host executors. The state machine remains the single portable agent-logic artifact.
|
|
4
|
+
|
|
5
|
+
## Mental model
|
|
6
|
+
|
|
7
|
+
- XState owns states, events, actors, snapshots, persistence semantics, inspection, timers, parallelism, and durable execution.
|
|
8
|
+
- Stately Agent owns model request logic, decision constraints, executor binding, interactions, streaming, eval helpers, and Agent-specific lint.
|
|
9
|
+
- The host framework owns storage, retries, queues, interruption recovery, and provider SDK behavior.
|
|
10
|
+
|
|
11
|
+
## Start here
|
|
12
|
+
|
|
13
|
+
- Greenfield, a new agent: [Quickstart](quickstart.md), then [Thinking in state machines](thinking-in-state-machines.md) or a copied [agent pattern](patterns.md).
|
|
14
|
+
- Brownfield, an existing agent loop: [Migrating from a loop](from-a-loop.md), or the shipped `loop-to-machine` skill in `node_modules/@statelyai/agent/skills/`.
|
|
15
|
+
- Brownfield, an existing async workflow: [Strangler-fig retrofit](strangler-fig.md). Wrap it unchanged with `wrapWorkflow`, then move one phase at a time into states, checked with `checkParity`.
|
|
16
|
+
- [Choosing a run mode](choosing-a-run-mode.md)
|
|
17
|
+
- [Advanced: bare XState actors and hand-written executors](advanced.md)
|
|
18
|
+
|
|
19
|
+
## Core APIs
|
|
20
|
+
|
|
21
|
+
| API | Purpose |
|
|
22
|
+
| ------------------------------------------- | -------------------------------------------------------------------------- |
|
|
23
|
+
| `runAgent` | Run a machine to done or idle; the default entry point |
|
|
24
|
+
| `setupAgent` | Schema-first XState setup with Agent request actors |
|
|
25
|
+
| `createAgentRuntime` | Advanced, own the loop: bind executors, expose one durable transition loop |
|
|
26
|
+
| `runToQuiescence` | Advanced, own the loop: drive a runtime to done, idle, or error |
|
|
27
|
+
| `getInteraction` / `eventFromInteraction` | Render and validate human interactions |
|
|
28
|
+
| `decideNext` | Ask a model for one event a plain XState machine accepts |
|
|
29
|
+
| `describeMachine` | Render a machine as plain text for a model |
|
|
30
|
+
| `wrapWorkflow` | Wrap an existing async workflow, unchanged, as a machine |
|
|
31
|
+
| `isAgentIdle` | Distinguish a human wait from a stuck settled machine |
|
|
32
|
+
| `ContextOf` / `EventOf` / other `*Of` types | Extract setup and machine types |
|
|
33
|
+
|
|
34
|
+
## Entry points
|
|
35
|
+
|
|
36
|
+
| Entry | Purpose |
|
|
37
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------ |
|
|
38
|
+
| `@statelyai/agent` | Authoring, running, human interaction, and the executor contract |
|
|
39
|
+
| `@statelyai/agent/testing` | `lintAgentMachine`, `simulateAgent`, `canReach`, `checkParity`, trajectories, seams |
|
|
40
|
+
| `@statelyai/agent/log` | The event log: `replay`, `forkEventLog`, `getDecisionAttempts`, hand-built entries, stores |
|
|
41
|
+
| `@statelyai/agent/ai-sdk` | `createAiSdkExecutors`: the Vercel AI SDK adapter, for language and decision models |
|
|
42
|
+
| `@statelyai/agent/openai` | Executors over the raw `openai` package |
|
|
43
|
+
| `@statelyai/agent/tanstack-ai` | `createTanStackAiExecutors`, the TanStack AI adapter |
|
|
44
|
+
| `@statelyai/agent/machines` | Preset machines: tool loop, sequential, parallel, router, supervisor, handoff |
|
|
45
|
+
| `@statelyai/agent/otel` | OpenTelemetry trace handler |
|
|
46
|
+
| `@statelyai/agent/validate` | JSON workflow config validation and `verifyAgentConfig` pre-run gates |
|
|
47
|
+
|
|
48
|
+
Core has no runtime dependency on the AI SDK.
|