start working on docs

Author: 404Wolf

README.md

@@ -124,6 +124,85 @@ await client.files.create({
 });
 ```
 
+## Streaming Helpers
+
+```ts
+import OpenAI from 'openai';
+
+const client = new OpenAI();
+
+async function main() {
+  const stream = client.chat.completions
+    .stream({
+      model: 'gpt-4o',
+      max_tokens: 1024,
+      messages: [
+        {
+          role: 'user',
+          content: 'Say hi!',
+        },
+      ],
+    })
+    .on('chunk', (text) => {
+      console.log(text);
+    });
+
+  const message = await stream.finalMessage();
+  console.log(message);
+}
+
+main();
+```
+
+## Tool Helpers
+
+The SDK makes it easy to create and run [function tools with the chats API](https://platform.openai.com/docs/guides/function-calling). You can use Zod schemas or direct JSON schemas to describe the shape of tool input, and then you can run the tools using the `client.beta.messages.toolRunner` method. This method will automatically handle passing the inputs generated by the model into your tools and providing the results back to the model.
+
+```ts
+import OpenAI from 'openai';
+
+import { betaZodFunctionTool } from 'openai/helpers/beta/zod';
+import { z } from 'zod/v4';
+
+const client = new OpenAI();
+
+async function main() {
+  const addTool = betaZodFunctionTool({
+    name: 'add',
+    parameters: z.object({
+      a: z.number(),
+      b: z.number(),
+    }),
+    description: 'Add two numbers together',
+    run: (input) => {
+      return String(input.a + input.b);
+    },
+  });
+
+  const multiplyTool = betaZodFunctionTool({
+    name: 'multiply',
+    parameters: z.object({
+      a: z.number(),
+      b: z.number(),
+    }),
+    description: 'Multiply two numbers together',
+    run: (input) => {
+      return String(input.a * input.b);
+    },
+  });
+
+  const finalMessage = await client.beta.chat.completions.toolRunner({
+    model: 'gpt-4o',
+    max_tokens: 1000,
+    messages: [{ role: 'user', content: 'What is 5 plus 3, and then multiply that result by 4?' }],
+    tools: [addTool, multiplyTool],
+  });
+  console.log(finalMessage);
+}
+
+main();
+```
+
 ## Webhook Verification
 
 Verifying webhook signatures is _optional but encouraged_.

examples/tool-calls-beta-zod.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S npm run tsn -T
 
 import OpenAI from 'openai';
-import { betaZodTool } from 'openai/helpers/beta/zod';
+import { betaZodFunctionTool } from 'openai/helpers/beta/zod';
 import { z } from 'zod';
 
 const client = new OpenAI();
@@ -15,7 +15,7 @@ async function main() {
       },
     ],
     tools: [
-      betaZodTool({
+      betaZodFunctionTool({
         name: 'getWeather',
         description: 'Get the weather at a specific location',
         parameters: z.object({
@@ -25,7 +25,7 @@ async function main() {
           return `The weather is sunny with a temperature of 20°C in ${location}.`;
         },
       }),
-      betaZodTool({
+      betaZodFunctionTool({
         name: 'getTime',
         description: 'Get the current time in a specific timezone',
         parameters: z.object({
@@ -35,7 +35,7 @@ async function main() {
           return `The current time in ${timezone} is 3:00 PM.`;
         },
       }),
-      betaZodTool({
+      betaZodFunctionTool({
         name: 'getCurrencyExchangeRate',
         description: 'Get the exchange rate between two currencies',
         parameters: z.object({

examples/tool-helpers-advanced-streaming.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S npm run tsn -T
 
 import OpenAI from 'openai';
-import { betaZodTool } from 'openai/helpers/beta/zod';
+import { betaZodFunctionTool } from 'openai/helpers/beta/zod';
 import { z } from 'zod';
 
 const client = new OpenAI();
@@ -15,7 +15,7 @@ async function main() {
       },
     ],
     tools: [
-      betaZodTool({
+      betaZodFunctionTool({
         name: 'getWeather',
         description: 'Get the weather at a specific location',
         parameters: z.object({
@@ -25,7 +25,7 @@ async function main() {
           return `The weather is sunny with a temperature of 20°C in ${location}.`;
         },
       }),
-      betaZodTool({
+      betaZodFunctionTool({
         name: 'getTime',
         description: 'Get the current time in a specific timezone',
         parameters: z.object({
@@ -35,7 +35,7 @@ async function main() {
           return `The current time in ${timezone} is 3:00 PM.`;
         },
       }),
-      betaZodTool({
+      betaZodFunctionTool({
         name: 'getCurrencyExchangeRate',
         description: 'Get the exchange rate between two currencies',
         parameters: z.object({

examples/tool-helpers-advanced.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S npm run tsn -T
 
 import OpenAI from 'openai';
-import { betaZodTool } from 'openai/helpers/beta/zod';
+import { betaZodFunctionTool } from 'openai/helpers/beta/zod';
 import { z } from 'zod';
 
 const client = new OpenAI();
@@ -15,7 +15,7 @@ async function main() {
       },
     ],
     tools: [
-      betaZodTool({
+      betaZodFunctionTool({
         name: 'getWeather',
         description: 'Get the weather at a specific location',
         parameters: z.object({

helpers.md

@@ -302,6 +302,128 @@ If you need to cancel a stream, you can `break` from a `for await` loop or call
 
 See an example of streaming helpers in action in [`examples/stream.ts`](examples/stream.ts).
 
+### Automated function calls via Beta Tool Runner
+
+We now offer an easier to use tool calling approach via the `openai.beta.chat.completions.toolRunner({…})` helper. The SDK provides helper functions to create runnable tools that can be automatically invoked by the .toolRunner() method. These helpers simplify tool creation with JSON Schema or Zod validation.
+
+#### Usage
+
+```ts
+import OpenAI from 'openai';
+
+import { betaZodFunctionTool } from 'openai/helpers/beta/zod';
+import { z } from 'zod/v4';
+
+const client = new OpenAI();
+
+async function main() {
+  const addTool = betaZodFunctionTool({
+    name: 'add',
+    parameters: z.object({
+      a: z.number(),
+      b: z.number(),
+    }),
+    description: 'Add two numbers together',
+    run: (input) => {
+      return String(input.a + input.b);
+    },
+  });
+
+  const multiplyTool = betaZodFunctionTool({
+    name: 'multiply',
+    parameters: z.object({
+      a: z.number(),
+      b: z.number(),
+    }),
+    description: 'Multiply two numbers together',
+    run: (input) => {
+      return String(input.a * input.b);
+    },
+  });
+
+  const finalMessage = await client.beta.chat.completions.toolRunner({
+    model: 'gpt-4o',
+    max_tokens: 1000,
+    messages: [{ role: 'user', content: 'What is 5 plus 3, and then multiply that result by 4?' }],
+    tools: [addTool, multiplyTool],
+  });
+  console.log(finalMessage);
+}
+
+main();
+```
+
+#### Advanced Usage
+
+You can also use the `toolRunner` as an async generator to act as the logic runs in.
+
+```ts
+// or, instead of using "await client.beta.messages.toolRunner", you can use:
+const toolRunner = client.beta.chat.completions.toolRunner({
+  model: 'gpt-4o',
+  max_tokens: 1000,
+  messages: [{ role: 'user', content: 'What is 5 plus 3, and then multiply that result by 4?' }],
+  tools: [addTool, multiplyTool],
+});
+
+for await (const event of toolRunner) {
+  console.log(event.choices[0]!.message.content);
+
+  // If the most recent message triggered a tool call, you can get the result of
+  // that tool call
+  const toolResponse = await toolRunner.generateToolResponse();
+  console.log(toolResponse);
+}
+```
+
+When you just "await" the `toolRunner`, it simply automatically iterates until the end of the async generator.
+
+#### Streaming
+
+```ts
+const runner = anthropic.beta.messages.toolRunner({
+  model: 'gpt-4o',
+  max_tokens: 1000,
+  messages: [{ role: 'user', content: 'What is the weather in San Francisco?' }],
+  tools: [calculatorTool],
+  stream: true,
+});
+
+// When streaming, the runner returns ChatCompletionStream
+for await (const messageStream of runner) {
+  for await (const event of messageStream) {
+    console.log('event:', event);
+  }
+  console.log('message:', await messageStream.finalMessage());
+}
+
+console.log(await runner);
+```
+
+See [./examples/tool-helpers-advanced-streaming.ts] for a more in-depth example.
+
+#### Beta Zod Tool
+
+Zod schemas can be used to define the input schema for your tools:
+
+```ts
+import { betaZodFunctionTool } from 'openai/helpers/beta/zod';
+
+const weatherTool = betaZodFunctionTool({
+  name: 'get_weather',
+  inputSchema: z.object({
+    location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+    unit: z.enum(['celsius', 'fahrenheit']).default('fahrenheit'),
+  }),
+  description: 'Get the current weather in a given location',
+  run: async (input) => {
+    return `The weather in ${input.location} is ${input.unit === 'celsius' ? '22°C' : '72°F'}`;
+  },
+});
+```
+
+The AI's generated inputs will be directly validated and fed into your function automatically.
+
 ### Automated function calls
 
 We provide the `openai.chat.completions.runTools({…})`
@@ -317,6 +439,8 @@ Otherwise, the args will be passed to the function you provide as a string.
 If you pass `tool_choice: {function: {name: …}}` instead of `auto`,
 it returns immediately after calling that function (and only loops to auto-recover parsing errors).
 
+#### Beta Tool
+
 ```ts
 import OpenAI from 'openai';
 

src/helpers/beta/zod.ts

@@ -9,7 +9,7 @@ import type { FunctionTool } from '../../resources/beta';
  * converted into JSON Schema when passed to the API. The provided function's
  * input arguments will also be validated against the provided schema.
  */
-export function betaZodTool<InputSchema extends ZodType>(options: {
+export function betaZodFunctionTool<InputSchema extends ZodType>(options: {
   name: string;
   parameters: InputSchema;
   description: string;

src/lib/beta/BetaToolRunner.ts

@@ -124,7 +124,7 @@ export class BetaToolRunner<Stream extends boolean>
           this.#toolResponse = undefined;
           this.#iterationCount++;
 
-          const { max_iterations, ...params } = this.#state.params;
+          const { max_iterations: _, ...params } = this.#state.params;
 
           if (params.stream) {
             stream = this.client.chat.completions.stream({ ...params, stream: true }, this.#options);

tests/lib/tools/BetaToolRunnerE2E.test.ts

@@ -1,5 +1,5 @@
 import { OpenAI } from '../../../src';
-import { betaZodTool } from '../../../src/helpers/beta/zod';
+import { betaZodFunctionTool } from '../../../src/helpers/beta/zod';
 import * as z from 'zod';
 import nock from 'nock';
 import { gunzipSync } from 'zlib';
@@ -102,7 +102,7 @@ describe('toolRunner integration tests', () => {
       run: (args: any) => any;
     }> = {},
   ) {
-    return betaZodTool({
+    return betaZodFunctionTool({
       name: 'test_tool',
       parameters: z.object({ value: z.string() }),
       description: 'A test tool',
@@ -112,7 +112,7 @@ describe('toolRunner integration tests', () => {
   }
 
   function createCounterTool() {
-    return betaZodTool({
+    return betaZodFunctionTool({
       name: 'test_tool',
       parameters: z.object({ count: z.number() }),
       description: 'A test tool',