@statelyai/agent 2.0.0-next.3 → 2.0.0-next.5

package/examples/chatbot.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { createAgent, fromDecision, TypesFromAgent } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, log, setup } from 'xstate';
-import { fromTerminal } from './helpers/helpers';
+import { fromTerminal, getFromTerminal } from './helpers/helpers';
 
 const agent = createAgent({
   id: 'chatbot',
@@ -60,7 +60,11 @@ const machine = setup({
 
 const actor = createActor(machine).start();
 
-agent.interact(actor, () => ({
-  goal: 'Respond to the user, unless they want to end the conversation.',
-  messages: agent.getMessages(),
-}));
+agent.interact(actor, (s) => {
+  if (s.state.matches('responding')) {
+    return {
+      goal: 'Respond to the user, unless they want to end the conversation.',
+      messages: agent.getMessages(),
+    };
+  }
+});

package/examples/cot.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { createAgent } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { getFromTerminal } from './helpers/helpers';
-import { chainOfThoughtStrategy } from '../src/strategies/chainOfThought';
+import { chainOfThoughtPolicy } from '../src/policies/chainOfThoughtPolicy';
 
 const agent = createAgent({
   id: 'chain-of-thought',
@@ -15,11 +15,9 @@ const agent = createAgent({
   context: {
     question: z.string().nullable(),
   },
-  strategy: chainOfThoughtStrategy,
+  policy: chainOfThoughtPolicy,
 });
 
-// agent.onMessage((msg) => console.log(msg.content));
-
 async function main() {
   const msg = await getFromTerminal('what?');
 

package/examples/jugs.ts

@@ -2,7 +2,7 @@ import { createAgent, TypesFromAgent } from '../src';
 import { assign, createActor, setup } from 'xstate';
 import { openai } from '@ai-sdk/openai';
 import { z } from 'zod';
-import { experimental_shortestPathStrategy } from '../src/strategies/shortestPath';
+import { experimental_shortestPathPolicy } from '../src/policies/shortestPathPolicy';
 
 const agent = createAgent({
   id: 'die-hard-solver',
@@ -103,7 +103,7 @@ async function main() {
       machine: waterJugMachine,
       goal: 'Get exactly 4 gallons of water in the 5-gallon jug',
       state: waterJugActor.getSnapshot(),
-      strategy: experimental_shortestPathStrategy,
+      policy: experimental_shortestPathPolicy,
     });
 
     console.log(decision?.nextEvent);

package/examples/learn-from-feedback.ts

@@ -35,7 +35,7 @@ async function main() {
         const relevantFeedback = await agent
           .getFeedback()
           .filter((f) =>
-            relevantObservations.find((o) => o.id === f.observationId)
+            relevantObservations.find((o) => o.decisionId === f.decisionId)
           );
 
         const decision = await agent.decide({
@@ -79,24 +79,24 @@ Achieve the goal. Consider both exploring unknown actions (high exploration_valu
         });
 
         if (decision?.nextEvent?.type === 'submit') {
-          const observation = await agent.addObservation({
-            goal: decision.goal,
+          const observation = agent.addObservation({
+            decisionId: decision.id,
             prevState: { value: 'editing' },
             event: { type: 'submit' },
             state: { value: 'editing' },
           });
 
           // don't change the status; pretend submit button is broken
-          await agent.addFeedback({
-            observationId: observation.id,
-            score: 0,
+          agent.addFeedback({
+            decisionId: observation.id,
+            reward: 0,
             comment: 'Form not submitted',
           });
         } else if (decision?.nextEvent?.type === 'pressEnter') {
           status = 'submitted';
 
           await agent.addObservation({
-            goal: decision.goal,
+            decisionId: decision.id,
             prevState: { value: 'editing' },
             event: { type: 'pressEnter' },
             state: { value: 'submitted' },

package/examples/newspaper.ts

@@ -8,7 +8,7 @@ import { assign, createActor, fromPromise, setup } from 'xstate';
 import { createAgent } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { z } from 'zod';
-import { generateObject, generateText } from 'ai';
+import { generateObject } from 'ai';
 
 interface AgentState {
   topic: string;

package/examples/rewoo.ts

@@ -0,0 +1,62 @@
+import { setup } from 'xstate';
+
+interface RewooContext {
+  task: string;
+  planString: string;
+  steps: string[][];
+  results: Record<string, any>;
+  result: string;
+}
+
+const createTemplate = (input: { task: string }) =>
+  `For the following task, make plans that can solve the problem step by step. For each plan, indicate
+which external tool together with tool input to retrieve evidence. You can store the evidence into a 
+variable #E that can be called by later tools. (Plan, #E1, Plan, #E2, Plan, ...)
+
+Tools can be one of the following:
+(1) Google[input]: Worker that searches results from Google. Useful when you need to find short
+and succinct answers about a specific topic. The input should be a search query.
+(2) LLM[input]: A pre-trained LLM like yourself. Useful when you need to act with general 
+world knowledge and common sense. Prioritize it when you are confident in solving the problem
+yourself. Input can be any instruction.
+
+For example,
+Task: Thomas, Toby, and Rebecca worked a total of 157 hours in one week. Thomas worked x 
+hours. Toby worked 10 hours less than twice what Thomas worked, and Rebecca worked 8 hours 
+less than Toby. How many hours did Rebecca work? 
+Plan: Given Thomas worked x hours, translate the problem into algebraic expressions and solve with Wolfram Alpha.
+#E1 = WolframAlpha[Solve x + (2x - 10) + ((2x - 10) - 8) = 157]
+Plan: Find out the number of hours Thomas worked.
+#E2 = LLM[What is x, given #E1]
+Plan: Calculate the number of hours Rebecca worked.
+#E3 = Calculator[(2 * #E2 - 10) - 8]
+
+Important!
+Variables/results MUST be referenced using the # symbol!
+The plan will be executed as a program, so no coreference resolution apart from naive variable replacement is allowed.
+The ONLY way for steps to share context is by including #E<step> within the arguments of the tool.
+
+Begin! 
+Describe your plans with rich details. Each Plan should be followed by only one #E.
+
+Task: ${input.task}`;
+
+const machine = setup({
+  types: {
+    context: {} as RewooContext,
+  },
+}).createMachine({
+  context: {
+    planString: '',
+    result: '',
+    steps: [],
+    task: '',
+    results: [],
+  },
+  initial: 'plan',
+  states: {
+    plan: {},
+    tool: {},
+    solve: {},
+  },
+});

package/examples/river-crossing.ts

@@ -2,7 +2,7 @@ import { createAgent, TypesFromAgent } from '../src';
 import { assign, createActor, setup } from 'xstate';
 import { openai } from '@ai-sdk/openai';
 import { z } from 'zod';
-import { experimental_shortestPathStrategy } from '../src/strategies/shortestPath';
+import { experimental_shortestPathPolicy } from '../src/policies/shortestPathPolicy';
 
 const agent = createAgent({
   id: 'river-crossing-solver',
@@ -118,7 +118,7 @@ async function main() {
       machine: riverCrossingMachine,
       goal: 'Get all items safely across the river. Remember: Cannot leave wolf with goat or goat with cabbage unattended.',
       state: riverActor.getSnapshot(),
-      strategy: experimental_shortestPathStrategy,
+      policy: experimental_shortestPathPolicy,
     });
 
     console.log(decision?.nextEvent);

package/examples/serverless.ts

@@ -0,0 +1,71 @@
+import { openai } from '@ai-sdk/openai';
+import {
+  AgentDecision,
+  AgentFeedback,
+  AgentInsight,
+  AgentMessage,
+  AgentObservation,
+  createAgent,
+} from '../src';
+import { z } from 'zod';
+
+const agent = createAgent({
+  id: 'simple',
+  model: openai('gpt-4o-mini'),
+  events: {
+    'agent.moveLeft': z.object({}),
+    'agent.moveRight': z.object({}),
+    'agent.doNothing': z.object({}),
+  },
+});
+
+const db = {
+  observations: [] as AgentObservation<any>[],
+  feedbackItems: [] as AgentFeedback[],
+  decisions: [] as AgentDecision[],
+  messages: [] as AgentMessage[],
+  insights: [] as AgentInsight[],
+};
+
+// async function postObservation(req: unknown) {
+//   db.observations.push(req.body);
+// }
+
+async function getDecision(req: {
+  query: {
+    episodeId: string;
+    goal: string;
+  };
+}) {
+  // Get relevant observations
+  const observations = db.observations
+    .filter((obs) => obs.episodeId === req.query.episodeId)
+    .at(-1);
+  const similarObservations = db.observations.filter(
+    (obs) => obs.prevState?.value === observations?.prevState?.value
+  );
+
+  // Get relevant feedback
+  const similarFeedback = db.feedbackItems.filter((fb) => {
+    similarObservations.map((obs) => obs.decisionId).includes(fb.decisionId);
+  });
+
+  // Get relevant insights
+  const insights = db.insights.filter((insight) =>
+    similarObservations.map((obs) => obs.id).includes(insight.observationId)
+  );
+
+  const decision = await agent.decide({
+    goal: req.query.goal,
+    state: observations?.state,
+    observations: similarObservations,
+    feedback: similarFeedback,
+    insights,
+    allowedEvents: ['agent.moveLeft', 'agent.moveRight'],
+  });
+
+  db.decisions.push(...agent.getDecisions());
+  db.messages.push(...agent.getMessages());
+
+  return decision;
+}

package/examples/simple.ts

@@ -2,7 +2,7 @@ import { createAgent, fromDecision } from '../src';
 import { z } from 'zod';
 import { setup, createActor, createMachine } from 'xstate';
 import { openai } from '@ai-sdk/openai';
-import { chainOfThoughtStrategy } from '../src/strategies/chainOfThought';
+import { chainOfThoughtPolicy } from '../src/policies/chainOfThoughtPolicy';
 
 const agent = createAgent({
   id: 'simple',

package/examples/ticTacToe.ts

@@ -267,8 +267,12 @@ xAgent.interact(actor, (observed) => {
 
     console.log('Similar:', similarObservations);
 
-    const similarFeedbacks = similarObservations.map((o) => {
-      return xAgent.getFeedback().filter((f) => f.observationId === o.id);
+    const similarFeedbacks = similarObservations.map((observation) => {
+      return xAgent
+        .getFeedback()
+        .filter(
+          (feedbackItem) => feedbackItem.decisionId === observation.decisionId
+        );
     });
 
     console.log('Feedbacks:', similarFeedbacks);

package/examples/wiki.ts

@@ -21,12 +21,12 @@ agent.onMessage((msg) => {
 });
 
 async function main() {
-  const response = await generateText({
+  const result = await generateText({
     model: agent.model,
     prompt: 'When was Deadpool 2 released?',
   });
 
-  for (const msg of await response.responseMessages) {
+  for (const msg of await result.response.messages) {
     agent.addMessage(msg);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-next.3",
+  "version": "2.0.0-next.5",
   "description": "Stateful agents that make decisions based on finite-state machine models",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -18,33 +18,35 @@
     "@ai-sdk/anthropic": "^0.0.54",
     "@ai-sdk/openai": "^0.0.40",
     "@changesets/changelog-github": "^0.5.0",
-    "@changesets/cli": "^2.27.9",
+    "@changesets/cli": "^2.27.12",
     "@langchain/community": "^0.0.53",
     "@langchain/core": "^0.1.63",
     "@langchain/openai": "^0.0.28",
     "@tavily/core": "^0.0.2",
-    "@types/node": "^20.17.1",
+    "@types/node": "^20.17.17",
     "@types/object-hash": "^3.0.6",
-    "@vitest/coverage-v8": "^2.1.4",
-    "dotenv": "^16.4.5",
+    "@vitest/coverage-v8": "^2.1.9",
+    "dotenv": "^16.4.7",
     "json-schema-to-ts": "^3.1.1",
     "ts-node": "^10.9.2",
-    "tsup": "^8.3.5",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.3",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.9",
     "wikipedia": "^2.1.2",
-    "zod": "^3.23.8"
+    "zod": "^3.24.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@xstate/graph": "^2.0.1",
-    "ai": "^3.4.31",
     "ajv": "^8.17.1",
     "object-hash": "^3.0.0",
-    "xstate": "^5.18.2",
-    "zod-to-json-schema": "^3.23.5"
+    "xstate": "^5.19.2",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "peerDependencies": {
+    "ai": "^4.1.36"
   },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",

package/readme.md

@@ -8,3 +8,60 @@ Stately Agent is a flexible framework for building AI agents using state machine
 - First-class integration with the [Vercel AI SDK](https://sdk.vercel.ai/) to easily support multiple model providers, such as OpenAI, Anthropic, Google, Mistral, Groq, Perplexity, and more
 
 **Read the documentation: [stately.ai/docs/agents](https://stately.ai/docs/agents)**
+
+# Stately Agent
+
+Stately Agent is a framework for building intelligent AI agents that are guided by state machines and learn from experience. Rather than relying solely on LLM responses, agents use structured observations, feedback, and insights to make informed decisions and improve over time.
+
+## Overview
+
+Stately Agent combines state machines with reinforcement learning concepts to create agents that:
+
+- Make decisions based on clear state transitions and goals
+- Learn from past experiences and feedback
+- Generate insights about state changes
+- Improve decision-making through structured rewards
+- Support multiple decision-making policies
+
+The framework is built on [XState](https://stately.ai/docs/xstate) for state machine management and integrates with the [Vercel AI SDK](https://sdk.vercel.ai/) for flexible LLM support.
+
+## Key Concepts
+
+- **Observations**: Records of state transitions, containing:
+
+  - Previous state
+  - Event/action taken
+  - Resulting state
+  - Metadata about the transition
+
+- **Decisions**: Actions the agent chooses to take based on:
+
+  - Current state
+  - Goal state
+  - Past observations
+  - Available feedback and insights
+  - Decision-making policy
+
+- **Feedback**: Rewards or evaluations given to decisions, helping the agent learn which actions are effective
+
+- **Insights**: Additional context about state transitions, helping the agent understand cause and effect
+
+- **Episodes**: Complete sequences of state transitions, from initial state to goal state (similar to RL episodes)
+
+## Quick Start
+
+TODO
+
+## Why Stately Agent?
+
+Traditional LLM-based agents often make decisions with limited context and no ability to learn from experience. Stately Agent provides:
+
+1. **Structured Decision Making**: State machines provide clear boundaries and valid transitions
+
+2. **Learning from Experience**: Agents improve through feedback and observations
+
+3. **Contextual Awareness**: Insights and observations inform better decisions
+
+4. **Flexible Policies**: Different approaches for different needs
+
+5. **Storage Integration**: Optional persistence of experiences and learning