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

package/dist/index.js

@@ -40,7 +40,7 @@ module.exports = __toCommonJS(src_exports);
 // src/agent.ts
 var import_xstate4 = require("xstate");
 
-// src/planners/simple.ts
+// src/strategies/simple.ts
 var import_ai3 = require("ai");
 
 // src/utils.ts
@@ -79,6 +79,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);
@@ -110,12 +119,16 @@ 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
 var import_xstate3 = require("xstate");
 
+// src/text.ts
+var import_ai = require("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 `
@@ -126,7 +139,6 @@ ${data.goal}
 };
 
 // src/text.ts
-var import_ai = require("ai");
 var import_xstate = require("xstate");
 async function getMessages(agent, prompt, options) {
   let messages = [];
@@ -215,35 +227,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 (0, import_xstate2.fromPromise)(async ({ input, self }) => {
@@ -257,19 +280,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) {
@@ -315,37 +336,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 (0, import_ai3.generateText)({
     ...rest,
@@ -369,7 +383,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,
@@ -486,12 +501,11 @@ var agentLogic = (0, import_xstate4.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;
       }
@@ -506,7 +520,7 @@ var agentLogic = (0, import_xstate4.fromTransition)(
     feedback: [],
     messages: [],
     observations: [],
-    plans: []
+    decisions: []
   })
 );
 function createAgent({
@@ -515,7 +529,8 @@ function createAgent({
   model,
   events,
   context,
-  planner = simplePlanner,
+  episodeId,
+  strategy = simpleStrategy,
   logic = agentLogic
 }) {
   return new Agent({
@@ -523,9 +538,10 @@ function createAgent({
     context,
     events,
     description,
-    planner,
+    strategy,
     model,
-    logic
+    logic,
+    episodeId
   });
 }
 var Agent = class extends import_xstate4.Actor {
@@ -538,17 +554,18 @@ var Agent = class extends import_xstate4.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();
   }
   /**
@@ -557,6 +574,12 @@ var Agent = class extends import_xstate4.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.
    */
@@ -579,8 +602,8 @@ var Agent = class extends import_xstate4.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
     };
@@ -619,17 +642,17 @@ var Agent = class extends import_xstate4.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;
@@ -639,15 +662,16 @@ var Agent = class extends import_xstate4.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;
@@ -657,11 +681,14 @@ var Agent = class extends import_xstate4.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);
       }
@@ -669,10 +696,10 @@ var Agent = class extends import_xstate4.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 {
@@ -690,11 +717,14 @@ var Agent = class extends import_xstate4.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);
@@ -710,14 +740,14 @@ var Agent = class extends import_xstate4.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);
   }
 };