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

package/dist/index.mjs

@@ -4,7 +4,7 @@ import {
   fromTransition
 } from "xstate";
 
-// src/planners/simplePlanner.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);
@@ -70,10 +79,19 @@ function getTransitions(state, machine) {
   });
   return getAllTransitions(resolvedState);
 }
+function isMachineActor(actor) {
+  return "src" in actor && typeof actor.src === "object" && actor.src !== null && "definition" in actor.src;
+}
 
-// src/planners/simplePlanner.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 = [
@@ -87,10 +105,6 @@ ${data.goal}
 };
 
 // src/text.ts
-import {
-  generateText,
-  streamText
-} from "ai";
 import {
   fromObservable,
   fromPromise,
@@ -183,27 +197,42 @@ async function agentDecide(agent, options) {
     ...options
   };
   const {
-    planner = simplePlanner,
+    strategy = agent.strategy,
     goal,
+    allowedEvents,
     events = agent.events,
     state,
     machine,
     model = agent.model,
-    ...otherPlanInput
+    messages,
+    ...otherDecideInput
   } = resolvedOptions;
-  const plan = await planner(agent, {
-    model,
-    goal,
-    events,
-    state,
-    machine,
-    ...otherPlanInput
-  });
-  if (plan?.nextEvent) {
-    agent.addPlan(plan);
-    await resolvedOptions.execute?.(plan.nextEvent);
+  const filteredEventSchemas = allowedEvents ? Object.fromEntries(
+    Object.entries(events).filter(([key]) => {
+      return allowedEvents.includes(key);
+    })
+  ) : events;
+  let attempts = 0;
+  const maxAttempts = resolvedOptions.maxAttempts ?? 2;
+  let decision;
+  while (attempts++ < maxAttempts) {
+    decision = await strategy(agent, {
+      model,
+      goal,
+      events: filteredEventSchemas,
+      state,
+      machine,
+      messages,
+      // TODO: fix UIMessage thing
+      ...otherDecideInput
+    });
+    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 }) => {
@@ -221,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) {
@@ -275,46 +307,48 @@ function getToolMap(_agent, input) {
   return toolMap;
 }
 
-// src/planners/simplePlanner.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,
+    system: input.system ?? agent.description,
     model,
     messages,
     tools: toolMap,
     toolChoice: input.toolChoice ?? "required"
   });
-  result.responseMessages.forEach((m) => {
+  result.response.messages.forEach((m) => {
     const message = m;
     agent.addMessage({
       ...message,
@@ -328,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,
@@ -361,13 +395,11 @@ function createAgentMiddleware(agent) {
     },
     wrapGenerate: async ({ doGenerate, params }) => {
       const id = randomId();
-      params.prompt.forEach((p) => {
+      params.prompt.forEach((message) => {
         agent.addMessage({
           id,
-          ...p,
-          timestamp: Date.now(),
-          correlationId: params.providerMetadata?.correlationId,
-          parentCorrelationId: params.providerMetadata?.parentCorrelationId
+          ...message,
+          timestamp: Date.now()
         });
       });
       const result = await doGenerate();
@@ -380,9 +412,7 @@ function createAgentMiddleware(agent) {
         agent.addMessage({
           id,
           ...message,
-          timestamp: Date.now(),
-          correlationId: params.providerMetadata?.correlationId,
-          parentCorrelationId: params.providerMetadata?.parentCorrelationId
+          timestamp: Date.now()
         });
       });
       const { stream, ...rest } = await doStream();
@@ -407,9 +437,7 @@ function createAgentMiddleware(agent) {
             timestamp: Date.now(),
             role: "assistant",
             content,
-            responseId: id,
-            correlationId: params.providerMetadata?.correlationId,
-            parentCorrelationId: params.providerMetadata?.parentCorrelationId
+            responseId: id
           });
         }
       });
@@ -453,17 +481,18 @@ 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;
       }
-      default:
+      default: {
+        console.warn("Unrecognized event", event);
         break;
+      }
     }
     return state;
   },
@@ -471,31 +500,28 @@ var agentLogic = fromTransition(
     feedback: [],
     messages: [],
     observations: [],
-    plans: []
+    decisions: []
   })
 );
 function createAgent({
   id,
-  name,
   description,
   model,
   events,
   context,
-  planner = simplePlanner,
-  stringify = JSON.stringify,
-  getMemory,
-  logic = agentLogic,
-  ...generateTextOptions
+  episodeId,
+  strategy = simpleStrategy,
+  logic = agentLogic
 }) {
   return new Agent({
     id,
     context,
     events,
-    name,
     description,
-    planner,
+    strategy,
     model,
-    logic
+    logic,
+    episodeId
   });
 }
 var Agent = class extends Actor {
@@ -508,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();
   }
   /**
@@ -527,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.
    */
@@ -550,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
     };
@@ -589,20 +621,21 @@ 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);
+    const actorRefCheck = isActorRef(actorRef) && actorRef.src;
+    const machine = isMachineActor(actorRef) ? actorRef.src : void 0;
     let prevState = void 0;
     let subscribed = true;
     const agent = this;
@@ -610,14 +643,14 @@ var Agent = class extends Actor {
       const observation = agent.addObservation(observationInput);
       const input = getInput?.(observation);
       if (input) {
-        await agentDecide(agent, {
-          machine: actorRefCheck ? actorRef.src : void 0,
+        const res = await agentDecide(agent, {
+          machine,
           state: observation.state,
-          execute: async (event) => {
-            actorRef.send(event);
-          },
           ...input
         });
+        if (res?.nextEvent) {
+          actorRef.send(res.nextEvent);
+        }
       }
       prevState = observationInput.state;
     }
@@ -638,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
       });
@@ -679,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-alt.ts

@@ -4,7 +4,7 @@ import { openai } from '@ai-sdk/openai';
 import { getFromTerminal } from './helpers/helpers';
 
 const agent = createAgent({
-  name: 'chatbot',
+  id: 'chatbot',
   model: openai('gpt-4o-mini'),
   events: {
     'agent.respond': z.object({

package/examples/chatbot.ts

@@ -1,11 +1,11 @@
 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';
 
 const agent = createAgent({
-  name: 'chatbot',
+  id: 'chatbot',
   model: openai('gpt-4o-mini'),
   events: {
     'agent.respond': z.object({
@@ -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,11 +1,12 @@
 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({
-  name: 'chain-of-thought',
+  id: 'chain-of-thought',
   model: openai('gpt-4o-mini'),
   events: {
     'agent.think': z.object({
@@ -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,11 +1,11 @@
-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';
 
 // Create customer service agent
 const customerServiceAgent = createAgent({
-  name: 'customer-service',
+  id: 'customer-service',
   model: openai('gpt-4o'),
   events: {
     'agent.respond': z.object({
@@ -14,12 +14,12 @@ const customerServiceAgent = createAgent({
         .describe('The response from the customer service agent'),
     }),
   },
-  system: 'You are a customer service agent for an airline.',
+  description: 'You are a customer service agent for an airline.',
 });
 
 // Create simulated customer agent
 const customerAgent = createAgent({
-  name: 'customer',
+  id: 'customer',
   model: openai('gpt-4o-mini'),
   events: {
     'agent.respond': z.object({
@@ -27,7 +27,7 @@ const customerAgent = createAgent({
     }),
     'agent.finish': z.object({}).describe('End the conversation'),
   },
-  system: `You are Harrison, a customer trying to get a refund for a trip to Alaska.
+  description: `You are Harrison, a customer trying to get a refund for a trip to Alaska.
 You want them to give you ALL the money back. Be extremely persistent. This trip happened 5 years ago.
 If you have nothing more to add to the conversation, send agent.finish event.`,
 });
@@ -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,12 +1,18 @@
 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';
 
 const agent = createAgent({
-  name: 'email',
-  model: openai('gpt-4o'),
+  id: 'email',
+  model: openai('gpt-4o-mini'),
   events: {
     askForClarification: z.object({
       questions: z.array(z.string()).describe('The questions to ask the agent'),
@@ -15,23 +21,26 @@ const agent = createAgent({
       email: z.string().describe('The email to submit'),
     }),
   },
+  context: {
+    email: z.string().describe('The email to respond to'),
+    instructions: z.string().describe('The instructions for the email'),
+    clarifications: z
+      .array(z.string())
+      .describe('The clarifications to the email'),
+    replyEmail: z.string().nullable().describe('The email to submit'),
+  },
 });
 
 const machine = setup({
   types: {
-    events: agent.types.events,
+    events: {} as EventsFromAgent<typeof agent>,
     input: {} as {
       email: string;
       instructions: string;
     },
-    context: {} as {
-      email: string;
-      instructions: string;
-      clarifications: string[];
-      replyEmail: string | null;
-    },
+    context: {} as ContextFromAgent<typeof agent>,
   },
-  actors: { agent: fromDecision(agent), getFromTerminal: fromTerminal },
+  actors: { getFromTerminal: fromTerminal },
 }).createMachine({
   initial: 'checking',
   context: ({ input }) => ({
@@ -42,18 +51,6 @@ const machine = setup({
   }),
   states: {
     checking: {
-      invoke: {
-        src: 'agent',
-        input: ({ context }) => ({
-          context: {
-            email: context.email,
-            instructions: context.instructions,
-            clarifications: context.clarifications,
-          },
-          messages: agent.getMessages(),
-          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.',
-        }),
-      },
       on: {
         askForClarification: {
           actions: ({ event }) => console.log(event.questions.join('\n')),
@@ -78,17 +75,6 @@ const machine = setup({
       },
     },
     submitting: {
-      invoke: {
-        src: 'agent',
-        input: ({ context }) => ({
-          context: {
-            email: context.email,
-            instructions: context.instructions,
-            clarifications: context.clarifications,
-          },
-          goal: `Create and submit an email based on the instructions.`,
-        }),
-      },
       on: {
         submitEmail: {
           actions: assign({
@@ -109,10 +95,26 @@ const machine = setup({
   },
 });
 
-createActor(machine, {
+const actor = createActor(machine, {
   input: {
     email: 'That sounds great! When are you available?',
     instructions:
       'Tell them exactly when I am available. Address them by his full (first and last) name.',
   },
 }).start();
+
+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,
+    };
+  }
+});