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

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,12 +83,19 @@ 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 = [
+    data.stateValue ? wrapInXml("stateValue", JSON.stringify(data.stateValue)) : void 0,
     data.context ? wrapInXml("context", JSON.stringify(data.context)) : void 0
   ].filter(Boolean).join("\n");
   return `
@@ -90,10 +106,6 @@ ${data.goal}
 };
 
 // src/text.ts
-import {
-  generateText,
-  streamText
-} from "ai";
 import {
   fromObservable,
   fromPromise,
@@ -186,35 +198,46 @@ 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;
+  const minimalState = {
+    value: state.value,
+    context: state.context
+  };
   while (attempts++ < maxAttempts) {
-    plan = await planner(agent, {
+    decision = await strategy(agent, {
       model,
       goal,
-      events,
-      state,
+      events: filteredEventSchemas,
+      state: minimalState,
       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 }) => {
@@ -228,19 +251,17 @@ function fromDecision(agent, defaultInput) {
       ...defaultInput,
       ...inputObject
     };
-    const state = {
-      value: snapshot.value,
-      context: resolvedInput.context
-    };
-    const plan = await agentDecide(agent, {
+    const decision = await agentDecide(agent, {
       machine: parentRef.logic,
-      state,
+      state: snapshot,
       execute: async (event) => {
         parentRef.send(event);
       },
-      ...resolvedInput
+      ...resolvedInput,
+      // @ts-ignore
+      messages: resolvedInput.messages
     });
-    return plan;
+    return decision;
   });
 }
 function getToolMap(_agent, input) {
@@ -286,37 +307,30 @@ 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({
+    stateValue: input.state.value,
+    context: input.context ?? input.state.context,
     goal: input.goal
   });
   const messages = await getMessages(agent, prompt, input);
   const model = input.model ? agent.wrap(input.model) : agent.model;
-  const {
-    state,
-    machine,
-    previousPlan,
-    events,
-    goal,
-    model: _,
-    ...rest
-  } = input;
-  const machineState = input.machine ? input.machine.resolveState({
+  const { state, machine, events, goal, model: _, ...rest } = input;
+  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 +354,8 @@ async function simplePlanner(agent, input) {
     return void 0;
   }
   return {
-    planner: "simple",
+    id: randomId(),
+    strategy: "simple",
     goal: input.goal,
     goalState: input.state,
     nextEvent: singleResult.result,
@@ -459,12 +474,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 +493,7 @@ var agentLogic = fromTransition(
     feedback: [],
     messages: [],
     observations: [],
-    plans: []
+    decisions: []
   })
 );
 function createAgent({
@@ -488,7 +502,8 @@ function createAgent({
   model,
   events,
   context,
-  planner = simplePlanner,
+  episodeId,
+  strategy = simpleStrategy,
   logic = agentLogic
 }) {
   return new Agent({
@@ -496,9 +511,10 @@ function createAgent({
     context,
     events,
     description,
-    planner,
+    strategy,
     model,
-    logic
+    logic,
+    episodeId
   });
 }
 var Agent = class extends Actor {
@@ -511,17 +527,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 +547,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.
    */
@@ -552,8 +575,8 @@ var Agent = class extends Actor {
   addFeedback(feedbackInput) {
     const feedback = {
       ...feedbackInput,
+      comment: feedbackInput.comment ?? void 0,
       attributes: { ...feedbackInput.attributes },
-      reward: feedbackInput.reward ?? 0,
       timestamp: feedbackInput.timestamp ?? Date.now(),
       episodeId: this.episodeId
     };
@@ -592,17 +615,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;
@@ -612,15 +635,16 @@ var Agent = class extends Actor {
     const agent = this;
     async function handleObservation(observationInput) {
       const observation = agent.addObservation(observationInput);
-      const input = getInput?.(observation);
-      if (input) {
-        const res = await agentDecide(agent, {
+      const interactInput = getInput?.(observation);
+      if (interactInput) {
+        const decision = await agentDecide(agent, {
           machine,
           state: observation.state,
-          ...input
+          ...interactInput
         });
-        if (res?.nextEvent) {
-          actorRef.send(res.nextEvent);
+        if (decision?.nextEvent) {
+          decision.nextEvent["_decision"] = decision.id;
+          actorRef.send(decision.nextEvent);
         }
       }
       prevState = observationInput.state;
@@ -630,11 +654,14 @@ var Agent = class extends Actor {
         if (!subscribed || inspEvent.actorRef !== actorRef || inspEvent.type !== "@xstate.snapshot") {
           return;
         }
+        const decisionId = inspEvent.event["_decision"];
+        const decision = decisionId ? agent.getDecisions().find((d) => d.id === decisionId) : void 0;
         const observationInput = {
           event: inspEvent.event,
           prevState,
           state: inspEvent.snapshot,
-          machine: actorRef.src
+          machine: actorRef.src,
+          goal: decision?.goal
         };
         await handleObservation(observationInput);
       }
@@ -642,10 +669,10 @@ 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
+        machine: actorRef.src,
+        goal: void 0
       });
     }
     return {
@@ -663,11 +690,14 @@ var Agent = class extends Actor {
         if (inspEvent.actorRef !== actorRef || inspEvent.type !== "@xstate.snapshot") {
           return;
         }
+        const decisionId = inspEvent.event["_decision"];
+        const decision = decisionId ? this.getDecisions().find((d) => d.id === decisionId) : void 0;
         const observationInput = {
           event: inspEvent.event,
           prevState,
           state: inspEvent.snapshot,
-          machine: actorRef.src
+          machine: actorRef.src,
+          goal: decision?.goal
         };
         prevState = observationInput.state;
         this.addObservation(observationInput);
@@ -683,14 +713,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,92 +1,40 @@
 import { z } from 'zod';
-import { createAgent, fromDecision } from '../src';
+import { createAgent } from '../src';
 import { openai } from '@ai-sdk/openai';
-import { assign, createActor, log, setup } from 'xstate';
-import { fromTerminal } from './helpers/helpers';
+import { getFromTerminal } from './helpers/helpers';
+import { chainOfThoughtStrategy } from '../src/strategies/chainOfThought';
 
 const agent = createAgent({
   id: 'chain-of-thought',
-  model: openai('gpt-4o-mini'),
+  model: openai('gpt-4o'),
   events: {
-    'agent.think': z.object({
-      thought: z
-        .string()
-        .describe('The thought process to answering the question'),
-    }),
     'agent.answer': z.object({
       answer: z.string().describe('The answer to the question'),
     }),
   },
   context: {
     question: z.string().nullable(),
-    thought: z.string().nullable(),
   },
+  strategy: chainOfThoughtStrategy,
 });
 
-const machine = setup({
-  types: agent.types,
-  actors: { getFromTerminal: fromTerminal },
-}).createMachine({
-  initial: 'asking',
-  context: {
-    question: null,
-    thought: null,
-  },
-  states: {
-    asking: {
-      invoke: {
-        src: 'getFromTerminal',
-        input: 'What would you like to ask?',
-        onDone: {
-          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',
-        },
-      },
-    },
-    answering: {
-      on: {
-        'agent.answer': {
-          actions: log(({ event }) => `Answer: ${event.answer}`),
-          target: 'answered',
-        },
+// agent.onMessage((msg) => console.log(msg.content));
+
+async function main() {
+  const msg = await getFromTerminal('what?');
+
+  const decision = await agent.decide({
+    messages: agent.getMessages(),
+    goal: 'Answer the question.',
+    state: {
+      value: 'thinking',
+      context: {
+        question: msg,
       },
     },
-    answered: {
-      type: 'final',
-    },
-  },
-});
+  });
 
-const actor = createActor(machine).start();
+  console.log(decision?.nextEvent?.answer);
+}
 
-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',
-      context: obs.state.context,
-      messages: agent.getMessages(),
-    };
-  }
-});
+main();

package/examples/customer-service-sim.ts

@@ -1,4 +1,4 @@
-import { createAgent, fromDecision } from '../src';
+import { createAgent, EventFromAgent, 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,
+      | EventFromAgent<typeof customerServiceAgent>
+      | EventFromAgent<typeof customerAgent>,
   },
   actors: {
     customerService: fromDecision(customerServiceAgent),

package/examples/email.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createAgent, fromDecision } from '../src';
+import { ContextFromAgent, createAgent, EventFromAgent } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, setup } from 'xstate';
 import { fromTerminal } from './helpers/helpers';
@@ -27,12 +27,12 @@ const agent = createAgent({
 
 const machine = setup({
   types: {
-    events: agent.types.events,
+    events: {} as EventFromAgent<typeof agent>,
     input: {} as {
       email: string;
       instructions: string;
     },
-    context: agent.types.context,
+    context: {} as ContextFromAgent<typeof agent>,
   },
   actors: { getFromTerminal: fromTerminal },
 }).createMachine({
@@ -101,14 +101,12 @@ agent.interact(actor, ({ state }) => {
   if (state.matches('checking')) {
     return {
       goal: 'Respond to the email given the instructions and the provided clarifications. If not enough information is provided, ask for clarification. Otherwise, if you are absolutely sure that there is no ambiguous or missing information, create and submit a response email.',
-      context: state.context,
     };
   }
 
   if (state.matches('submitting')) {
     return {
       goal: 'Create and submit an email based on the instructions.',
-      context: state.context,
     };
   }
 });

package/examples/example.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createAgent, fromDecision, fromText } from '../src';
+import { createAgent, EventFromAgent, 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 EventFromAgent<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, EventFromAgent, 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 EventFromAgent<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,
@@ -186,40 +186,40 @@ const jokeMachine = setup({
 
 const actor = createActor(jokeMachine);
 
-agent.interact(actor, (observed) => {
-  if (observed.state.matches('tellingJoke')) {
+agent.interact(actor, ({ state }) => {
+  if (state.matches('tellingJoke')) {
     return {
       goal: 'Tell me a joke about the topic. Do not make any joke that is not relevant to the topic.',
       context: {
-        topic: observed.state.context.topic,
+        topic: state.context.topic,
       },
     };
   }
 
-  if (observed.state.matches('relevance')) {
+  if (state.matches('relevance')) {
     return {
       goal: 'An irrelevant joke has no reference to the topic. If the last joke is completely irrelevant to the topic, ask for a new joke topic. Otherwise, continue.',
       context: {
-        topic: observed.state.context.topic,
-        lastJoke: observed.state.context.jokes.at(-1),
+        topic: state.context.topic,
+        lastJoke: state.context.jokes.at(-1),
       },
     };
   }
 
-  if (observed.state.matches('rateJoke')) {
+  if (state.matches('rateJoke')) {
     return {
       goal: 'Rate the last joke on a scale of 1 to 10.',
       context: {
-        lastJoke: observed.state.context.jokes.at(-1),
+        lastJoke: state.context.jokes.at(-1),
       },
     };
   }
 
-  if (observed.state.matches('decide')) {
+  if (state.matches('decide')) {
     return {
       goal: 'Choose what to do next, given the previous rating of the joke.',
       context: {
-        lastRating: observed.state.context.lastRating,
+        lastRating: state.context.lastRating,
       },
     };
   }