Document updates for #513 (#514)

Author: seratch

docs/src/content/docs/guides/models.mdx

@@ -10,6 +10,7 @@ import modelSettingsExample from '../../../../../examples/docs/models/modelSetti
 import promptIdExample from '../../../../../examples/basic/prompt-id.ts?raw';
 import agentWithModelExample from '../../../../../examples/docs/models/agentWithModel.ts?raw';
 import runnerWithModelExample from '../../../../../examples/docs/models/runnerWithModel.ts?raw';
+import gpt5DefaultModelSettingsExample from '../../../../../examples/docs/models/gpt5DefaultModelSettings.ts?raw';
 import setTracingExportApiKeyExample from '../../../../../examples/docs/config/setTracingExportApiKey.ts?raw';
 
 Every Agent ultimately calls an LLM. The SDK abstracts models behind two lightweight
@@ -54,22 +55,11 @@ Second, you can set a default model for a `Runner` instance. If you don't set a
 
 When you use any of GPT-5's reasoning models ([`gpt-5`](https://platform.openai.com/docs/models/gpt-5), [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini), or [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)) this way, the SDK applies sensible `modelSettings` by default. Specifically, it sets both `reasoning.effort` and `verbosity` to `"low"`. To adjust the reasoning effort for the default model, pass your own `modelSettings`:
 
-```ts
-import { Agent } from '@openai/agents';
-
-const myAgent = new Agent({
-  name: 'My Agent',
-  instructions: "You're a helpful agent.",
-  modelSettings: {
-    providerData: {
-      reasoning: { effort: 'minimal' },
-      text: { verbosity: 'low' },
-    },
-  // If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings works.
-  // It's also fine to pass a GPT-5 model name explicitly:
-  // model: 'gpt-5',
-});
-```
+<Code
+  lang="typescript"
+  code={gpt5DefaultModelSettingsExample}
+  title="Customize GPT-5 default settings"
+/>
 
 For lower latency, using either [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) or [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) with `reasoning.effort="minimal"` will often return responses faster than the default settings. However, some built-in tools (such as file search and image generation) in Responses API do not support `"minimal"` reasoning effort, which is why this Agents SDK defaults to `"low"`.
 

docs/src/content/docs/ja/guides/models.mdx

@@ -10,6 +10,7 @@ import modelSettingsExample from '../../../../../../examples/docs/models/modelSe
 import promptIdExample from '../../../../../../examples/basic/prompt-id.ts?raw';
 import agentWithModelExample from '../../../../../../examples/docs/models/agentWithModel.ts?raw';
 import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw';
+import gpt5DefaultModelSettingsExample from '../../../../../../examples/docs/models/gpt5DefaultModelSettings.ts?raw';
 import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw';
 
 最終的にすべてのエージェントは LLM を呼び出します。SDK はモデルを 2 つの軽量インターフェースの背後に抽象化します:
@@ -50,22 +51,11 @@ node my-awesome-agent.js
 
 この方法で GPT-5 の推論モデル（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini)、[`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）を使用する場合、SDK はデフォルトで妥当な `modelSettings` を適用します。具体的には、`reasoning.effort` と `verbosity` の両方を `"low"` に設定します。デフォルトモデルの推論強度を調整するには、独自の `modelSettings` を指定します:
 
-```ts
-import { Agent } from '@openai/agents';
-
-const myAgent = new Agent({
-  name: 'My Agent',
-  instructions: "You're a helpful agent.",
-  modelSettings: {
-    providerData: {
-      reasoning: { effort: 'minimal' },
-      text: { verbosity: 'low' },
-    },
-  // If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings works.
-  // It's also fine to pass a GPT-5 model name explicitly:
-  // model: 'gpt-5',
-});
-```
+<Code
+  lang="typescript"
+  code={gpt5DefaultModelSettingsExample}
+  title="GPT-5 の既定設定をカスタマイズ"
+/>
 
 より低レイテンシを求める場合、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) または [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) に `reasoning.effort="minimal"` を指定すると、デフォルト設定より高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は `"minimal"` の推論強度をサポートしないため、この Agents SDK ではデフォルトを `"low"` にしています。
 

docs/src/content/docs/zh/guides/models.mdx

@@ -10,6 +10,7 @@ import modelSettingsExample from '../../../../../../examples/docs/models/modelSe
 import promptIdExample from '../../../../../../examples/basic/prompt-id.ts?raw';
 import agentWithModelExample from '../../../../../../examples/docs/models/agentWithModel.ts?raw';
 import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw';
+import gpt5DefaultModelSettingsExample from '../../../../../../examples/docs/models/gpt5DefaultModelSettings.ts?raw';
 import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw';
 
 每个智能体最终都会调用一个 LLM。SDK 在两个轻量接口后面抽象了模型：
@@ -50,22 +51,11 @@ node my-awesome-agent.js
 
 当您以这种方式使用任一 GPT-5 推理模型（[`gpt-5`](https://platform.openai.com/docs/models/gpt-5)、[`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 或 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano)）时，SDK 会默认应用合理的 `modelSettings`。具体来说，它会将 `reasoning.effort` 与 `verbosity` 都设为 `"low"`。若要为默认模型调整推理强度，请传入您自己的 `modelSettings`：
 
-```ts
-import { Agent } from '@openai/agents';
-
-const myAgent = new Agent({
-  name: 'My Agent',
-  instructions: "You're a helpful agent.",
-  modelSettings: {
-    providerData: {
-      reasoning: { effort: 'minimal' },
-      text: { verbosity: 'low' },
-    },
-  // If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings works.
-  // It's also fine to pass a GPT-5 model name explicitly:
-  // model: 'gpt-5',
-});
-```
+<Code
+  lang="typescript"
+  code={gpt5DefaultModelSettingsExample}
+  title="自定义 GPT-5 默认设置"
+/>
 
 为了降低延迟，使用 [`gpt-5-mini`](https://platform.openai.com/docs/models/gpt-5-mini) 或 [`gpt-5-nano`](https://platform.openai.com/docs/models/gpt-5-nano) 并设置 `reasoning.effort="minimal"` 通常会比默认设置更快地返回响应。但需要注意，Responses API 中的一些内置工具（例如文件搜索与图像生成）不支持 `"minimal"` 推理强度，因此本 Agents SDK 默认使用 `"low"`。
 

examples/docs/models/gpt5DefaultModelSettings.ts

@@ -0,0 +1,13 @@
+import { Agent } from '@openai/agents';
+
+const myAgent = new Agent({
+  name: 'My Agent',
+  instructions: "You're a helpful agent.",
+  modelSettings: {
+    reasoning: { effort: 'minimal' },
+    text: { verbosity: 'low' },
+  },
+  // If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings works.
+  // It's also fine to pass a GPT-5 model name explicitly:
+  // model: 'gpt-5',
+});