@statelyai/agent 1.1.6 → 2.0.0-next.1

package/examples/number.ts

@@ -2,13 +2,14 @@ import { createAgent, fromDecision } from '../src';
 import { assign, createActor, log, setup } from 'xstate';
 import { z } from 'zod';
 import { openai } from '@ai-sdk/openai';
-import { getFromTerminal } from './helpers/helpers';
+import { fromTerminal } from './helpers/helpers';
 
 const agent = createAgent({
-  name: 'number-guesser',
+  id: 'number-guesser',
   model: openai('gpt-3.5-turbo-1106'),
   events: {
     'agent.guess': z.object({
+      reasoning: z.string().describe('The reasoning for the guess'),
       number: z.number().min(1).max(10).describe('The number guessed'),
     }),
   },
@@ -24,7 +25,7 @@ const machine = setup({
   },
   actors: {
     agent: fromDecision(agent),
-    getFromTerminal,
+    getFromTerminal: fromTerminal,
   },
 }).createMachine({
   context: {
@@ -39,7 +40,7 @@ const machine = setup({
         input: 'Enter a number between 1 and 10',
         onDone: {
           actions: assign({
-            answer: (x) => +x.event.output,
+            answer: ({ event }) => +event.output,
           }),
           target: 'guessing',
         },
@@ -78,7 +79,7 @@ const machine = setup({
                 event.number,
               ],
             }),
-            log((x) => x.event.number),
+            log(({ event }) => `${event.number} (${event.reasoning})`),
           ],
           target: 'guessing',
           reenter: true,

package/examples/raffle.ts

@@ -2,11 +2,11 @@ import { z } from 'zod';
 import { createAgent, fromDecision } from '../src';
 import { openai } from '@ai-sdk/openai';
 import { assign, createActor, log, setup } from 'xstate';
-import { getFromTerminal } from './helpers/helpers';
+import { fromTerminal } from './helpers/helpers';
 
 const agent = createAgent({
-  name: 'raffle-chooser',
-  model: openai('gpt-4-turbo'),
+  id: 'raffle-chooser',
+  model: openai('gpt-4o-mini'),
   events: {
     'agent.collectEntries': z.object({}).describe('Collect more entries'),
     'agent.draw': z.object({}).describe('Draw a winner'),
@@ -27,11 +27,10 @@ const machine = setup({
       lastInput: string | null;
       entries: string[];
     },
-    events: {} as typeof agent.types.events | { type: 'draw' },
+    events: agent.types.events,
   },
-  actors: { agent: fromDecision(agent), getFromTerminal },
+  actors: { agent: fromDecision(agent), getFromTerminal: fromTerminal },
 }).createMachine({
-  /** @xstate-layout N4IgpgJg5mDOIC5QAoC2BDAxgCwJYDswBKAOjHwBcwAnAqAYggHtCSCA3JgazBLSzyFS5KrXxQEHJpnQVcLANoAGALrKViUAAcmsXHJaaQAD0QAmAOwBmEmYCsADgCMZgJxmALE4ceHSuwA0IACe5gBsZiR29q5KPnaOrmEOAL4pQfw4BMQkEGCiqAR09OgwlCSYTAA2VWCYFACilLRw6kY6egb4RqYIZg52JB52Ya5jSq5+To4eQaEILhYkA0qjVlYeSlsOYWFpGRhZQrn5NIX4xaUiudToAO5tSCAd+vLdT727SiRKHsl2FjCwxcrlmIUQTl2ticHk26ycMPsqXSIEyghyEFud0uZQoJGoYB01AoAHUCIRqI9tLpXoYPohXBYnCQnP4HK4nFYLF5vK45hCPDYmVtdk5uYzuWkUfgmHl4E80dkiO0aV0eogALRhfkIDWDMZjJn9MxhKwjSb7VGHdHCSg0OgqzpvdUIDxmHWc5l2caeKxhVYDFyWxXHPIFIriR2096gXoeVw2VmgiIOBzWJRiqwe2FRdzcpRWE0JPPB61Km73B1PF5q+kIPweEhWMWjCz+BJKJketwkQEWCyuOywv0WaJ2UsCcvY-AUqO12MQls-Ue+Px2KzspweoHLXxsjO-eNmMxSlJAA */
   context: {
     lastInput: null,
     entries: [],
@@ -56,10 +55,10 @@ const machine = setup({
     determining: {
       invoke: {
         src: 'agent',
-        input: {
-          context: true,
+        input: ({ context }) => ({
+          context,
           goal: 'If the last input explicitly says to end the drawing and/or choose a winner, start the drawing process. Otherwise, get more entries.',
-        },
+        }),
       },
       on: {
         'agent.collectEntries': {
@@ -76,10 +75,10 @@ const machine = setup({
       entry: log('And the winner is...'),
       invoke: {
         src: 'agent',
-        input: {
-          context: true,
+        input: ({ context }) => ({
+          context,
           goal: 'Choose the technology that sounds most exciting to you from the entries. Be as unbiased as possible in your choice. Explain why you chose the winning entry.',
-        },
+        }),
       },
       on: {
         'agent.reportWinner': {

package/examples/river-crossing.ts

@@ -0,0 +1,140 @@
+import { createAgent } 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';
+
+const agent = createAgent({
+  id: 'river-crossing-solver',
+  model: openai('gpt-4'),
+  events: {
+    takeWolf: z
+      .object({
+        reasoning: z.string().describe('Reasoning for taking the wolf across'),
+      })
+      .describe('Take wolf across the river'),
+    takeGoat: z
+      .object({
+        reasoning: z.string().describe('Reasoning for taking the goat across'),
+      })
+      .describe('Take goat across the river'),
+    takeCabbage: z
+      .object({
+        reasoning: z
+          .string()
+          .describe('Reasoning for taking the cabbage across'),
+      })
+      .describe('Take cabbage across the river'),
+    returnEmpty: z
+      .object({
+        reasoning: z.string().describe('Reasoning for returning alone'),
+      })
+      .describe('Return across river alone'),
+  },
+  context: {
+    leftBank: z
+      .array(z.enum(['wolf', 'goat', 'cabbage']))
+      .describe('Items on the left bank'),
+    rightBank: z
+      .array(z.enum(['wolf', 'goat', 'cabbage']))
+      .describe('Items on the right bank'),
+    farmerPosition: z
+      .enum(['left', 'right'])
+      .describe('Which bank the farmer is on'),
+  },
+});
+
+const riverCrossingMachine = setup({
+  types: {
+    context: agent.types.context,
+    events: agent.types.events,
+  },
+}).createMachine({
+  initial: 'solving',
+  context: {
+    leftBank: ['wolf', 'goat', 'cabbage'],
+    rightBank: [],
+    farmerPosition: 'left',
+  },
+  states: {
+    solving: {
+      always: {
+        guard: ({ context }) => context.rightBank.length === 3,
+        target: 'success',
+      },
+      on: {
+        takeWolf: {
+          guard: ({ context }) =>
+            context.leftBank.includes('wolf') &&
+            context.farmerPosition === 'left',
+          actions: assign(({ context }) => ({
+            leftBank: context.leftBank.filter((item) => item !== 'wolf'),
+            rightBank: [...context.rightBank, 'wolf'],
+            farmerPosition: 'right',
+          })),
+        },
+        takeGoat: {
+          guard: ({ context }) =>
+            context.leftBank.includes('goat') &&
+            context.farmerPosition === 'left',
+          actions: assign(({ context }) => ({
+            leftBank: context.leftBank.filter((item) => item !== 'goat'),
+            rightBank: [...context.rightBank, 'goat'],
+            farmerPosition: 'right',
+          })),
+        },
+        takeCabbage: {
+          guard: ({ context }) =>
+            context.leftBank.includes('cabbage') &&
+            context.farmerPosition === 'left',
+          actions: assign(({ context }) => ({
+            leftBank: context.leftBank.filter((item) => item !== 'cabbage'),
+            rightBank: [...context.rightBank, 'cabbage'],
+            farmerPosition: 'right',
+          })),
+        },
+        returnEmpty: {
+          actions: assign(({ context }) => ({
+            farmerPosition:
+              context.farmerPosition === 'left' ? 'right' : 'left',
+          })),
+        },
+      },
+    },
+    success: {
+      type: 'final',
+    },
+  },
+});
+
+let maxTries = 0;
+async function main() {
+  const riverActor = createActor(riverCrossingMachine).start();
+
+  while (riverActor.getSnapshot().value !== 'success') {
+    maxTries++;
+    if (maxTries > 20) {
+      console.log('Max tries reached');
+      throw new Error('Max tries reached');
+    }
+    const decision = await agent.decide({
+      machine: riverCrossingMachine,
+      goal: 'Get all items safely across the river. Remember: Cannot leave wolf with goat or goat with cabbage unattended.',
+      state: riverActor.getSnapshot(),
+      planner: experimental_createShortestPathPlanner(),
+    });
+
+    console.log(decision?.nextEvent);
+
+    if (decision?.nextEvent) {
+      riverActor.send(decision.nextEvent);
+      console.log(riverActor.getSnapshot().context);
+    } else {
+      console.log('No decision made');
+    }
+  }
+
+  console.log('Successfully crossed the river!');
+}
+
+main();

package/examples/sandbox.ts

@@ -4,7 +4,7 @@ import { openai } from '@ai-sdk/openai';
 import { createMachine } from 'xstate';
 
 const agent = createAgent({
-  model: openai('gpt-4o'),
+  model: openai('gpt-4o-mini'),
   events: {
     doSomething: z.object({}).describe('Do something'),
   },

package/examples/simple.ts

@@ -4,8 +4,8 @@ import { setup, createActor } from 'xstate';
 import { openai } from '@ai-sdk/openai';
 
 const agent = createAgent({
-  name: 'simple',
-  model: openai('gpt-3.5-turbo-16k-0613'),
+  id: 'simple',
+  model: openai('gpt-4o-mini'),
   events: {
     'agent.thought': z.object({
       text: z.string().describe('The text of the thought'),
@@ -21,7 +21,9 @@ const machine = setup({
     thinking: {
       invoke: {
         src: 'agent',
-        input: 'Think about a random topic, and then share that thought.',
+        input: {
+          goal: 'Think about a random topic, and then share that thought.',
+        },
       },
       on: {
         'agent.thought': {

package/examples/summary.ts

@@ -0,0 +1,121 @@
+import { createAgent, fromDecision } from '../src';
+import { assign, createActor, setup } from 'xstate';
+import { z } from 'zod';
+import { openai } from '@ai-sdk/openai';
+import { fromTerminal } from './helpers/helpers';
+
+const agent = createAgent({
+  id: 'summarizing-chat',
+  model: openai('gpt-4o'),
+  events: {
+    'agent.respond': z.object({
+      response: z.string().describe('The response from the agent'),
+    }),
+    'agent.summarize': z.object({
+      summary: z.string().describe('Summary of the conversation history'),
+    }),
+  },
+  context: {
+    messages: z.array(
+      z.object({
+        role: z.enum(['user', 'assistant']),
+        content: z.string(),
+      })
+    ),
+    summary: z.string().nullable(),
+  },
+});
+
+const machine = setup({
+  types: {
+    context: agent.types.context,
+    events: agent.types.events,
+  },
+  actors: {
+    agent: fromDecision(agent),
+    fromTerminal,
+  },
+}).createMachine({
+  initial: 'user',
+  context: {
+    messages: [],
+    summary: null,
+  },
+  states: {
+    user: {
+      invoke: {
+        src: 'fromTerminal',
+        input: 'Enter a message:',
+        onDone: {
+          actions: assign({
+            messages: ({ context, event }) => [
+              ...context.messages,
+              { role: 'user', content: event.output },
+            ],
+          }),
+          target: 'chatting',
+        },
+      },
+    },
+    chatting: {
+      always: {
+        guard: ({ context }) => context.messages.length > 10,
+        target: 'summarizing',
+      },
+      invoke: {
+        src: 'agent',
+        input: ({ context }) => ({
+          goal: 'Respond to the user message',
+          context: {
+            messages: context.messages,
+            summary: context.summary,
+          },
+        }),
+      },
+      on: {
+        'agent.respond': {
+          actions: assign({
+            messages: ({ context, event }) => [
+              ...context.messages,
+              { role: 'assistant', content: event.response },
+            ],
+          }),
+          target: 'user',
+        },
+      },
+    },
+    summarizing: {
+      invoke: {
+        src: 'agent',
+        input: ({ context }) => ({
+          goal: 'Create a concise summary of the conversation history',
+          context: {
+            messages: context.messages,
+            previousSummary: context.summary,
+          },
+        }),
+      },
+      on: {
+        'agent.summarize': {
+          actions: assign({
+            summary: ({ event }) => event.summary,
+            messages: ({ context }) => context.messages.slice(-3), // Keep last 3 messages
+          }),
+          target: 'chatting',
+        },
+      },
+    },
+  },
+});
+
+const actor = createActor(machine);
+actor.subscribe((state) => {
+  console.log('Current state:', state.value);
+  console.log(
+    'Messages:',
+    state.context.messages.map((msg) => `${msg.role}: ${msg.content}`)
+  );
+  console.log('Summary:', state.context.summary);
+});
+
+actor.start();

package/examples/support.ts

@@ -4,8 +4,8 @@ import { z } from 'zod';
 import { createActor, log, setup } from 'xstate';
 
 const agent = createAgent({
-  name: 'support-agent',
-  model: openai('gpt-4-1106-preview'),
+  id: 'support-agent',
+  model: openai('gpt-4o-mini'),
   events: {
     'agent.respond': z.object({
       response: z.string().describe('The response from the agent'),
@@ -101,11 +101,11 @@ const machine = setup({
     technical: {
       invoke: {
         src: 'agent',
-        input: {
-          context: true,
+        input: ({ context }) => ({
+          context,
           system: `You are an expert at diagnosing technical computer issues. You work for a company called LangCorp that sells computers. Help the user to the best of your ability, but be concise in your responses.`,
           goal: 'Solve the customer issue.',
-        },
+        }),
       },
       on: {
         'agent.technical.solve': {
@@ -123,7 +123,7 @@ const machine = setup({
       },
       on: {
         'agent.endConversation': {
-          actions: log((x) => x.event),
+          actions: log(({ event }) => event),
           target: 'end',
         },
       },

package/examples/ticTacToe.ts

@@ -3,40 +3,53 @@ import { z } from 'zod';
 import { createAgent, fromDecision, fromTextStream } from '../src';
 import { openai } from '@ai-sdk/openai';
 
-const agent = createAgent({
-  name: 'tic-tac-toe-bot',
-  model: openai('gpt-4-0125-preview'),
-  events: {
-    'agent.x.play': z.object({
-      index: z
-        .number()
-        .min(0)
-        .max(8)
-        .describe('The index of the cell to play on'),
-    }),
-    'agent.o.play': z.object({
-      index: z
-        .number()
-        .min(0)
-        .max(8)
-        .describe('The index of the cell to play on'),
-    }),
-    reset: z.object({}).describe('Reset the game to the initial state'),
-  },
-  context: {
-    board: z
-      .array(z.union([z.literal(null), z.literal('x'), z.literal('o')]))
-      .describe('The 3x3 board represented as a 9-element array.'),
-    moves: z
+const events = {
+  'agent.x.play': z.object({
+    reasoning: z.string().describe('The reasoning for the move'),
+    index: z
       .number()
       .min(0)
-      .max(9)
-      .describe('The number of moves made in the game.'),
-    player: z
-      .union([z.literal('x'), z.literal('o')])
-      .describe('The current player (x or o)'),
-    gameReport: z.string(),
-  },
+      .max(8)
+      .describe('The index of the cell for xto play on'),
+  }),
+  'agent.o.play': z.object({
+    reasoning: z.string().describe('The reasoning for the move'),
+    index: z
+      .number()
+      .min(0)
+      .max(8)
+      .describe('The index of the cell for o to play on'),
+  }),
+};
+
+const context = {
+  board: z
+    .array(z.union([z.literal(null), z.literal('x'), z.literal('o')]))
+    .describe('The 3x3 board represented as a 9-element array.'),
+  moves: z
+    .number()
+    .min(0)
+    .max(9)
+    .describe('The number of moves made in the game.'),
+  player: z
+    .union([z.literal('x'), z.literal('o')])
+    .describe('The current player (x or o)'),
+  gameReport: z.string(),
+  lastReason: z.string(),
+};
+
+const xAgent = createAgent({
+  id: 'tic-tac-toe-learner',
+  model: openai('gpt-4o-mini'),
+  events,
+  context,
+});
+
+const oAgent = createAgent({
+  id: 'tic-tac-toe-noob',
+  model: openai('gpt-4o-mini'),
+  events,
+  context,
 });
 
 type Player = 'x' | 'o';
@@ -46,7 +59,8 @@ const initialContext = {
   moves: 0,
   player: 'x' as Player,
   gameReport: '',
-} satisfies typeof agent.types.context;
+  lastReason: '',
+} satisfies typeof xAgent.types.context;
 
 function getWinner(board: typeof initialContext.board): Player | null {
   const lines = [
@@ -69,12 +83,15 @@ function getWinner(board: typeof initialContext.board): Player | null {
 
 export const ticTacToeMachine = setup({
   types: {
-    context: agent.types.context,
-    events: agent.types.events,
+    context: xAgent.types.context,
+    events: {} as
+      | typeof xAgent.types.events
+      | {
+          type: 'reset';
+        },
   },
   actors: {
-    agent: fromDecision(agent),
-    gameReporter: fromTextStream(agent),
+    gameReporter: fromTextStream(xAgent),
   },
   actions: {
     updateBoard: assign({
@@ -90,14 +107,14 @@ export const ticTacToeMachine = setup({
     resetGame: assign(initialContext),
     printBoard: ({ context }) => {
       // Print the context.board in a 3 x 3 grid format
-      let boardString = '';
+      let boardString = `${context.lastReason}\n`;
       for (let i = 0; i < context.board.length; i++) {
         if ([0, 3, 6].includes(i)) {
           boardString += context.board[i] ?? ' ';
         } else {
           boardString += ' | ' + (context.board[i] ?? ' ');
           if ([2, 5].includes(i)) {
-            boardString += '\n--+---+--\n';
+            boardString += `\n--+---+--\n`;
           }
         }
       }
@@ -142,7 +159,12 @@ export const ticTacToeMachine = setup({
               {
                 target: 'o',
                 guard: 'isValidMove',
-                actions: 'updateBoard',
+                actions: [
+                  assign({
+                    lastReason: ({ event }) => event.reasoning,
+                  }),
+                  'updateBoard',
+                ],
               },
               { target: 'x', reenter: true },
             ],
@@ -155,7 +177,12 @@ export const ticTacToeMachine = setup({
               {
                 target: 'x',
                 guard: 'isValidMove',
-                actions: 'updateBoard',
+                actions: [
+                  assign({
+                    lastReason: ({ event }) => event.reasoning,
+                  }),
+                  'updateBoard',
+                ],
               },
               { target: 'o', reenter: true },
             ],
@@ -169,7 +196,7 @@ export const ticTacToeMachine = setup({
         src: 'gameReporter',
         input: ({ context }) => ({
           context: {
-            events: agent.getObservations().map((o) => o.event),
+            events: xAgent.getObservations().map((o) => o.event),
             board: context.board,
           },
           prompt: 'Provide a short game report analyzing the game.',
@@ -207,10 +234,24 @@ export const ticTacToeMachine = setup({
 
 const actor = createActor(ticTacToeMachine);
 
-agent.interact(actor, (observed) => {
-  if (observed.state.matches('playing')) {
+xAgent.interact(actor, (observed) => {
+  if (observed.state.matches({ playing: 'x' })) {
+    return {
+      goal: `You are playing a game of tic tac toe. This is the current game state. The 3x3 board is represented by a 9-element array. The first element is the top-left cell, the second element is the top-middle cell, the third element is the top-right cell, the fourth element is the middle-left cell, and so on. The value of each cell is either null, x, or o. The value of null means that the cell is empty. 
+
+${JSON.stringify(observed.state.context, null, 2)}
+
+Execute the single best next move to try to win the game. Do not play on an existing cell.`,
+    };
+  }
+
+  return;
+});
+
+oAgent.interact(actor, (observed) => {
+  if (observed.state.matches({ playing: 'o' })) {
     return {
-      goal: `You are playing a game of tic tac toe. This is the current game state. The 3x3 board is represented by a 9-element array. The first element is the top-left cell, the second element is the top-middle cell, the third element is the top-right cell, the fourth element is the middle-left cell, and so on. The value of each cell is either null, x, or o. The value of null means that the cell is empty. The value of x means that the cell is occupied by an x. The value of o means that the cell is occupied by an o.
+      goal: `You are playing a game of tic tac toe. This is the current game state. The 3x3 board is represented by a 9-element array. The first element is the top-left cell, the second element is the top-middle cell, the third element is the top-right cell, the fourth element is the middle-left cell, and so on. The value of each cell is either null, x, or o. The value of null means that the cell is empty. 
 
 ${JSON.stringify(observed.state.context, null, 2)}
 

package/examples/todo.ts

@@ -2,11 +2,11 @@ import { assign, setup, assertEvent, createActor, createMachine } from 'xstate';
 import { z } from 'zod';
 import { createAgent, fromDecision } from '../src';
 import { openai } from '@ai-sdk/openai';
-import { getFromTerminal } from './helpers/helpers';
+import { fromTerminal } from './helpers/helpers';
 
 const agent = createAgent({
-  name: 'todo',
-  model: openai('gpt-4o'),
+  id: 'todo',
+  model: openai('gpt-4o-mini'),
   events: {
     addTodo: z.object({
       title: z.string().min(1).max(100).describe('The title of the todo'),
@@ -40,7 +40,7 @@ const machine = setup({
       | typeof agent.types.events
       | { type: 'assist'; command: string },
   },
-  actors: { agent: fromDecision(agent), getFromTerminal },
+  actors: { agent: fromDecision(agent), getFromTerminal: fromTerminal },
 }).createMachine({
   context: {
     command: null,
@@ -118,10 +118,10 @@ const machine = setup({
     assisting: {
       invoke: {
         src: 'agent',
-        input: (x) => ({
+        input: ({ context }) => ({
           context: {
-            command: x.context.command,
-            todos: x.context.todos,
+            command: context.command,
+            todos: context.todos,
           },
           goal: 'Interpret the command as an action for this todo list; for example, "I need donuts" would add a todo item with the message "Get donuts".',
         }),