openai · seratch · Sep 25, 2025 · Sep 25, 2025
diff --git a/docs/src/content/docs/extensions/ai-sdk.mdx b/docs/src/content/docs/extensions/ai-sdk.mdx
@@ -41,7 +41,7 @@ Out of the box the Agents SDK works with OpenAI models through the Responses API
 4. Initialize an instance of the model to be used by the agent:
 
    ```typescript
-   const model = aisdk(openai('o4-mini'));
+   const model = aisdk(openai('gpt-5-mini'));
    ```
 
 </Steps>

diff --git a/docs/src/content/docs/extensions/twilio.mdx b/docs/src/content/docs/extensions/twilio.mdx
@@ -1,5 +1,5 @@
 ---
-title: Using Realtime Agents with Twilio
+title: Connect Realtime Agents to Twilio
 description: Connect your Agents SDK agents to Twilio to use voice agents
 ---
 

diff --git a/docs/src/content/docs/guides/agents.mdx b/docs/src/content/docs/guides/agents.mdx
@@ -34,13 +34,13 @@ The rest of this page walks through every Agent feature in more detail.
 The `Agent` constructor takes a single configuration object. The most commonly‑used
 properties are shown below.
 
-| Property        | Required | Description                                                                                             |
-| --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
-| `name`          | yes      | A short human‑readable identifier.                                                                      |
-| `instructions`  | yes      | System prompt (string **or** function – see [Dynamic instructions](#dynamic-instructions)).             |
-| `model`         | no       | Model name **or** a custom [`Model`](/openai-agents-js/openai/agents/interfaces/model/) implementation. |
-| `modelSettings` | no       | Tuning parameters (temperature, top_p, etc.).                                                           |
-| `tools`         | no       | Array of [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) instances the model can call.     |
+| Property        | Required | Description                                                                                                                                  |
+| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`          | yes      | A short human‑readable identifier.                                                                                                           |
+| `instructions`  | yes      | System prompt (string **or** function – see [Dynamic instructions](#dynamic-instructions)).                                                  |
+| `model`         | no       | Model name **or** a custom [`Model`](/openai-agents-js/openai/agents/interfaces/model/) implementation.                                      |
+| `modelSettings` | no       | Tuning parameters (temperature, top_p, etc.). If the properties you need aren’t at the top level, you can include them under `providerData`. |
+| `tools`         | no       | Array of [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) instances the model can call.                                          |
 
 <Code lang="typescript" code={agentWithTools} title="Agent with tools" />
 
@@ -118,7 +118,7 @@ Both synchronous and `async` functions are supported.
 
 ## Lifecycle hooks
 
-For advanced use‑cases you can observe the Agent lifecycle by listening on events
+For advanced use‑cases you can observe the Agent lifecycle by listening on events. To learn what's available, refer to agent hook event names listed [here](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts).
 
 <Code
   lang="typescript"

diff --git a/docs/src/content/docs/guides/config.mdx b/docs/src/content/docs/guides/config.mdx
@@ -35,22 +35,26 @@ Finally you can switch between the Responses API and the Chat Completions API.
 
 ## Tracing
 
-Tracing is enabled by default and uses the OpenAI key from the section above. A separate key may be set via `setTracingExportApiKey()`.
+Tracing is enabled by default and uses the OpenAI key from the section above.
+
+A separate key may be set via `setTracingExportApiKey()`:
 
 <Code
   lang="typescript"
   code={setTracingExportApiKeyExample}
   title="Set tracing export API key"
 />
 
-Tracing can also be disabled entirely.
+Tracing can also be disabled entirely:
 
 <Code
   lang="typescript"
   code={setTracingDisabledExample}
   title="Disable tracing"
 />
 
+If you’d like to learn more about the tracing feature, please check out [Tracing guide](/openai-agents-js/guides/tracing).
+
 ## Debug logging
 
 The SDK uses the [`debug`](https://www.npmjs.com/package/debug) package for debug logging. Set the `DEBUG` environment variable to `openai-agents*` to see verbose logs.

diff --git a/docs/src/content/docs/guides/running-agents.mdx b/docs/src/content/docs/guides/running-agents.mdx
@@ -85,9 +85,7 @@ If you are creating your own `Runner` instance, you can pass in a `RunConfig` ob
 
 ## Conversations / chat threads
 
-Each call to `runner.run()` (or `run()` utility) represents one **turn** in your application-level conversation. You
-choose how much of the `RunResult` you show the end‑user – sometimes only `finalOutput`, other
-times every generated item.
+Each call to `runner.run()` (or `run()` utility) represents one **turn** in your application-level conversation. You choose how much of the `RunResult` you show the end‑user – sometimes only `finalOutput`, other times every generated item.
 
 <Code
   lang="typescript"

diff --git a/docs/src/content/docs/guides/tools.mdx b/docs/src/content/docs/guides/tools.mdx
@@ -75,8 +75,7 @@ raw JSON schema:
 
 ## 3. Agents as tools
 
-Sometimes you want an Agent to _assist_ another Agent without fully handing off the
-conversation. Use `agent.asTool()`:
+Sometimes you want an Agent to _assist_ another Agent without fully handing off the conversation. Use `agent.asTool()`:
 
 <Code lang="typescript" code={agentsAsToolsExample} title="Agents as tools" />
 
@@ -86,16 +85,18 @@ Under the hood the SDK:
 - Runs the sub‑agent with that input when the tool is called.
 - Returns either the last message or the output extracted by `customOutputExtractor`.
 
+When you run an agent as a tool, Agents SDK creates a runner with the defualt settings and run the agent with it within the function execution. If you want to provide any properties of `runConfig` or `runOptions`, you can pass them to the `asTool()` method to customize the runner's behavior.
+
 ---
 
-## 4. Local MCP servers
+## 4. MCP servers
 
-You can expose tools via a local [Model Context Protocol](https://modelcontextprotocol.io/) server and attach them to an agent.
-Use `MCPServerStdio` to spawn and connect to the server:
+You can expose tools via [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers and attach them to an agent.
+For instance, you can use `MCPServerStdio` to spawn and connect to the stdio MCP server:
 
 <Code lang="typescript" code={mcpLocalServer} title="Local MCP server" />
 
-See [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) for a complete example.
+See [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/mcp/filesystem-example.ts) for a complete example. Also, if you're looking for a comprehensitve guide for MCP server tool integration, refer to [MCP guide](/openai-agents-js/guides/mcp) for details.
 
 ---
 

diff --git a/docs/src/content/docs/guides/voice-agents/build.mdx b/docs/src/content/docs/guides/voice-agents/build.mdx
@@ -55,7 +55,7 @@ Similarly to regular agents, you can use handoffs to break your agent into multi
 
 Unlike regular agents, handoffs behave slightly differently for Realtime Agents. When a handoff is performed, the ongoing session will be updated with the new agent configuration. Because of this, the agent automatically has access to the ongoing conversation history and input filters are currently not applied.
 
-Additionally, this means that the `voice` or `model` cannot be changed as part of the handoff. You can also only connect to other Realtime Agents. If you need to use a different model, for example a reasoning model like `o4-mini`, you can use [delegation through tools](#delegation-through-tools).
+Additionally, this means that the `voice` or `model` cannot be changed as part of the handoff. You can also only connect to other Realtime Agents. If you need to use a different model, for example a reasoning model like `gpt-5-mini`, you can use [delegation through tools](#delegation-through-tools).
 
 ## Tools
 

diff --git a/examples/docs/agents/agentCloning.ts b/examples/docs/agents/agentCloning.ts
@@ -3,7 +3,7 @@ import { Agent } from '@openai/agents';
 const pirateAgent = new Agent({
   name: 'Pirate',
   instructions: 'Respond like a pirate – lots of “Arrr!”',
-  model: 'o4-mini',
+  model: 'gpt-5-mini',
 });
 
 const robotAgent = pirateAgent.clone({

diff --git a/examples/docs/agents/agentWithDynamicInstructions.ts b/examples/docs/agents/agentWithDynamicInstructions.ts
@@ -5,7 +5,7 @@ interface UserContext {
 }
 
 function buildInstructions(runContext: RunContext<UserContext>) {
-  return `The user's name is ${runContext.context.name}.  Be extra friendly!`;
+  return `The user's name is ${runContext.context.name}. Be extra friendly!`;
 }
 
 const agent = new Agent<UserContext>({

diff --git a/examples/docs/agents/agentWithHandoffs.ts b/examples/docs/agents/agentWithHandoffs.ts
@@ -13,10 +13,8 @@ const refundAgent = new Agent({
 // Use Agent.create method to ensure the finalOutput type considers handoffs
 const triageAgent = Agent.create({
   name: 'Triage Agent',
-  instructions: [
-    'Help the user with their questions.',
-    'If the user asks about booking, hand off to the booking agent.',
-    'If the user asks about refunds, hand off to the refund agent.',
-  ].join('\n'),
+  instructions: `Help the user with their questions. 
+  If the user asks about booking, hand off to the booking agent. 
+  If the user asks about refunds, hand off to the refund agent.`.trimStart(),
   handoffs: [bookingAgent, refundAgent],
 });
diff --git a/examples/docs/agents/agentWithTools.ts b/examples/docs/agents/agentWithTools.ts
@@ -13,6 +13,6 @@ const getWeather = tool({
 const agent = new Agent({
   name: 'Weather bot',
   instructions: 'You are a helpful weather bot.',
-  model: 'o4-mini',
+  model: 'gpt-4.1',
   tools: [getWeather],
 });
diff --git a/examples/docs/agents/simpleAgent.ts b/examples/docs/agents/simpleAgent.ts
@@ -3,5 +3,5 @@ import { Agent } from '@openai/agents';
 const agent = new Agent({
   name: 'Haiku Agent',
   instructions: 'Always respond in haiku form.',
-  model: 'o4-mini', // optional – falls back to the default model
+  model: 'gpt-5-nano', // optional – falls back to the default model
 });
diff --git a/examples/docs/extensions/ai-sdk-setup.ts b/examples/docs/extensions/ai-sdk-setup.ts
@@ -7,7 +7,7 @@ import { openai } from '@ai-sdk/openai';
 import { aisdk } from '@openai/agents-extensions';
 
 // Create a model instance to be used by the agent
-const model = aisdk(openai('o4-mini'));
+const model = aisdk(openai('gpt-5-mini'));
 
 // Create an agent with the model
 const agent = new Agent({

diff --git a/examples/docs/voice-agents/serverAgent.ts b/examples/docs/voice-agents/serverAgent.ts
@@ -9,7 +9,7 @@ const agent = new Agent({
   name: 'Refund Expert',
   instructions:
     'You are a refund expert. You are given a request to process a refund and you need to determine if the request is valid.',
-  model: 'o4-mini',
+  model: 'gpt-5-mini',
   outputType: z.object({
     reasong: z.string(),
     refundApproved: z.boolean(),