@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/zod.cjs

@@ -0,0 +1,31 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/zod/index.ts
+/**
+* A zod schema for an `AgentMessage[]` context/input field — the typed,
+* dependency-light replacement for the hand-rolled
+* `z.custom<AgentMessage[]>((value) => Array.isArray(value))` recipe repeated
+* across machines that carry a message transcript in context.
+*
+* `AgentMessage` is a structural union (see `src/types.ts`), not something to
+* re-declare as a zod object, so this stays a `z.custom` under the hood while
+* exposing the precise `z.ZodType<AgentMessage[]>` type. Validation checks that
+* the value is an array; element shape is trusted (the library's own message
+* builders and adapters produce well-formed `AgentMessage`s).
+*
+* `zod` is an optional peer of `@statelyai/agent` — this subpath is the only
+* place it's imported, mirroring how `./ai-sdk` gates on `ai`.
+*
+* @example
+* ```ts
+* import { z } from 'zod';
+* import { zodAgentMessages } from '@statelyai/agent/zod';
+*
+* const context = z.object({ messages: zodAgentMessages() });
+* ```
+*/
+function zodAgentMessages() {
+	return zod.z.custom((value) => Array.isArray(value));
+}
+//#endregion
+exports.zodAgentMessages = zodAgentMessages;

package/dist/zod.d.cts

@@ -0,0 +1,30 @@
+import { r as AgentMessage } from "./types-C9QiMjre.cjs";
+import { z } from "zod";
+
+//#region src/zod/index.d.ts
+/**
+ * A zod schema for an `AgentMessage[]` context/input field — the typed,
+ * dependency-light replacement for the hand-rolled
+ * `z.custom<AgentMessage[]>((value) => Array.isArray(value))` recipe repeated
+ * across machines that carry a message transcript in context.
+ *
+ * `AgentMessage` is a structural union (see `src/types.ts`), not something to
+ * re-declare as a zod object, so this stays a `z.custom` under the hood while
+ * exposing the precise `z.ZodType<AgentMessage[]>` type. Validation checks that
+ * the value is an array; element shape is trusted (the library's own message
+ * builders and adapters produce well-formed `AgentMessage`s).
+ *
+ * `zod` is an optional peer of `@statelyai/agent` — this subpath is the only
+ * place it's imported, mirroring how `./ai-sdk` gates on `ai`.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { zodAgentMessages } from '@statelyai/agent/zod';
+ *
+ * const context = z.object({ messages: zodAgentMessages() });
+ * ```
+ */
+declare function zodAgentMessages(): z.ZodType<AgentMessage[]>;
+//#endregion
+export { zodAgentMessages };

package/dist/zod.d.mts

@@ -0,0 +1,30 @@
+import { r as AgentMessage } from "./types-qm00QF91.mjs";
+import { z } from "zod";
+
+//#region src/zod/index.d.ts
+/**
+ * A zod schema for an `AgentMessage[]` context/input field — the typed,
+ * dependency-light replacement for the hand-rolled
+ * `z.custom<AgentMessage[]>((value) => Array.isArray(value))` recipe repeated
+ * across machines that carry a message transcript in context.
+ *
+ * `AgentMessage` is a structural union (see `src/types.ts`), not something to
+ * re-declare as a zod object, so this stays a `z.custom` under the hood while
+ * exposing the precise `z.ZodType<AgentMessage[]>` type. Validation checks that
+ * the value is an array; element shape is trusted (the library's own message
+ * builders and adapters produce well-formed `AgentMessage`s).
+ *
+ * `zod` is an optional peer of `@statelyai/agent` — this subpath is the only
+ * place it's imported, mirroring how `./ai-sdk` gates on `ai`.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { zodAgentMessages } from '@statelyai/agent/zod';
+ *
+ * const context = z.object({ messages: zodAgentMessages() });
+ * ```
+ */
+declare function zodAgentMessages(): z.ZodType<AgentMessage[]>;
+//#endregion
+export { zodAgentMessages };

package/dist/zod.mjs

@@ -0,0 +1,30 @@
+import { z } from "zod";
+//#region src/zod/index.ts
+/**
+* A zod schema for an `AgentMessage[]` context/input field — the typed,
+* dependency-light replacement for the hand-rolled
+* `z.custom<AgentMessage[]>((value) => Array.isArray(value))` recipe repeated
+* across machines that carry a message transcript in context.
+*
+* `AgentMessage` is a structural union (see `src/types.ts`), not something to
+* re-declare as a zod object, so this stays a `z.custom` under the hood while
+* exposing the precise `z.ZodType<AgentMessage[]>` type. Validation checks that
+* the value is an array; element shape is trusted (the library's own message
+* builders and adapters produce well-formed `AgentMessage`s).
+*
+* `zod` is an optional peer of `@statelyai/agent` — this subpath is the only
+* place it's imported, mirroring how `./ai-sdk` gates on `ai`.
+*
+* @example
+* ```ts
+* import { z } from 'zod';
+* import { zodAgentMessages } from '@statelyai/agent/zod';
+*
+* const context = z.object({ messages: zodAgentMessages() });
+* ```
+*/
+function zodAgentMessages() {
+	return z.custom((value) => Array.isArray(value));
+}
+//#endregion
+export { zodAgentMessages };

package/package.json

@@ -1,52 +1,156 @@
 {
   "name": "@statelyai/agent",
-  "version": "1.1.6",
-  "description": "Stateful agents that make decisions based on finite-state machine models",
-  "main": "dist/index.js",
+  "version": "2.0.0-alpha.11",
+  "description": "State-machine authoring layer for AI agents",
+  "type": "module",
+  "main": "dist/index.cjs",
   "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./ai-sdk": {
+      "import": {
+        "types": "./dist/ai-sdk.d.mts",
+        "default": "./dist/ai-sdk.mjs"
+      },
+      "require": {
+        "types": "./dist/ai-sdk.d.cts",
+        "default": "./dist/ai-sdk.cjs"
+      }
+    },
+    "./openai-compat": {
+      "import": {
+        "types": "./dist/openai-compat.d.mts",
+        "default": "./dist/openai-compat.mjs"
+      },
+      "require": {
+        "types": "./dist/openai-compat.d.cts",
+        "default": "./dist/openai-compat.cjs"
+      }
+    },
+    "./steps": {
+      "import": {
+        "types": "./dist/steps.d.mts",
+        "default": "./dist/steps.mjs"
+      },
+      "require": {
+        "types": "./dist/steps.d.cts",
+        "default": "./dist/steps.cjs"
+      }
+    },
+    "./adapter": {
+      "import": {
+        "types": "./dist/adapter.d.mts",
+        "default": "./dist/adapter.mjs"
+      },
+      "require": {
+        "types": "./dist/adapter.d.cts",
+        "default": "./dist/adapter.cjs"
+      }
+    },
+    "./zod": {
+      "import": {
+        "types": "./dist/zod.d.mts",
+        "default": "./dist/zod.mjs"
+      },
+      "require": {
+        "types": "./dist/zod.d.cts",
+        "default": "./dist/zod.cjs"
+      }
+    },
+    "./agent-workflow.json": "./schemas/agent-workflow.json"
+  },
+  "files": [
+    "dist",
+    "schemas"
+  ],
   "keywords": [
     "ai",
     "state machine",
     "agent",
-    "rl",
-    "reinforcement learning"
+    "statechart"
   ],
-  "author": "",
+  "author": "David Khourshid <david@stately.ai>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statelyai/agent.git"
+  },
+  "homepage": "https://github.com/statelyai/agent#readme",
+  "bugs": {
+    "url": "https://github.com/statelyai/agent/issues"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "devDependencies": {
+    "@ai-sdk/openai": "^3.0.25",
+    "@anthropic-ai/sdk": "^0.109.1",
     "@changesets/changelog-github": "^0.5.0",
-    "@changesets/cli": "^2.27.8",
-    "@langchain/community": "^0.0.53",
-    "@langchain/core": "^0.1.63",
-    "@langchain/openai": "^0.0.28",
-    "@types/node": "^20.16.9",
-    "@types/object-hash": "^3.0.6",
+    "@changesets/cli": "^2.27.9",
+    "@cloudflare/workers-types": "^4.20260702.1",
+    "@inquirer/prompts": "^8.5.2",
+    "@statelyai/inspect": "^0.7.2",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.16.10",
+    "@types/react": "^19.2.17",
+    "agents": "0.11.5",
+    "ai": "^6.0.67",
+    "ajv": "^8.20.0",
     "dotenv": "^16.4.5",
-    "json-schema-to-ts": "^3.1.1",
-    "ts-node": "^10.9.2",
-    "tsup": "^8.3.0",
+    "express": "^5.2.1",
+    "hono": "^4.12.30",
+    "knip": "6.24.0",
+    "openai": "^6.45.0",
+    "oxfmt": "0.57.0",
+    "oxlint": "1.72.0",
+    "react": "^19.2.7",
+    "tsdown": "^0.21.7",
+    "tsx": "^4.21.0",
     "typescript": "^5.6.2",
-    "vitest": "^2.1.1",
-    "wikipedia": "^2.1.2",
-    "zod": "^3.23.8"
+    "vitest": "^2.1.2",
+    "xstate": "6.0.0-alpha.21",
+    "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@ai-sdk/openai": "^0.0.40",
-    "@xstate/graph": "^2.0.1",
-    "ai": "^3.4.6",
-    "object-hash": "^3.0.0",
-    "xstate": "^5.18.2"
+  "peerDependencies": {
+    "ai": "^6.0.67",
+    "xstate": ">=6.0.0-alpha.16 <6.0.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "lint": "tsc --noEmit",
+    "build": "tsdown",
+    "proto:prefabs": "tsx .scratch/prefabs/demo.ts",
+    "typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples",
+    "typecheck:src": "tsc --noEmit",
+    "typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",
+    "lint": "oxlint",
+    "format": "oxfmt src examples",
+    "format:check": "oxfmt --check src examples",
+    "knip": "knip",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm run knip",
+    "check:dts": "tsc -p fixtures/dts-consumer/tsconfig.json",
     "test": "vitest",
     "test:ci": "vitest --run",
-    "example": "ts-node examples/helpers/runner.ts",
     "changeset": "changeset",
     "release": "changeset publish",
     "version": "changeset version"

package/readme.md

@@ -1,10 +1,157 @@
 # Stately Agent
 
-Stately Agent is a flexible framework for building AI agents using state machines. Stately agents go beyond normal LLM-based AI agents by:
+**The logic layer for AI agents.**
 
-- Using state machines to guide the agent's behavior, powered by [XState](https://stately.ai/docs/xstate)
-- Incorporating **observations**, **message history**, and **feedback** to the agent decision-making and text-generation processes, as needed
-- Enabling custom **planning** abilities for agents to achieve specific goals based on state machine logic, observations, and feedback
-- Wrapping the [Vercel AI SDK](https://sdk.vercel.ai/) to easily support multiple model providers, such as OpenAI, Anthropic, Google, Mistral, Groq, Perplexity, and more
+Build agents as state machines to control exactly what the agent can do. The machine owns control flow; the model only ever picks a legal event. Testing, inspection, and visualization fall out for free.
 
-**Read the documentation: [stately.ai/docs/agents](https://stately.ai/docs/agents)**
+Stately Agent adds model requests and decisions to XState. The state machine defines what the agent can do. Your application chooses the model, runs the requests, and stores the state.
+
+Any agent workflow or loop can be modeled as a state machine. Model calls and tools run as effects inside it. The model proposes an event. The machine decides whether it is allowed and what happens next. See [how this compares to LangGraph and hand-rolling a loop](docs/comparison.md).
+
+Stately Agent 2 is in alpha. APIs may change before the stable release.
+
+[Documentation](https://stately.ai/docs/agents) · [Examples](examples/README.md) · [XState](https://github.com/statelyai/xstate)
+
+## Three ways to start
+
+- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runAgent`, test it with no API key, then eject to any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Eject to your stack](docs/eject.md).
+- **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a loop](docs/from-a-loop.md).
+- **Copy a known pattern.** ReAct, reflection, plan-and-execute, RAG, supervisor, and more, each a single runnable file you lift in 60 seconds. See [Agent patterns](docs/patterns.md).
+
+## Install
+
+<!-- install command matching the package prerelease channel and package.json peers -->
+
+```sh
+pnpm add @statelyai/agent@alpha xstate@alpha zod ai@^6 @ai-sdk/openai@^3
+```
+
+Node 22.18 or newer is required. The package is ESM-only; the library targets XState v6 alpha and stays compatible with XState v5. Provider packages must match your `ai` major: `@ai-sdk/openai@^3` pairs with `ai@^6` (a bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer).
+
+## Quick start
+
+<!-- refund decision example using setupAgent, agent.decide, a machine guard, and the AI SDK runAgent host -->
+
+This agent reviews refund requests. The model may propose an automatic refund, but the state machine owns the $100 limit.
+
+```ts
+import { openai } from "@ai-sdk/openai";
+import { runAgent, setupAgent } from "@statelyai/agent";
+import { createAiSdkExecutors, defineModels } from "@statelyai/agent/ai-sdk";
+import { z } from "zod";
+
+const models = defineModels({
+  fast: openai("gpt-5.4-mini"),
+});
+
+const agentSetup = setupAgent({
+  models,
+  context: z.object({
+    request: z.string(),
+    amount: z.number(),
+  }),
+  input: z.object({
+    request: z.string(),
+    amount: z.number(),
+  }),
+  output: z.object({
+    outcome: z.enum(["refunded", "review"]),
+  }),
+  events: {
+    AUTO_REFUND: {},
+    REVIEW: z.object({ reason: z.string() }),
+  },
+});
+
+const refundMachine = agentSetup.createMachine({
+  context: ({ input }) => input,
+  initial: "deciding",
+  states: {
+    deciding: {
+      invoke: {
+        src: "agent.decide",
+        input: ({ context }) => ({
+          model: "fast",
+          system: "Choose AUTO_REFUND for eligible requests. Otherwise choose REVIEW.",
+          prompt: `${context.request}\nAmount: $${context.amount}`,
+          allowedEvents: ["AUTO_REFUND", "REVIEW"],
+        }),
+      },
+      on: {
+        AUTO_REFUND: ({ context }) => (context.amount <= 100 ? { target: "refunded" } : undefined),
+        REVIEW: { target: "review" },
+      },
+    },
+    refunded: {
+      type: "final",
+      output: () => ({ outcome: "refunded" }),
+    },
+    review: {
+      type: "final",
+      output: () => ({ outcome: "review" }),
+    },
+  },
+});
+
+const result = await runAgent(refundMachine, {
+  input: {
+    request: "I was charged twice for the same order.",
+    amount: 75,
+  },
+  executors: createAiSdkExecutors({ models }),
+});
+
+if (result.status === "done") {
+  console.log(result.output);
+}
+```
+
+When the machine reaches `refunded`, the result is:
+
+```text
+{ outcome: 'refunded' }
+```
+
+The model chooses between the events allowed in `deciding`. The `AUTO_REFUND` transition only works when the amount is at most $100. If the model chooses it for a larger amount, the guard rejects the choice and the decision is tried again.
+
+## The state machine
+
+<!-- Add the state machine illustration here. -->
+
+The example has one model decision and two final outcomes. Real machines can add approval states, retries, parallel work, child agents, and long-running waits without changing how the control flow is represented.
+
+## Core concepts
+
+<!-- core concepts derived from setupAgent, built-in agent actors, runAgent, and XState snapshots -->
+
+- **Machines own control flow.** States, events, transitions, and guards define what can happen.
+- **Models make bounded decisions.** `agent.decide` asks a model to choose one of the events accepted by the current state.
+- **Requests are typed.** Inputs, outputs, context, and events use Standard Schema. Zod works out of the box.
+- **Your code runs the model.** `runAgent` accepts executor functions. The example uses the Vercel AI SDK adapter, but the machine does not depend on a provider.
+- **Snapshots can be stored.** An agent can stop for human input, save its XState snapshot, and resume later in another process.
+- **Machines can be checked without model calls.** Lint their structure, simulate scripted decisions, and explore paths without an API key.
+- **Agents are XState machines.** Guards, actors, parallel states, inspection, testing, and visualization work as usual.
+
+## Examples
+
+<!-- starter examples derived from examples/*/metadata.json and examples/index.ts -->
+
+- [Twenty Questions](examples/twenty-questions) shows a model choosing legal events in a loop.
+- [Go Fish](examples/go-fish) pits a model against a human while the machine enforces hidden-information game rules.
+- [Human in the loop](examples/human-in-the-loop) pauses, stores a snapshot, and resumes after review.
+- [Ticket triage](examples/triage) returns structured data from a model request.
+- [JSON agent](examples/json-agent) runs a machine defined as data.
+
+See [all examples](examples/README.md).
+
+## Learn more
+
+- [Machines](docs/machines.md)
+- [Text requests](docs/text-requests.md)
+- [Decisions](docs/decisions.md)
+- [Human in the loop](docs/human-in-the-loop.md)
+- [Testing and verification](docs/verify.md)
+- [Running on different hosts](docs/hosts.md)
+- [Eject to your stack](docs/eject.md)
+- [Agent patterns](docs/patterns.md)
+- [Migrating from a loop](docs/from-a-loop.md)