Merge branch 'main' into agent-as-tool-on-stream-docs

Author: seratch

.changeset/famous-stamps-report.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-core': patch
+---
+
+feat: Add onStream handler to agents as tools

.changeset/neat-ligers-notice.md

@@ -0,0 +1,6 @@
+---
+"@openai/agents-core": patch
+"@openai/agents-openai": patch
+---
+
+feat: track token usage while streaming responses for openai models

.changeset/sweet-baboons-drive.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-openai': patch
+---
+
+fix: propagate providerData for function_calls in chat completions converter

CONTRIBUTING.md

@@ -104,9 +104,9 @@ When opening an issue, include:
 
 1. Fork the repository and create a branch with a descriptive name (e.g., `fix/missing-error`, `feat/new-tool`).
 2. Ensure your branch is up to date with `main`.
-3. Make your changes, add or update tests, and ensure that:
+3. Make your changes, add or update tests, and ensure that the following succeeds:
    ```bash
-   pnpm build && pnpm test && pnpm lint
+   pnpm build && pnpm -r build-check && pnpm test && pnpm lint
    ```
 4. If applicable, generate a changeset (`pnpm changeset`).
 5. Make sure you have [Trufflehog](https://github.com/trufflesecurity/trufflehog) installed to ensure no secrets are accidentally committed.

examples/agent-patterns/agents-as-tools-streaming.ts

@@ -0,0 +1,75 @@
+import { Agent, run, tool, withTrace } from '@openai/agents';
+import { z } from 'zod';
+
+async function main() {
+  await withTrace('Agents as tools streaming example', async () => {
+    const billingStatusCheckerTool = tool({
+      name: 'Billing statu checker',
+      description:
+        'You are a billing agent that answers questions about billing.',
+      parameters: z.object({
+        customerId: z.string().nullable().optional(),
+        question: z.string(),
+      }),
+      execute: async ({ customerId, question }) => {
+        console.log(`Customer ID: ${customerId} Question: ${question}`);
+        if (question.toLowerCase().includes('bill')) {
+          return `This customer (ID: ${customerId})'s bill is $100`;
+        }
+        return `I'm sorry, I can only answer questions about billing.`;
+      },
+    });
+
+    const subAgent = new Agent({
+      name: 'Billing Agent',
+      instructions:
+        'You are a billing agent that answers questions about billing.',
+      modelSettings: { toolChoice: 'required' },
+      tools: [billingStatusCheckerTool],
+    });
+
+    // When you pass either onStream or asTool response's on method, the agent is executed in streaming mode.
+    const billingAgentTool = subAgent.asTool({
+      toolName: 'billing_agent',
+      toolDescription:
+        'You are a billing agent that answers questions about billing.',
+      // When you pass onStream handler, the agent is executed in streaming mode.
+      onStream: (event) => {
+        console.log(
+          `### onStream method streaming event from ${event.agentName} in streaming mode:\n\n` +
+            JSON.stringify(event) +
+            '\n',
+        );
+      },
+    });
+    // Alternative way to listen to streaming events:
+    // Event types: raw_model_stream_event, run_item_stream_event, agent_updated_stream_event
+    /*
+    billingAgentTool.on('raw_model_stream_event', (event) => {
+      console.log(
+        `### on method streaming event from ${event.agentName} in streaming mode:\n\n` +
+        JSON.stringify(event) +
+        '\n',
+      );
+    });
+    */
+
+    const mainAgent = new Agent({
+      name: 'Customer Support Agent',
+      instructions:
+        'You are the customer support agent that calls the billing agent to answer a user question.',
+      tools: [billingAgentTool],
+    });
+    const result = await run(
+      mainAgent,
+      'Hello, my customer ID is ABC123. How much is my bill for this month?',
+    );
+
+    console.log(`\n### Final response:\n\n${result.finalOutput}`);
+  });
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

examples/agent-patterns/package.json

@@ -9,6 +9,7 @@
     "build-check": "tsc --noEmit",
     "start:agents-as-tools": "tsx agents-as-tools.ts",
     "start:agents-as-tools-conditional": "tsx agents-as-tools-conditional.ts",
+    "start:agents-as-tools-streaming": "tsx agents-as-tools-streaming.ts",
     "start:deterministic": "tsx deterministic.ts",
     "start:forcing-tool-use": "tsx forcing-tool-use.ts -t default",
     "start:human-in-the-loop-stream": "tsx human-in-the-loop-stream.ts",

examples/ai-sdk/README.md

@@ -1,21 +1,19 @@
-# AI SDK Example
+# AI SDK Examples
 
-This example shows how to run the Agents SDK with a model provided by the [AI SDK](https://www.npmjs.com/package/@ai-sdk/openai).
+These examples show how to wrap models from the [AI SDK](https://www.npmjs.com/package/@ai-sdk/openai) (and compatible providers) with the `aisdk()` helper from `@openai/agents-extensions`, then run them inside the Agents runtime.
 
-The [ai-sdk-model.ts](./ai-sdk-model.ts) script:
+## Available scripts
 
-- Wraps the AI SDK `openai` provider with `aisdk` from `@openai/agents-extensions`.
-- Creates a simple `get_weather` tool that returns a mock weather string.
-- Defines a data agent that uses this model and tool.
-- Runs a parent agent that hands off to the data agent to answer a weather question.
+| Script                                         | Command                                  | Provider                          | Description                                                                                                 |
+| ---------------------------------------------- | ---------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| [index.ts](./index.ts)                         | `pnpm -F ai-sdk start`                   | OpenRouter (`OPENROUTER_API_KEY`) | Runs a parent agent that hands off a weather question to a child agent equipped with a `get_weather` tool.  |
+| [gpt-5.ts](./gpt-5.ts)                         | `pnpm -F ai-sdk start:gpt-5`             | OpenAI (`OPENAI_API_KEY`)         | Shows a single agent that must call the `get_weather` tool using `gpt-5-mini` with custom provider options. |
+| [stream.ts](./stream.ts)                       | `pnpm -F ai-sdk start:stream`            | OpenAI (`OPENAI_API_KEY`)         | Demonstrates streaming text output from an AI SDK model wrapped with `aisdk()`.                             |
+| [image-tool-output.ts](./image-tool-output.ts) | `pnpm -F ai-sdk start:image-tool-output` | OpenRouter (`OPENROUTER_API_KEY`) | Returns a `ToolOutputImage` from a tool call and asks the model to describe the image.                      |
 
-## Running the script
+## Prerequisites
 
-From the repository root, execute:
-
-```bash
-pnpm -F ai-sdk start:sdk-model
-```
-
-The script prints the final output produced by the runner.
+- Run `pnpm install` at the repo root.
+- Export the relevant API key(s) shown in the table above before running a script.
 
+Once the environment variable is set, run the corresponding command from the repository root. Each script prints the final output produced by the Agents runner.

packages/agents-core/src/agent.ts

@@ -24,9 +24,9 @@ import type {
   HandoffsOutput,
   Expand,
 } from './types';
-import type { RunResult } from './result';
+import type { RunResult, StreamedRunResult } from './result';
 import { getHandoff, type Handoff } from './handoff';
-import { NonStreamRunOptions, RunConfig, Runner } from './run';
+import { StreamRunOptions, RunConfig, Runner } from './run';
 import { toFunctionToolName } from './utils/tools';
 import { getOutputText } from './utils/messages';
 import { isAgentToolInput } from './utils/typeGuards';
@@ -37,13 +37,39 @@ import logger from './logger';
 import { UnknownContext, TextOutput } from './types';
 import type * as protocol from './types/protocol';
 import type { ZodObjectLike } from './utils/zodCompat';
+import type { RunStreamEvent } from './events';
+
+type AnyAgentRunResult =
+  | RunResult<any, Agent<any, any>>
+  | StreamedRunResult<any, Agent<any, any>>;
+type CompletedRunResult<TContext, TAgent extends Agent<TContext, any>> = (
+  | RunResult<TContext, TAgent>
+  | StreamedRunResult<TContext, TAgent>
+) & {
+  finalOutput: ResolvedAgentOutput<TAgent['outputType']>;
+};
+
+type AgentToolRunOptions<TContext> = Omit<StreamRunOptions<TContext>, 'stream'>;
 
-type AnyAgentRunResult = RunResult<any, Agent<any, any>>;
-type CompletedRunResult<
+type AgentToolStreamEvent = {
+  // Raw stream event emitted by the nested agent run.
+  event: RunStreamEvent;
+  // Convenience metadata so callers can correlate to the invoking tool call/agent.
+  agentName: string;
+  toolCallId?: string;
+};
+type AgentToolEventName = AgentToolStreamEvent['event']['type'] | '*';
+type AgentToolEventHandler = (
+  event: AgentToolStreamEvent,
+) => void | Promise<void>;
+type AgentTool<TContext> = FunctionTool<
   TContext,
-  TAgent extends Agent<TContext, any>,
-> = RunResult<TContext, TAgent> & {
-  finalOutput: ResolvedAgentOutput<TAgent['outputType']>;
+  typeof AgentAsToolNeedApprovalSchame
+> & {
+  on: (
+    name: AgentToolEventName,
+    handler: AgentToolEventHandler,
+  ) => AgentTool<TContext>;
 };
 
 // Per-process, ephemeral map linking a function tool call to its nested
@@ -334,9 +360,9 @@ const AgentAsToolNeedApprovalSchame = z.object({ input: z.string() });
  * passed to tool functions, handoffs, guardrails, etc.
  */
 export class Agent<
-    TContext = UnknownContext,
-    TOutput extends AgentOutputType = TextOutput,
-  >
+  TContext = UnknownContext,
+  TOutput extends AgentOutputType = TextOutput,
+>
   extends AgentHooks<TContext, TOutput>
   implements AgentConfiguration<TContext, TOutput>
 {
@@ -527,7 +553,7 @@ export class Agent<
       /**
        * Additional run options for the agent (as tool) execution.
        */
-      runOptions?: NonStreamRunOptions<TContext>;
+      runOptions?: AgentToolRunOptions<TContext>;
       /**
        * Determines whether this tool should be exposed to the model for the current run.
        */
@@ -537,8 +563,12 @@ export class Agent<
             runContext: RunContext<TContext>;
             agent: Agent<TContext, TOutput>;
           }) => boolean | Promise<boolean>);
+      /**
+       * Optional hook to receive streamed events from the nested agent run.
+       */
+      onStream?: (event: AgentToolStreamEvent) => void | Promise<void>;
     },
-  ): FunctionTool<TContext, typeof AgentAsToolNeedApprovalSchame> {
+  ): AgentTool<TContext> {
     const {
       toolName,
       toolDescription,
@@ -547,8 +577,30 @@ export class Agent<
       runConfig,
       runOptions,
       isEnabled,
+      onStream,
     } = options;
-    return tool({
+    // Event handlers are scoped to this agent tool instance and are not shared; we only support registration (no removal) to keep the API surface small.
+    const eventHandlers = new Map<
+      AgentToolEventName,
+      Set<AgentToolEventHandler>
+    >();
+    const emitEvent = async (event: AgentToolStreamEvent) => {
+      // We intentionally keep only add semantics (no off) to reduce surface area; handlers are scoped to this agent tool instance.
+      const specific = eventHandlers.get(event.event.type);
+      const wildcard = eventHandlers.get('*');
+      const candidates = [
+        ...(onStream ? [onStream] : []),
+        ...(specific ? Array.from(specific) : []),
+        ...(wildcard ? Array.from(wildcard) : []),
+      ];
+      // Run all handlers in parallel so a slow onStream callback does not block on(...) handlers (and vice versa).
+      await Promise.allSettled(
+        candidates.map((handler) =>
+          Promise.resolve().then(() => handler(event)),
+        ),
+      );
+    };
+    const baseTool = tool({
       name: toolName ?? toFunctionToolName(this.name),
       description: toolDescription ?? '',
       parameters: AgentAsToolNeedApprovalSchame,
@@ -560,10 +612,42 @@ export class Agent<
           throw new ModelBehaviorError('Agent tool called with invalid input');
         }
         const runner = new Runner(runConfig ?? {});
-        const result = await runner.run(this, data.input, {
-          context,
-          ...(runOptions ?? {}),
-        });
+        // Only flip to streaming mode when a handler is provided to avoid extra overhead for callers that do not need events.
+        // Flip to streaming if either a legacy onStream callback or event handlers are registered; otherwise stay on the non-stream path to avoid extra overhead.
+        const shouldStream =
+          typeof onStream === 'function' || eventHandlers.size > 0;
+        const result = shouldStream
+          ? await runner.run(this, data.input, {
+              context,
+              ...(runOptions ?? {}),
+              stream: true,
+            })
+          : await runner.run(this, data.input, {
+              context,
+              ...(runOptions ?? {}),
+            });
+        const streamPayload = {
+          agentName: this.name,
+          // Tool calls should carry IDs, but direct invocation or provider quirks can omit it, so keep this optional.
+          toolCallId: details?.toolCall?.callId,
+        };
+
+        if (shouldStream) {
+          // Cast through unknown: the async iterator shape matches and we want to drain the stream for side effects while keeping the public API stable.
+          const streamResult = result as unknown as StreamedRunResult<
+            TContext,
+            Agent<TContext, AgentOutputType>
+          >;
+          // Drain the stream to deliver every event to registered handlers; ensure completion awaited so the nested run finishes before returning.
+          for await (const event of streamResult) {
+            await emitEvent({
+              event,
+              ...streamPayload,
+            });
+          }
+          await streamResult.completed;
+        }
+
         const completedResult = result as CompletedRunResult<TContext, TAgent>;
 
         const usesStopAtToolNames =
@@ -591,12 +675,24 @@ export class Agent<
         if (details?.toolCall) {
           saveAgentToolRunResult(
             details.toolCall,
-            completedResult as RunResult<any, Agent<any, any>>,
+            completedResult as AnyAgentRunResult,
           );
         }
         return outputText;
       },
     });
+
+    const agentTool: AgentTool<TContext> = {
+      ...baseTool,
+      on: (name, handler) => {
+        const set = eventHandlers.get(name) ?? new Set<AgentToolEventHandler>();
+        set.add(handler);
+        eventHandlers.set(name, set);
+        return agentTool;
+      },
+    };
+
+    return agentTool;
   }
 
   /**

packages/agents-core/src/index.ts

@@ -136,7 +136,6 @@ export {
   FunctionTool,
   FunctionToolResult,
   Tool,
-  ToolOptions,
   tool,
   ToolExecuteArgument,
   ToolEnabledFunction,

packages/agents-core/src/run.ts

@@ -1183,6 +1183,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
                 output: parsed.response.output,
                 responseId: parsed.response.id,
               };
+              result.state._context.usage.add(finalResponse.usage);
             }
             if (result.cancelled) {
               // When the user's code exits a loop to consume the stream, we need to break