@statelyai/agent 0.0.7 → 0.1.0

package/examples/number.ts

@@ -0,0 +1,102 @@
+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';
+
+const agent = createAgent({
+  name: 'number-guesser',
+  model: openai('gpt-3.5-turbo-1106'),
+  events: {
+    'agent.guess': z.object({
+      number: z.number().min(1).max(10).describe('The number guessed'),
+    }),
+  },
+});
+
+const machine = setup({
+  types: {
+    context: {} as {
+      previousGuesses: number[];
+      answer: number | null;
+    },
+    events: agent.eventTypes,
+  },
+  actors: {
+    agent: fromDecision(agent),
+    getFromTerminal,
+  },
+}).createMachine({
+  context: {
+    answer: null,
+    previousGuesses: [],
+  },
+  initial: 'providing',
+  states: {
+    providing: {
+      invoke: {
+        src: 'getFromTerminal',
+        input: 'Enter a number between 1 and 10',
+        onDone: {
+          actions: assign({
+            answer: (x) => +x.event.output,
+          }),
+          target: 'guessing',
+        },
+      },
+    },
+    guessing: {
+      always: {
+        guard: ({ context }) =>
+          context.answer === context.previousGuesses.at(-1),
+        target: 'winner',
+      },
+      invoke: {
+        src: 'agent',
+        input: ({ context }) => ({
+          goal: `
+          Guess the number between 1 and 10. The previous guesses were ${
+            context.previousGuesses.length
+              ? context.previousGuesses.join(', ')
+              : 'not made yet'
+          } and the last result was ${
+            context.previousGuesses.length === 0
+              ? 'not given yet'
+              : context.previousGuesses.at(-1)! - context.answer! > 0
+              ? 'too high'
+              : 'too low'
+          }.
+        `,
+        }),
+      },
+      on: {
+        'agent.guess': {
+          actions: [
+            assign({
+              previousGuesses: ({ context, event }) => [
+                ...context.previousGuesses,
+                event.number,
+              ],
+            }),
+            log((x) => x.event.number),
+          ],
+          target: 'guessing',
+          reenter: true,
+        },
+      },
+    },
+    winner: {
+      entry: log('You guessed the correct number!'),
+      type: 'final',
+    },
+  },
+  exit: () => {
+    process.exit();
+  },
+});
+
+const actor = createActor(machine, {
+  input: { answer: 4 },
+});
+
+actor.start();

package/examples/raffle.ts

@@ -0,0 +1,105 @@
+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';
+
+const agent = createAgent({
+  name: 'raffle-chooser',
+  model: openai('gpt-4-turbo'),
+  events: {
+    'agent.collectEntries': z.object({}).describe('Collect more entries'),
+    'agent.draw': z.object({}).describe('Draw a winner'),
+    'agent.reportWinner': z.object({
+      winningEntry: z.string().describe('The winning entry'),
+      firstRunnerUp: z.string().describe('The first runner up entry'),
+      secondRunnerUp: z.string().describe('The second runner up entry'),
+      explanation: z
+        .string()
+        .describe('Explanation for why you chose the winning entry'),
+    }),
+  },
+});
+
+const machine = setup({
+  types: {
+    context: {} as {
+      lastInput: string | null;
+      entries: string[];
+    },
+    events: {} as typeof agent.eventTypes | { type: 'draw' },
+  },
+  actors: { agent: fromDecision(agent), getFromTerminal },
+}).createMachine({
+  /** @xstate-layout N4IgpgJg5mDOIC5QAoC2BDAxgCwJYDswBKAOjHwBcwAnAqAYggHtCSCA3JgazBLSzyFS5KrXxQEHJpnQVcLANoAGALrKViUAAcmsXHJaaQAD0QAmAOwBmEmYCsADgCMZgJxmALE4ceHSuwA0IACe5gBsZiR29q5KPnaOrmEOAL4pQfw4BMQkEGCiqAR09OgwlCSYTAA2VWCYFACilLRw6kY6egb4RqYIZg52JB52Ya5jSq5+To4eQaEILhYkA0qjVlYeSlsOYWFpGRhZQrn5NIX4xaUiudToAO5tSCAd+vLdT727SiRKHsl2FjCwxcrlmIUQTl2ticHk26ycMPsqXSIEyghyEFud0uZQoJGoYB01AoAHUCIRqI9tLpXoYPohXBYnCQnP4HK4nFYLF5vK45hCPDYmVtdk5uYzuWkUfgmHl4E80dkiO0aV0eogALRhfkIDWDMZjJn9MxhKwjSb7VGHdHCSg0OgqzpvdUIDxmHWc5l2caeKxhVYDFyWxXHPIFIriR2096gXoeVw2VmgiIOBzWJRiqwe2FRdzcpRWE0JPPB61Km73B1PF5q+kIPweEhWMWjCz+BJKJketwkQEWCyuOywv0WaJ2UsCcvY-AUqO12MQls-Ue+Px2KzspweoHLXxsjO-eNmMxSlJAA */
+  context: {
+    lastInput: null,
+    entries: [],
+  },
+  initial: 'entering',
+  states: {
+    entering: {
+      entry: log(({ context }) => context.entries),
+      invoke: {
+        src: 'getFromTerminal',
+        input: 'What technology are you most interested in right now?',
+        onDone: [
+          {
+            actions: assign({
+              lastInput: ({ event }) => event.output,
+            }),
+            target: 'determining',
+          },
+        ],
+      },
+    },
+    determining: {
+      invoke: {
+        src: 'agent',
+        input: {
+          context: true,
+          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': {
+          target: 'entering',
+          actions: assign({
+            entries: ({ context }) => [...context.entries, context.lastInput!],
+            lastInput: null,
+          }),
+        },
+        'agent.draw': 'drawing',
+      },
+    },
+    drawing: {
+      entry: log('And the winner is...'),
+      invoke: {
+        src: 'agent',
+        input: {
+          context: true,
+          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': {
+          actions: log(
+            ({ event }) =>
+              `\n🎉🎉🎉 ${event.winningEntry} 🎉🎉🎉\n\n${event.explanation}`
+          ),
+          target: 'winner',
+        },
+      },
+    },
+    winner: {
+      type: 'final',
+    },
+  },
+  exit: () => {
+    process.exit(0);
+  },
+});
+
+const actor = createActor(machine);
+
+actor.start();

package/examples/simple.ts

@@ -0,0 +1,39 @@
+import { createAgent, fromDecision } from '../src';
+import { z } from 'zod';
+import { setup, createActor } from 'xstate';
+import { openai } from '@ai-sdk/openai';
+
+const agent = createAgent({
+  name: 'simple',
+  model: openai('gpt-3.5-turbo-16k-0613'),
+  events: {
+    'agent.thought': z.object({
+      text: z.string().describe('The text of the thought'),
+    }),
+  },
+});
+
+const machine = setup({
+  actors: { agent: fromDecision(agent) },
+}).createMachine({
+  initial: 'thinking',
+  states: {
+    thinking: {
+      invoke: {
+        src: 'agent',
+        input: 'Think about a random topic, and then share that thought.',
+      },
+      on: {
+        'agent.thought': {
+          actions: ({ event }) => console.log(event.text),
+          target: 'thought',
+        },
+      },
+    },
+    thought: {
+      type: 'final',
+    },
+  },
+});
+
+const actor = createActor(machine).start();

package/examples/support.ts

@@ -0,0 +1,147 @@
+import { openai } from '@ai-sdk/openai';
+import { createAgent, fromDecision } from '../src';
+import { z } from 'zod';
+import { createActor, log, setup } from 'xstate';
+
+const agent = createAgent({
+  name: 'support-agent',
+  model: openai('gpt-4-1106-preview'),
+  events: {
+    'agent.respond': z.object({
+      response: z.string().describe('The response from the agent'),
+    }),
+    'agent.frontline.classify': z.object({
+      category: z
+        .enum(['billing', 'technical', 'other'])
+        .describe('The category of the customer issue'),
+    }),
+    'agent.refund': z
+      .object({
+        response: z.string().describe('The response from the agent'),
+      })
+      .describe('The agent wants to refund the user'),
+    'agent.technical.solve': z.object({
+      solution: z
+        .string()
+        .describe('The solution provided by the technical agent'),
+    }),
+    'agent.endConversation': z
+      .object({
+        response: z.string().describe('The response from the agent'),
+      })
+      .describe('The agent ends the conversation'),
+  },
+});
+
+const machine = setup({
+  types: {
+    events: agent.eventTypes,
+    input: {} as string,
+    context: {} as {
+      customerIssue: string;
+    },
+  },
+  actors: { agent: fromDecision(agent) },
+}).createMachine({
+  initial: 'frontline',
+  context: ({ input }) => ({
+    customerIssue: input,
+  }),
+  states: {
+    frontline: {
+      invoke: {
+        src: 'agent',
+        input: ({ context }) => ({
+          context,
+          system: `You are frontline support staff for LangCorp, a company that sells computers.
+          Be concise in your responses.
+          You can chat with customers and help them with basic questions, but if the customer is having a billing or technical problem,
+          do not try to answer the question directly or gather information.
+          Instead, immediately transfer them to the billing or technical team by asking the user to hold for a moment.
+          Otherwise, just respond conversationally.`,
+          goal: `The previous conversation is an interaction between a customer support representative and a user.
+          Classify whether the representative is routing the user to a billing or technical team, or whether they are just responding conversationally.`,
+        }),
+      },
+      on: {
+        'agent.frontline.classify': [
+          {
+            actions: log(({ event }) => event),
+            guard: ({ event }) => event.category === 'billing',
+            target: 'billing',
+          },
+          {
+            actions: log(({ event }) => event),
+            guard: ({ event }) => event.category === 'technical',
+            target: 'technical',
+          },
+          {
+            actions: log(({ event }) => event),
+            target: 'conversational',
+          },
+        ],
+      },
+    },
+    billing: {
+      invoke: {
+        src: 'agent',
+        input: {
+          system:
+            'Your job is to detect whether a billing support representative wants to refund the user.',
+          goal: `The following text is a response from a customer support representative. Extract whether they want to refund the user or not.`,
+        },
+      },
+      on: {
+        'agent.refund': {
+          actions: log(({ event }) => event),
+          target: 'refund',
+        },
+      },
+    },
+    technical: {
+      invoke: {
+        src: 'agent',
+        input: {
+          context: true,
+          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': {
+          actions: log(({ event }) => event),
+          target: 'conversational',
+        },
+      },
+    },
+    conversational: {
+      invoke: {
+        src: 'agent',
+        input: {
+          goal: 'You are a customer support agent that is ending the conversation with the customer. Respond politely and thank them for their time.',
+        },
+      },
+      on: {
+        'agent.endConversation': {
+          actions: log((x) => x.event),
+          target: 'end',
+        },
+      },
+    },
+    refund: {
+      entry: () => console.log('Refunding...'),
+      after: {
+        1000: { target: 'conversational' },
+      },
+    },
+    end: {
+      type: 'final',
+    },
+  },
+});
+
+const actor = createActor(machine, {
+  input: `I've changed my mind and I want a refund for order #182818!`,
+});
+
+actor.start();

package/examples/ticTacToe.ts

@@ -1,80 +1,40 @@
-import { assign, setup, assertEvent } from 'xstate';
-import OpenAI from 'openai';
-import { createOpenAIAdapter, createSchemas, createAgent } from '../src';
-
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-});
-
-type Player = 'x' | 'o';
-
-const schemas = createSchemas({
-  context: {
-    type: 'object',
-    properties: {
-      board: {
-        type: 'array',
-        items: {
-          type: ['null', 'string'],
-          enum: [null, 'x', 'o'],
-        },
-        minItems: 9,
-        maxItems: 9,
-        description: 'The board of the tic-tac-toe game',
-      },
-      moves: {
-        type: 'number',
-        description: 'The number of moves that have been played',
-      },
-      player: {
-        type: 'string',
-        enum: ['x', 'o'],
-        description: 'The player whose turn it is',
-      },
-      gameReport: {
-        type: 'string',
-        description: 'The game report',
-      },
-      events: {
-        type: 'array',
-        items: {
-          type: 'string',
-        },
-      },
-    },
-    required: ['board', 'moves', 'player', 'gameReport', 'events'],
-  },
+import { assign, setup, assertEvent, createActor } from 'xstate';
+import { z } from 'zod';
+import { createAgent, fromDecision, fromTextStream } from '../src';
+import { openai } from '@ai-sdk/openai';
+import { defaultToolCallTemplate } from '../src/templates/defaultToolCall';
+
+const agent = createAgent({
+  name: 'tic-tac-toe-bot',
+  model: openai('gpt-4-0125-preview'),
   events: {
-    'x.play': {
-      properties: {
-        index: {
-          description: 'The index of the cell to play on',
-          type: 'number',
-
-          minimum: 0,
-          maximum: 8,
-        },
-      },
-    },
-    'o.play': {
-      properties: {
-        index: {
-          description: 'The index of the cell to play on',
-          type: 'number',
-          minimum: 0,
-          maximum: 8,
-        },
-      },
-    },
-    reset: {
-      properties: {},
-    },
+    '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'),
   },
 });
 
-const adapter = createOpenAIAdapter(openai, {
-  model: 'gpt-4-1106-preview',
-});
+type Player = 'x' | 'o';
+
+interface GameContext {
+  board: (Player | null)[];
+  moves: number;
+  player: Player;
+  gameReport: string;
+  events: string[];
+}
 
 const initialContext = {
   board: Array(9).fill(null) as Array<Player | null>,
@@ -82,34 +42,7 @@ const initialContext = {
   player: 'x' as Player,
   gameReport: '',
   events: [],
-} satisfies typeof schemas.types.context;
-
-const bot = adapter.fromEvent(
-  ({ context }: { context: typeof schemas.types.context }) => `
-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.
-
-${JSON.stringify(context, null, 2)}
-
-Execute the single best next move to try to win the game. Do not play on an existing cell.`
-);
-
-const gameReporter = adapter.fromChatStream(
-  ({
-    context,
-  }: {
-    context: typeof schemas.types.context;
-  }) => `Here is the game board:
-
-${JSON.stringify(context.board, null, 2)}
-
-And here are the events that led to this game state:
-
-${context.events.join('\n')}
-
-The winner is ${getWinner(context.board)}.
-
-Provide a very short game report analyzing the game.`
-);
+} satisfies GameContext;
 
 function getWinner(board: typeof initialContext.board): Player | null {
   const lines = [
@@ -131,16 +64,18 @@ function getWinner(board: typeof initialContext.board): Player | null {
 }
 
 export const ticTacToeMachine = setup({
-  schemas,
-  types: schemas.types,
+  types: {
+    context: {} as GameContext,
+    events: agent.eventTypes,
+  },
   actors: {
-    bot,
-    gameReporter,
+    agent: fromDecision(agent),
+    gameReporter: fromTextStream(agent),
   },
   actions: {
     updateBoard: assign({
       board: ({ context, event }) => {
-        assertEvent(event, ['x.play', 'o.play']);
+        assertEvent(event, ['agent.x.play', 'agent.o.play']);
         const updatedBoard = [...context.board];
         updatedBoard[event.index] = context.player;
         return updatedBoard;
@@ -157,6 +92,22 @@ export const ticTacToeMachine = setup({
         return [...context.events, JSON.stringify(event)];
       },
     }),
+    printBoard: ({ context }) => {
+      // Print the context.board in a 3 x 3 grid format
+      let boardString = '';
+      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';
+          }
+        }
+      }
+
+      console.log(boardString);
+    },
   },
   guards: {
     checkWin: ({ context }) => {
@@ -169,7 +120,7 @@ export const ticTacToeMachine = setup({
     },
     isValidMove: ({ context, event }) => {
       try {
-        assertEvent(event, ['o.play', 'x.play']);
+        assertEvent(event, ['agent.o.play', 'agent.x.play']);
       } catch {
         return false;
       }
@@ -189,12 +140,9 @@ export const ticTacToeMachine = setup({
       initial: 'x',
       states: {
         x: {
-          invoke: {
-            src: 'bot',
-            input: ({ context }) => ({ context }),
-          },
+          entry: 'printBoard',
           on: {
-            'x.play': [
+            'agent.x.play': [
               {
                 target: 'o',
                 guard: 'isValidMove',
@@ -205,12 +153,9 @@ export const ticTacToeMachine = setup({
           },
         },
         o: {
-          invoke: {
-            src: 'bot',
-            input: ({ context }) => ({ context }),
-          },
+          entry: 'printBoard',
           on: {
-            'o.play': [
+            'agent.o.play': [
               {
                 target: 'x',
                 guard: 'isValidMove',
@@ -226,13 +171,21 @@ export const ticTacToeMachine = setup({
       initial: 'winner',
       invoke: {
         src: 'gameReporter',
-        input: ({ context }) => ({ context }),
+        input: ({ context }) => ({
+          context: {
+            events: context.events,
+            board: context.board,
+          },
+          prompt: 'Provide a short game report analyzing the game.',
+        }),
         onSnapshot: {
           actions: assign({
             gameReport: ({ context, event }) => {
+              console.log(
+                context.gameReport + (event.snapshot.context?.textDelta ?? '')
+              );
               return (
-                context.gameReport +
-                (event.snapshot.context?.choices[0]?.delta.content ?? '')
+                context.gameReport + (event.snapshot.context?.textDelta ?? '')
               );
             },
           }),
@@ -256,8 +209,20 @@ export const ticTacToeMachine = setup({
   },
 });
 
-const agent = createAgent(ticTacToeMachine);
-agent.subscribe((s) => {
-  console.log(s.value, s.context);
+const actor = createActor(ticTacToeMachine);
+
+agent.interact(actor, (observed) => {
+  if (observed.state.matches('playing')) {
+    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.
+
+${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;
 });
-agent.start();
+
+actor.start();