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

helpers.md

@@ -585,6 +585,42 @@ async function main() {
 main();
 ```
 
+#### Use afterComplete for multi-agent patterns
+
+The `afterComplete` callback allows for some powerful multi-agent patterns. By passing runner.messages to another LLM chat within afterComplete, you can easily have another model analyze the conversation and do things like conditionally inject web research or other targeting guidance to help the first model overcome problems.
+
+```ts
+import OpenAI from 'openai';
+
+const client = new OpenAI();
+
+async function main() {
+  let shouldInjectMessage = false // You can do any kind of conditional logic you want
+  const runner = client.chat.completions
+    .runTools({
+      model: 'gpt-3.5-turbo',
+      messages: [{ role: 'user', content: "How's the weather this week in Los Angeles?" }],
+      tools: [
+        // Whole bunch of tools...perhaps so many that we need to offload some cognitive overhead to another chat via afterCompletion...
+      ],
+    },
+    {
+      afterCompletion: async () => {
+        if (!shouldInjectMessage) {
+          runner._addMessage({
+            role: 'system',
+            content: `Here's some up-to-date information I've found from the web that can help you with your next response: 42.`,
+          });
+
+          shouldInjectMessage = true;
+        }
+      },
+    })
+}
+
+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 it was run after as an argument.
+   */
+  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;

src/resources/beta/chat/completions.ts

@@ -21,6 +21,7 @@ export {
   ParsingFunction,
   ParsingToolFunction,
 } from '../../../lib/RunnableFunction';
+import { RunnerOptions } from '../../../lib/AbstractChatCompletionRunner';
 import { ChatCompletionToolRunnerParams } from '../../../lib/ChatCompletionRunner';
 export { ChatCompletionToolRunnerParams } from '../../../lib/ChatCompletionRunner';
 import { ChatCompletionStreamingToolRunnerParams } from '../../../lib/ChatCompletionStreamingRunner';
@@ -119,19 +120,19 @@ export class Completions extends APIResource {
   runTools<
     Params extends ChatCompletionToolRunnerParams<any>,
     ParsedT = ExtractParsedContentFromParams<Params>,
-  >(body: Params, options?: Core.RequestOptions): ChatCompletionRunner<ParsedT>;
+  >(body: Params, options?: RunnerOptions): ChatCompletionRunner<ParsedT>;
 
   runTools<
     Params extends ChatCompletionStreamingToolRunnerParams<any>,
     ParsedT = ExtractParsedContentFromParams<Params>,
-  >(body: Params, options?: Core.RequestOptions): ChatCompletionStreamingRunner<ParsedT>;
+  >(body: Params, options?: RunnerOptions): ChatCompletionStreamingRunner<ParsedT>;
 
   runTools<
     Params extends ChatCompletionToolRunnerParams<any> | ChatCompletionStreamingToolRunnerParams<any>,
     ParsedT = ExtractParsedContentFromParams<Params>,
   >(
     body: Params,
-    options?: Core.RequestOptions,
+    options?: RunnerOptions,
   ): ChatCompletionRunner<ParsedT> | ChatCompletionStreamingRunner<ParsedT> {
     if (body.stream) {
       return ChatCompletionStreamingRunner.runTools(