feat: Add afterCompletion callback option for runTools to enable easily building multi-model / multi-agent flows

helpers.md

@@ -585,6 +585,43 @@ async function main() {
 main();
 ```
 
+#### Use `afterCompletion` for multi-agent patterns
+
+The `afterCompletion` callback allows for some powerful multi-agent patterns. By passing runner.messages to another LLM chat within `afterCompletion`, you can easily have another model analyze the conversation and do things like conditionally inject web research or other relevant data or guidance to help the first model overcome problems.
+
+```ts
+import OpenAI from 'openai';
+
+const client = new OpenAI();
+
+async function main() {
+  const runner = client.chat.completions
+    .runTools({
+      model: 'gpt-4o',
+      // Let's say we have a code agent that can autonomously carry out code changes
+      messages: [systemMessage, { role: 'user', content: "Please setup [some awesome library with a complex setup] in my codebase." }],
+      tools: [
+        // Whole bunch of tools...so many that we need to offload some cognitive overhead via afterCompletion
+      ],
+    },
+    {
+      afterCompletion: async () => {
+        // Pass the last ten messages to a separate LLM flow and check if we should inject any web research to help the agent overcome any problems or gaps in knowledge
+        const webResearch = await optionallyPerformWebResearch(runner.messages.slice(-10))
+
+        if (webResearch) {
+          runner._addMessage({
+            role: 'system',
+            content: `You've been provided the following up-to-date web research and should use it to guide your next steps:\n\n${webResearch}.`,
+          });
+        }
+      },
+    })
+}
+
+main();
+```
+
 #### Integrate with `zod`
 
 [`zod`](https://www.npmjs.com/package/zod) is a schema validation library which can help with validating the

src/lib/AbstractChatCompletionRunner.ts

@@ -29,6 +29,12 @@ const DEFAULT_MAX_CHAT_COMPLETIONS = 10;
 export interface RunnerOptions extends Core.RequestOptions {
   /** How many requests to make before canceling. Default 10. */
   maxChatCompletions?: number;
+  /** A callback to be run after each chat completion (and after any tools have been run for the completion).
+   * Can be used, for example, to make an LLM call to analyze the conversation thus far and provide guidance
+   * or supplemental information by injecting a message via runner._addMessage().
+   * Receives the chat completion that was just processed as an argument and runs after all tool calls have been handled.
+   */
+  afterCompletion?: (completion: ChatCompletion) => Promise<void>;
 }
 
 export class AbstractChatCompletionRunner<
@@ -274,7 +280,7 @@ export class AbstractChatCompletionRunner<
     const role = 'function' as const;
     const { function_call = 'auto', stream, ...restParams } = params;
     const singleFunctionToCall = typeof function_call !== 'string' && function_call?.name;
-    const { maxChatCompletions = DEFAULT_MAX_CHAT_COMPLETIONS } = options || {};
+    const { maxChatCompletions = DEFAULT_MAX_CHAT_COMPLETIONS, afterCompletion } = options || {};
 
     const functionsByName: Record<string, RunnableFunction<any>> = {};
     for (const f of params.functions) {
@@ -345,6 +351,10 @@ export class AbstractChatCompletionRunner<
 
       this._addMessage({ role, name, content });
 
+      if (afterCompletion) {
+        await afterCompletion(chatCompletion);
+      }
+
       if (singleFunctionToCall) return;
     }
   }
@@ -359,7 +369,7 @@ export class AbstractChatCompletionRunner<
     const role = 'tool' as const;
     const { tool_choice = 'auto', stream, ...restParams } = params;
     const singleFunctionToCall = typeof tool_choice !== 'string' && tool_choice?.function?.name;
-    const { maxChatCompletions = DEFAULT_MAX_CHAT_COMPLETIONS } = options || {};
+    const { maxChatCompletions = DEFAULT_MAX_CHAT_COMPLETIONS, afterCompletion } = options || {};
 
     // TODO(someday): clean this logic up
     const inputTools = params.tools.map((tool): RunnableToolFunction<any> => {
@@ -470,9 +480,16 @@ export class AbstractChatCompletionRunner<
         this._addMessage({ role, tool_call_id, content });
 
         if (singleFunctionToCall) {
+          if (afterCompletion) {
+            await afterCompletion(chatCompletion);
+          }
           return;
         }
       }
+
+      if (afterCompletion) {
+        await afterCompletion(chatCompletion);
+      }
     }
 
     return;