@statelyai/agent 2.0.0-next.1 → 2.0.0-next.2

package/dist/index.mjs

@@ -4,7 +4,7 @@ import {
   fromTransition
 } from "xstate";
 
-// src/planners/simple.ts
+// src/strategies/simple.ts
 import { generateText as generateText2 } from "ai";
 
 // src/utils.ts
@@ -43,6 +43,15 @@ function getAllMachineTransitions(stateNode) {
 function wrapInXml(tagName, content) {
   return `<${tagName}>${content}</${tagName}>`;
 }
+function convertToXml(obj) {
+  return Object.entries(obj).map(([key, value]) => {
+    if (typeof value === "object" && value !== null) {
+      return wrapInXml(key, convertToXml(value));
+    } else {
+      return wrapInXml(key, value);
+    }
+  }).join("");
+}
 function randomId(prefix) {
   const timestamp = Date.now().toString(36);
   const random = Math.random().toString(36).substring(2, 9);
@@ -74,9 +83,15 @@ function isMachineActor(actor) {
   return "src" in actor && typeof actor.src === "object" && actor.src !== null && "definition" in actor.src;
 }
 
-// src/planners/simple.ts
+// src/strategies/simple.ts
 import { getNextSnapshot } from "xstate";
 
+// src/text.ts
+import {
+  generateText,
+  streamText
+} from "ai";
+
 // src/templates/defaultText.ts
 var defaultTextTemplate = (data) => {
   const preamble = [
@@ -90,10 +105,6 @@ ${data.goal}
 };
 
 // src/text.ts
-import {
-  generateText,
-  streamText
-} from "ai";
 import {
   fromObservable,
   fromPromise,
@@ -186,35 +197,42 @@ async function agentDecide(agent, options) {
     ...options
   };
   const {
-    planner = simplePlanner,
+    strategy = agent.strategy,
     goal,
+    allowedEvents,
     events = agent.events,
     state,
     machine,
     model = agent.model,
     messages,
-    ...otherPlanInput
+    ...otherDecideInput
   } = resolvedOptions;
+  const filteredEventSchemas = allowedEvents ? Object.fromEntries(
+    Object.entries(events).filter(([key]) => {
+      return allowedEvents.includes(key);
+    })
+  ) : events;
   let attempts = 0;
   const maxAttempts = resolvedOptions.maxAttempts ?? 2;
-  let plan;
+  let decision;
   while (attempts++ < maxAttempts) {
-    plan = await planner(agent, {
+    decision = await strategy(agent, {
       model,
       goal,
-      events,
+      events: filteredEventSchemas,
       state,
       machine,
       messages,
       // TODO: fix UIMessage thing
-      ...otherPlanInput
+      ...otherDecideInput
     });
-    if (plan?.nextEvent) {
-      agent.addPlan(plan);
-      await resolvedOptions.execute?.(plan.nextEvent);
+    if (decision?.nextEvent) {
+      agent.addDecision(decision);
+      await resolvedOptions.execute?.(decision.nextEvent);
+      break;
     }
   }
-  return plan;
+  return decision;
 }
 function fromDecision(agent, defaultInput) {
   return fromPromise2(async ({ input, self }) => {
@@ -232,15 +250,18 @@ function fromDecision(agent, defaultInput) {
       value: snapshot.value,
       context: resolvedInput.context
     };
-    const plan = await agentDecide(agent, {
+    const decision = await agentDecide(agent, {
       machine: parentRef.logic,
-      state,
+      state: snapshot,
+      context: resolvedInput.context,
       execute: async (event) => {
         parentRef.send(event);
       },
-      ...resolvedInput
+      ...resolvedInput,
+      // @ts-ignore
+      messages: resolvedInput.messages
     });
-    return plan;
+    return decision;
   });
 }
 function getToolMap(_agent, input) {
@@ -286,37 +307,38 @@ function getToolMap(_agent, input) {
   return toolMap;
 }
 
-// src/planners/simple.ts
-var simplePlannerPromptTemplate = (data) => {
+// src/strategies/simple.ts
+var simpleStrategyPromptTemplate = (data) => {
   return `
-${defaultTextTemplate(data)}
+${convertToXml(data)}
 
 Make at most one tool call to achieve the above goal. If the goal cannot be achieved with any tool calls, do not make any tool call.
   `.trim();
 };
-async function simplePlanner(agent, input) {
+async function simpleStrategy(agent, input) {
   const toolMap = getToolMap(agent, input);
   if (!toolMap) {
     return void 0;
   }
-  const prompt = simplePlannerPromptTemplate({
-    context: input.state.context,
+  const prompt = simpleStrategyPromptTemplate({
+    context: input.context,
     goal: input.goal
   });
   const messages = await getMessages(agent, prompt, input);
   const model = input.model ? agent.wrap(input.model) : agent.model;
   const {
     state,
+    context,
     machine,
-    previousPlan,
+    prevDecision,
     events,
     goal,
     model: _,
     ...rest
   } = input;
-  const machineState = input.machine ? input.machine.resolveState({
+  const machineState = input.machine && input.state ? input.machine.resolveState({
     ...input.state,
-    context: input.state.context
+    context: input.state.context ?? {}
   }) : void 0;
   const result = await generateText2({
     ...rest,
@@ -340,7 +362,7 @@ async function simplePlanner(agent, input) {
     return void 0;
   }
   return {
-    planner: "simple",
+    strategy: "simple",
     goal: input.goal,
     goalState: input.state,
     nextEvent: singleResult.result,
@@ -459,12 +481,11 @@ var agentLogic = fromTransition(
         });
         break;
       }
-      case "agent.plan": {
-        state.plans.push(event.plan);
+      case "agent.decision": {
+        state.decisions.push(event.decision);
         emit({
-          type: "plan",
-          // @ts-ignore TODO: fix types in XState
-          plan: event.plan
+          type: "decision",
+          decision: event.decision
         });
         break;
       }
@@ -479,7 +500,7 @@ var agentLogic = fromTransition(
     feedback: [],
     messages: [],
     observations: [],
-    plans: []
+    decisions: []
   })
 );
 function createAgent({
@@ -488,7 +509,8 @@ function createAgent({
   model,
   events,
   context,
-  planner = simplePlanner,
+  episodeId,
+  strategy = simpleStrategy,
   logic = agentLogic
 }) {
   return new Agent({
@@ -496,9 +518,10 @@ function createAgent({
     context,
     events,
     description,
-    planner,
+    strategy,
     model,
-    logic
+    logic,
+    episodeId
   });
 }
 var Agent = class extends Actor {
@@ -511,17 +534,18 @@ var Agent = class extends Actor {
     model,
     events,
     context,
-    planner = simplePlanner
+    episodeId,
+    strategy = simpleStrategy
   }) {
     super(logic);
     this.model = model;
-    this.episodeId = id ?? randomId();
+    this.episodeId = episodeId ?? randomId("episode-");
     this.name = name;
     this.description = description;
     this.events = events;
     this.context = context;
-    this.planner = planner;
-    this.types = {};
+    this.strategy = strategy;
+    this.id = id ?? randomId();
     this.start();
   }
   /**
@@ -530,6 +554,12 @@ var Agent = class extends Actor {
   onMessage(fn) {
     return this.on("message", (ev) => fn(ev.message));
   }
+  /**
+   * Called whenever the agent (LLM assistant) receives some feedback.
+   */
+  onFeedback(fn) {
+    return this.on("feedback", (ev) => fn(ev.feedback));
+  }
   /**
    * Retrieves messages from the agent's short-term (local) memory.
    */
@@ -553,7 +583,6 @@ var Agent = class extends Actor {
     const feedback = {
       ...feedbackInput,
       attributes: { ...feedbackInput.attributes },
-      reward: feedbackInput.reward ?? 0,
       timestamp: feedbackInput.timestamp ?? Date.now(),
       episodeId: this.episodeId
     };
@@ -592,17 +621,17 @@ var Agent = class extends Actor {
   getObservations() {
     return this.getSnapshot().context.observations;
   }
-  addPlan(plan) {
+  addDecision(decision) {
     this.send({
-      type: "agent.plan",
-      plan
+      type: "agent.decision",
+      decision
     });
   }
   /**
    * Retrieves strategies from the agent's short-term (local) memory.
    */
-  getPlans() {
-    return this.getSnapshot().context.plans;
+  getDecisions() {
+    return this.getSnapshot().context.decisions;
   }
   interact(actorRef, getInput) {
     const actorRefCheck = isActorRef(actorRef) && actorRef.src;
@@ -642,8 +671,7 @@ var Agent = class extends Actor {
     if (actorRef._processingStatus === 1) {
       handleObservation({
         prevState: void 0,
-        event: { type: "" },
-        // TODO: unknown events?
+        event: void 0,
         state: actorRef.getSnapshot(),
         machine: actorRef.src
       });
@@ -683,14 +711,14 @@ var Agent = class extends Actor {
     });
   }
   /**
-   * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
+   * Resolves with an `AgentDecision` based on the information provided in the `options`, including:
    *
    * - The `goal` for the agent to achieve
    * - The observed current `state`
    * - The `machine` (e.g. a state machine) that specifies what can happen next
    * - Additional `context`
    */
-  decide(opts) {
+  async decide(opts) {
     return agentDecide(this, opts);
   }
 };

package/examples/chatbot.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createAgent, fromDecision } from '../src';
+import { createAgent, fromDecision, TypesFromAgent } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, log, setup } from 'xstate';
 import { fromTerminal } from './helpers/helpers';
@@ -19,7 +19,7 @@ const agent = createAgent({
 });
 
 const machine = setup({
-  types: agent.types,
+  types: {} as TypesFromAgent<typeof agent>,
   actors: { getFromTerminal: fromTerminal },
 }).createMachine({
   initial: 'listening',

package/examples/cot.ts

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { createAgent, fromDecision } from '../src';
+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 { chainOfThoughtStrategy } from '../src/strategies/chainOfThought';
 
 const agent = createAgent({
   id: 'chain-of-thought',
@@ -19,18 +20,17 @@ const agent = createAgent({
   },
   context: {
     question: z.string().nullable(),
-    thought: z.string().nullable(),
   },
+  strategy: chainOfThoughtStrategy,
 });
 
 const machine = setup({
-  types: agent.types,
+  types: {} as TypesFromAgent<typeof agent>,
   actors: { getFromTerminal: fromTerminal },
 }).createMachine({
   initial: 'asking',
   context: {
     question: null,
-    thought: null,
   },
   states: {
     asking: {
@@ -41,19 +41,6 @@ const machine = setup({
           actions: assign({
             question: ({ event }) => event.output,
           }),
-          target: 'thinking',
-        },
-      },
-    },
-    thinking: {
-      on: {
-        'agent.think': {
-          actions: [
-            log(({ event }) => `Thought: ${event.thought}`),
-            assign({
-              thought: ({ event }) => event.thought,
-            }),
-          ],
           target: 'answering',
         },
       },
@@ -74,14 +61,9 @@ const machine = setup({
 
 const actor = createActor(machine).start();
 
+agent.onMessage(console.log);
+
 agent.interact(actor, (obs) => {
-  if (obs.state.matches('thinking')) {
-    return {
-      goal: 'Think step-by-step about how you would answer the question',
-      context: obs.state.context,
-      messages: agent.getMessages(),
-    };
-  }
   if (obs.state.matches('answering')) {
     return {
       goal: 'Answer the question',

package/examples/customer-service-sim.ts

@@ -1,4 +1,4 @@
-import { createAgent, fromDecision } from '../src';
+import { createAgent, EventsFromAgent, fromDecision } from '../src';
 import { assign, createActor, setup } from 'xstate';
 import { openai } from '@ai-sdk/openai';
 import { z } from 'zod';
@@ -38,8 +38,8 @@ const machine = setup({
       messages: string[];
     },
     events: {} as
-      | typeof customerServiceAgent.types.events
-      | typeof customerAgent.types.events,
+      | EventsFromAgent<typeof customerServiceAgent>
+      | EventsFromAgent<typeof customerAgent>,
   },
   actors: {
     customerService: fromDecision(customerServiceAgent),

package/examples/email.ts

@@ -1,5 +1,11 @@
 import { z } from 'zod';
-import { createAgent, fromDecision } from '../src';
+import {
+  ContextFromAgent,
+  createAgent,
+  EventsFromAgent,
+  fromDecision,
+  TypesFromAgent,
+} from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, setup } from 'xstate';
 import { fromTerminal } from './helpers/helpers';
@@ -27,12 +33,12 @@ const agent = createAgent({
 
 const machine = setup({
   types: {
-    events: agent.types.events,
+    events: {} as EventsFromAgent<typeof agent>,
     input: {} as {
       email: string;
       instructions: string;
     },
-    context: agent.types.context,
+    context: {} as ContextFromAgent<typeof agent>,
   },
   actors: { getFromTerminal: fromTerminal },
 }).createMachine({

package/examples/example.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createAgent, fromDecision, fromText } from '../src';
+import { createAgent, EventsFromAgent, fromDecision, fromText } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, setup } from 'xstate';
 
@@ -18,7 +18,7 @@ const agent = createAgent({
 
 const machine = setup({
   types: {
-    events: agent.types.events,
+    events: {} as EventsFromAgent<typeof agent>,
   },
   actors: { agent: fromDecision(agent), summarizer: fromText(agent) },
 }).createMachine({

package/examples/goal.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createAgent, fromDecision } from '../src';
+import { createAgent, EventsFromAgent, fromDecision } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, log, setup } from 'xstate';
 import { fromTerminal } from './helpers/helpers';
@@ -25,7 +25,7 @@ const machine = setup({
       question: string | null;
       goal: string | null;
     },
-    events: agent.types.events,
+    events: {} as EventsFromAgent<typeof agent>,
   },
   actors: { decider, getFromTerminal: fromTerminal },
 }).createMachine({

package/examples/joke.ts

@@ -1,5 +1,5 @@
 import { assign, createActor, fromCallback, log, setup } from 'xstate';
-import { createAgent, fromDecision } from '../src';
+import { createAgent, fromDecision, TypesFromAgent } from '../src';
 import { loadingAnimation } from './helpers/loader';
 import { z } from 'zod';
 import { openai } from '@ai-sdk/openai';
@@ -81,7 +81,7 @@ const agent = createAgent({
 });
 
 const jokeMachine = setup({
-  types: agent.types,
+  types: {} as TypesFromAgent<typeof agent>,
   actors: {
     agent: fromDecision(agent),
     loader,

package/examples/jugs.ts

@@ -1,8 +1,8 @@
-import { createAgent } from '../src';
+import { createAgent, TypesFromAgent } from '../src';
 import { assign, createActor, setup } from 'xstate';
 import { openai } from '@ai-sdk/openai';
 import { z } from 'zod';
-import { experimental_createShortestPathPlanner } from '../src/planners/shortestPath';
+import { experimental_shortestPathStrategy } from '../src/strategies/shortestPath';
 
 const agent = createAgent({
   id: 'die-hard-solver',
@@ -38,10 +38,7 @@ const agent = createAgent({
 });
 
 const waterJugMachine = setup({
-  types: {
-    context: agent.types.context,
-    events: agent.types.events,
-  },
+  types: {} as TypesFromAgent<typeof agent>,
 }).createMachine({
   initial: 'solving',
   context: { jug3: 0, jug5: 0 },
@@ -106,7 +103,7 @@ async function main() {
       machine: waterJugMachine,
       goal: 'Get exactly 4 gallons of water in the 5-gallon jug',
       state: waterJugActor.getSnapshot(),
-      planner: experimental_createShortestPathPlanner(),
+      strategy: experimental_shortestPathStrategy,
     });
 
     console.log(decision?.nextEvent);

package/examples/learn-from-feedback.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { createAgent } from '../src';
+import { openai } from '@ai-sdk/openai';
+
+const agent = createAgent({
+  id: 'chatbot',
+  model: openai('gpt-4o-mini'),
+  events: {
+    submit: z.object({}).describe('Submit the form'),
+    pressEnter: z.object({}).describe('Press the enter key'),
+  },
+  context: {
+    userMessage: z.string(),
+  },
+});
+
+agent.onMessage((msg) => {
+  console.log(`Message`, msg.content);
+});
+
+agent.on('decision', ({ decision }) => {
+  console.log(`Decision: ${decision.nextEvent?.type ?? '??'}`);
+});
+
+async function main() {
+  let status = 'editing';
+  let count = 0;
+
+  while (status !== 'submitted') {
+    console.log(`Attempt ${count} - ${status}`);
+    if (count++ > 5) {
+      break;
+    }
+    switch (status) {
+      case 'editing': {
+        const relevantObservations = await agent
+          .getObservations()
+          .filter((obs) => obs.prevState.value === 'editing');
+        const relevantFeedback = await agent
+          .getFeedback()
+          .filter((f) =>
+            relevantObservations.find((o) => o.id === f.observationId)
+          );
+
+        const decision = await agent.decide({
+          goal: 'Submit the form. Take the feedback into consideration, and perform the action that will lead to the form being submitted.',
+          state: {
+            value: 'editing',
+            context: {
+              feedback: relevantFeedback.map((f) => {
+                const observation = relevantObservations.find(
+                  (o) => o.id === f.observationId
+                );
+                return {
+                  prevState: observation?.prevState,
+                  event: observation?.event,
+                  state: observation?.state,
+                  feedback: f.attributes.text,
+                };
+              }),
+            },
+          },
+        });
+
+        if (decision?.nextEvent?.type === 'submit') {
+          const observation = await agent.addObservation({
+            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,
+            goal: 'Submit the form',
+            attributes: {
+              text: 'Form not submitted',
+            },
+          });
+        } else if (decision?.nextEvent?.type === 'pressEnter') {
+          status = 'submitted';
+
+          await agent.addObservation({
+            prevState: { value: 'editing' },
+            event: { type: 'pressEnter' },
+            state: { value: 'submitted' },
+          });
+        }
+        break;
+      }
+      case 'submitted':
+        break;
+    }
+  }
+
+  console.log('End of conversation.');
+  process.exit();
+}
+
+main().catch(console.error);

package/examples/number.ts

@@ -1,4 +1,4 @@
-import { createAgent, fromDecision } from '../src';
+import { createAgent, EventsFromAgent, fromDecision } from '../src';
 import { assign, createActor, log, setup } from 'xstate';
 import { z } from 'zod';
 import { openai } from '@ai-sdk/openai';
@@ -21,7 +21,7 @@ const machine = setup({
       previousGuesses: number[];
       answer: number | null;
     },
-    events: agent.types.events,
+    events: {} as EventsFromAgent<typeof agent>,
   },
   actors: {
     agent: fromDecision(agent),

package/examples/raffle.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createAgent, fromDecision } from '../src';
+import { createAgent, EventsFromAgent, fromDecision } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, log, setup } from 'xstate';
 import { fromTerminal } from './helpers/helpers';
@@ -27,7 +27,7 @@ const machine = setup({
       lastInput: string | null;
       entries: string[];
     },
-    events: agent.types.events,
+    events: {} as EventsFromAgent<typeof agent>,
   },
   actors: { agent: fromDecision(agent), getFromTerminal: fromTerminal },
 }).createMachine({