Update documents with workaround for #187 (#200)

seratch · web-flow · commit 3f3210254de4 · 2025-07-11T15:00:49.000+09:00
diff --git a/README.md b/README.md
@@ -4,11 +4,9 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 
 <img src="https://cdn.openai.com/API/docs/images/orchestration.png" alt="Image of the Agents Tracing UI" style="max-height: 803px;">
 
-
 > [!NOTE]
 > Looking for the Python version? Check out [Agents SDK Python](https://github.com/openai/openai-agents-python).
 
-
 ## Core concepts
 
 1. **Agents**: LLMs configured with instructions, tools, guardrails, and handoffs.
@@ -52,8 +50,10 @@ Experimental support:
 
 ### Installation
 
+This SDK currently does not work with `zod@3.25.68` and above. Please install `zod@3.25.67` (or any older version) explicitly. We will resolve this dependency issue soon. Please check [this issue}(https://github.com/openai/openai-agents-js/issues/187) for updates.
+
 ```bash
-npm install @openai/agents
+npm install @openai/agents 'zod@<=3.25.67'
 ```
 
 ## Hello world example
diff --git a/docs/src/content/docs/guides/quickstart.mdx b/docs/src/content/docs/guides/quickstart.mdx
@@ -22,7 +22,7 @@ import quickstartExample from '../../../../../examples/docs/quickstart/index.ts?
 2. Install the Agents SDK.
 
    ```bash
-   npm install @openai/agents
+   npm install @openai/agents 'zod@<=3.25.67'
    ```
 
 3. Set an OpenAI API key. If you don't have one, follow [these instructions](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) to create an OpenAI API key.
diff --git a/docs/src/content/docs/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/guides/voice-agents/quickstart.mdx
@@ -37,7 +37,7 @@ import thinClientExample from '../../../../../../examples/docs/voice-agents/thin
 1. **Install the Agents SDK**
 
    ```bash
-   npm install @openai/agents
+   npm install @openai/agents 'zod@<=3.25.67'
    ```
 
    Alternatively you can install `@openai/agents-realtime` for a standalone browser package.
@@ -113,15 +113,13 @@ import thinClientExample from '../../../../../../examples/docs/voice-agents/thin
 From here you can start designing and building your own voice agent. Voice agents include a lot of the same features as regular agents, but have some of their own unique features.
 
 - Learn how to give your voice agent:
-
   - [Tools](/openai-agents-js/guides/voice-agents/build#tools)
   - [Handoffs](/openai-agents-js/guides/voice-agents/build#handoffs)
   - [Guardrails](/openai-agents-js/guides/voice-agents/build#guardrails)
   - [Handle audio interruptions](/openai-agents-js/guides/voice-agents/build#audio-interruptions)
   - [Manage session history](/openai-agents-js/guides/voice-agents/build#session-history)
 
 - Learn more about the different transport layers.
-
   - [WebRTC](/openai-agents-js/guides/voice-agents/transport#connecting-over-webrtc)
   - [WebSocket](/openai-agents-js/guides/voice-agents/transport#connecting-over-websocket)
   - [Building your own transport mechanism](/openai-agents-js/guides/voice-agents/transport#building-your-own-transport-mechanism)
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -63,8 +63,10 @@ Here are the main features of the SDK:
 
 ## Installation
 
+This SDK currently does not work with `zod@3.25.68` and above. Please install `zod@3.25.67` (or any older version) explicitly. We will resolve this dependency issue soon. Please check [this issue}(https://github.com/openai/openai-agents-js/issues/187) for updates.
+
 ```bash
-npm install @openai/agents
+npm install @openai/agents 'zod@<=3.25.67'
 ```
 
 ## Hello world example
diff --git a/docs/src/content/docs/ja/guides/quickstart.mdx b/docs/src/content/docs/ja/guides/quickstart.mdx
@@ -7,11 +7,11 @@ import { Steps } from '@astrojs/starlight/components';
 import { Code } from '@astrojs/starlight/components';
 import quickstartExample from '../../../../../../examples/docs/quickstart/index.ts?raw';
 
-## プロジェクトセットアップ
+## プロジェクトのセットアップ
 
 <Steps>
 
-1. プロジェクトを作成して npm を初期化します。これは一度だけで構いません。
+1. プロジェクトを作成して npm を初期化します。これは最初の一度だけで大丈夫です。
 
    ```bash
    mkdir my_project
@@ -22,21 +22,20 @@ import quickstartExample from '../../../../../../examples/docs/quickstart/index.
 2. Agents SDK をインストールします。
 
    ```bash
-   npm install @openai/agents
+   npm install @openai/agents 'zod@<=3.25.67'
    ```
 
-3. OpenAI API キーを設定します。まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)に従って OpenAI API キーを作成してください。
+3. OpenAI API キーを設定します。まだお持ちでない場合は、[こちらの手順](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key) に従って OpenAI API キーを作成してください。
 
    ```bash
    export OPENAI_API_KEY=sk-...
    ```
 
-   あるいは `setDefaultOpenAIKey('<api key>')` を呼び出してプログラムからキーを設定し、トレーシングには `setTracingExportApiKey('<api key>')` を使用できます。
-   くわしくは[SDK の設定](/openai-agents-js/ja/guides/config)をご覧ください。
+   あるいは、`setDefaultOpenAIKey('<api key>')` を呼び出してプログラム上でキーを設定し、トレーシング用には `setTracingExportApiKey('<api key>')` を使用できます。詳細は [SDK の設定](/openai-agents-js/ja/guides/config) をご覧ください。
 
 </Steps>
 
-## 最初のエージェントの作成
+## はじめてのエージェントを作成する
 
 エージェントは instructions と名前で定義します。
 
@@ -50,11 +49,11 @@ const agent = new Agent({
 });
 ```
 
-## 最初のエージェントの実行
+## はじめてのエージェントを実行する
 
-`run` メソッドを使ってエージェントを実行できます。開始したいエージェントと入力を渡すことで実行がトリガーされます。
+`run` メソッドを使ってエージェントを実行できます。実行を開始するには、開始したいエージェントと渡したい入力の両方を渡します。
 
-これにより、最終出力と実行中に行われたアクションを含む実行結果が返されます。
+これにより、その実行中に行われた最終出力とすべてのアクションを含む result が返されます。
 
 ```typescript
 import { Agent, run } from '@openai/agents';
@@ -70,9 +69,9 @@ const result = await run(agent, 'When did sharks first appear?');
 console.log(result.finalOutput);
 ```
 
-## エージェントにツールを与える
+## エージェントにツールを持たせる
 
-エージェントにツールを渡すことで、情報の検索やアクションの実行が可能になります。
+エージェントにツールを与えて、情報を検索したりアクションを実行したりさせることができます。
 
 ```typescript
 import { Agent, tool } from '@openai/agents';
@@ -101,7 +100,7 @@ const agent = new Agent({
 
 ## さらにエージェントを追加する
 
-追加のエージェントを同様に定義して、問題をより小さなパートに分割し、タスクに集中させることができます。また、エージェントごとにモデルを指定することで、問題に応じて異なるモデルを使用できます。
+追加のエージェントを同様に定義して、問題をより小さな部分に分割し、タスクに集中させることができます。また、エージェントごとにモデルを定義することで、異なる問題に異なるモデルを使用できます。
 
 ```typescript
 const historyTutorAgent = new Agent({
@@ -117,9 +116,9 @@ const mathTutorAgent = new Agent({
 });
 ```
 
-## ハンドオフの定義
+## ハンドオフを定義する
 
-複数のエージェント間でオーケストレーションを行うには、エージェントに `handoffs` を定義します。これにより、実行中に会話が自動的に次のエージェントへ渡されます。
+複数のエージェント間でオーケストレーションを行うために、エージェントに `handoffs` を定義できます。これにより、実行中に会話が自動的に次のエージェントへ引き継がれます。
 
 ```typescript
 // Using the Agent.create method to ensures type safety for the final output
@@ -131,11 +130,11 @@ const triageAgent = Agent.create({
 });
 ```
 
-実行後、`finalAgent` プロパティを確認すると、どのエージェントが最終応答を生成したかがわかります。
+実行後、`finalAgent` プロパティを見ることで、最終的な応答を生成したエージェントを確認できます。
 
-## エージェントオーケストレーションの実行
+## エージェントオーケストレーションを実行する
 
-Runner は、個々のエージェントの実行、ハンドオフ、ツール実行を管理します。
+Runner は個々のエージェントの実行、ハンドオフの可能性、ツールの実行を管理します。
 
 ```typescript
 import { run } from '@openai/agents';
@@ -148,21 +147,21 @@ async function main() {
 main().catch((err) => console.error(err));
 ```
 
-## まとめ
+## すべてをまとめる
 
-すべてをまとめて 1 つの完全な例にしてみましょう。これを `index.js` に配置して実行してください。
+これまでの内容を 1 つの例にまとめましょう。`index.js` に配置して実行してください。
 
-<Code lang="typescript" code={quickstartExample} title="Quickstart" />
+<Code lang="typescript" code={quickstartExample} title="クイックスタート" />
 
-## トレースの確認
+## トレースを確認する
 
-Agents SDK は自動的にトレースを生成します。これにより、エージェントがどのように動作し、どのツールを呼び出し、どのエージェントにハンドオフしたかを確認できます。
+Agents SDK はトレースを自動的に生成します。これにより、エージェントがどのように動作したか、どのツールを呼び出したか、どのエージェントへハンドオフしたかを確認できます。
 
-エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace viewer](https://platform.openai.com/traces) に移動してください。
+エージェント実行中に何が起こったかを確認するには、[OpenAI ダッシュボードの Trace ビューア](https://platform.openai.com/traces) に移動してください。
 
 ## 次のステップ
 
-より複雑なエージェントフローの構築方法を学びましょう。
+より複雑なエージェントフローの構築方法を学びましょう:
 
 - [エージェント](/openai-agents-js/ja/guides/agents) の設定方法を学ぶ
 - [エージェントの実行](/openai-agents-js/ja/guides/running-agents) について学ぶ
diff --git a/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx b/docs/src/content/docs/ja/guides/voice-agents/quickstart.mdx
@@ -26,25 +26,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t
 
 <Steps>
 
-0. **プロジェクトを作成**
+0. **プロジェクトを作成する**
 
-   このクイックスタートでは、ブラウザで使える音声エージェントを作成します。新しいプロジェクトを試したい場合は [`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) を使うこともできます。
+   このクイックスタートでは、ブラウザで利用できる音声エージェントを作成します。新しいプロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) や [`Vite`](https://vite.dev/guide/installation.html) をお試しください。
 
    ```bash
    npm create vite@latest my-project --template vanilla-ts
    ```
 
-1. ** Agents SDK をインストール**
+1. **Agents SDK をインストールする**
 
    ```bash
-   npm install @openai/agents
+   npm install @openai/agents 'zod@<=3.25.67'
    ```
 
-   代わりに、スタンドアロンのブラウザ用パッケージとして `@openai/agents-realtime` をインストールすることもできます。
+   代わりにブラウザ用の単体パッケージである `@openai/agents-realtime` をインストールすることもできます。
 
-2. **クライアントのエフェメラルトークンを生成**
+2. **クライアントのエフェメラルトークンを生成する**
 
-   このアプリケーションはユーザーのブラウザ上で動作するため、モデルへ安全に接続する方法が必要です。そのために、バックエンドサーバーで生成する [エフェメラルクライアントキー](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) を使用します。テスト用途であれば、`curl` と通常の OpenAI API キーを使ってキーを生成することも可能です。
+   このアプリケーションはユーザーのブラウザで動作するため、Realtime API を介してモデルへ安全に接続する方法が必要です。そのために、[エフェメラルクライアントキー](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) をバックエンドサーバーで生成します。テスト目的であれば、`curl` と通常の OpenAI API キーを使ってキーを生成することも可能です。
 
    ```bash
    curl -X POST https://api.openai.com/v1/realtime/sessions \
@@ -55,11 +55,11 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t
       }'
    ```
 
-   レスポンスには後で接続に使用する `client_secret.value` が含まれています。このキーは短時間しか有効ではなく、期限切れ後は再生成が必要です。
+   レスポンスには後で接続に使用する `client_secret.value` が含まれます。このキーは短時間のみ有効で、再生成が必要になる点に注意してください。
 
-3. **最初のエージェントを作成**
+3. **最初のエージェントを作成する**
 
-   新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) を作成する方法は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) を作成する方法とほとんど同じです。
+   新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`Agent`](/openai-agents-js/ja/guides/agents) の作成とほぼ同じです。
 
    ```typescript
    import { RealtimeAgent } from '@openai/agents-realtime';
@@ -70,9 +70,9 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t
    });
    ```
 
-4. **セッションを作成**
+4. **セッションを作成する**
 
-   通常のエージェントと異なり、Voice Agent は `RealtimeSession` 内で継続的に稼働し、会話とモデルへの接続を管理します。このセッションは音声処理や割り込みなど、多くのライフサイクル機能も処理します。
+   通常のエージェントと異なり、Voice エージェントは `RealtimeSession` 内で継続的に動作し、時間をかけてモデルとの会話と接続を管理します。このセッションは音声処理、割り込み、その他のライフサイクル機能も扱います。これらについては後ほど説明します。
 
    ```typescript
    import { RealtimeSession } from '@openai/agents-realtime';
@@ -82,25 +82,25 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t
    });
    ```
 
-   `RealtimeSession` のコンストラクターは第一引数に `agent` を取ります。このエージェントがユーザーと最初に対話できるエージェントになります。
+   `RealtimeSession` のコンストラクターは最初の引数に `agent` を取ります。このエージェントがユーザーと最初に対話するエージェントになります。
 
-5. **セッションへ接続**
+5. **セッションへ接続する**
 
-   セッションに接続するには、先ほど生成したクライアントエフェメラルトークンを渡します。
+   先ほど生成したクライアントのエフェメラルトークンを渡してセッションへ接続します。
 
    ```typescript
    await session.connect({ apiKey: '<client-api-key>' });
    ```
 
-   これにより、ブラウザで WebRTC を利用して Realtime API へ接続し、マイクとスピーカーが自動的に設定されます。`RealtimeSession` をバックエンドサーバー（Node.js など）で実行している場合、SDK は自動的に WebSocket を使用します。さまざまなトランスポート層については、[Realtime Transport Layer](/openai-agents-js/ja/guides/voice-agents/transport) ガイドを参照してください。
+   これによりブラウザで WebRTC を使って Realtime API に接続し、マイクとスピーカーを自動で設定して音声の入出力を行います。`RealtimeSession` をバックエンドサーバー（Node.js など）で実行している場合、SDK は自動で WebSocket を使用します。異なるトランスポート層については [リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドで詳しく学べます。
 
 6. **すべてをまとめる**
 
    <Code lang="typescript" code={helloWorldExample} />
 
 7. **エンジンを起動して話し始める**
 
-   Web サーバーを起動し、新しい Realtime Agent のコードを含むページへアクセスします。マイクへのアクセス許可を求めるダイアログが表示されるはずです。許可すると、エージェントと会話を開始できます。
+   Web サーバーを起動し、作成した Realtime エージェントのコードを含むページへアクセスしてください。マイクのアクセス許可を求めるダイアログが表示されます。許可すると、エージェントと会話を始められます。
 
    ```bash
    npm run dev
@@ -110,18 +110,16 @@ import thinClientExample from '../../../../../../../examples/docs/voice-agents/t
 
 ## 次のステップ
 
-ここからは、独自の音声エージェントの設計と構築を始められます。Voice Agent には通常のエージェントと共通の機能が多くありますが、独自の機能も備えています。
-
-- 次の機能をエージェントに追加する方法を学びましょう
+ここからは、独自の音声エージェントの設計と構築を進めましょう。音声エージェントは通常のエージェントと多くの機能を共有していますが、いくつか固有の機能もあります。
 
+- 音声エージェントに以下を追加する方法を学ぶ
   - [ツール](/openai-agents-js/ja/guides/voice-agents/build#tools)
   - [ハンドオフ](/openai-agents-js/ja/guides/voice-agents/build#handoffs)
   - [ガードレール](/openai-agents-js/ja/guides/voice-agents/build#guardrails)
-  - [音声割り込みへの対応](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions)
+  - [音声割り込みの処理](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions)
   - [セッション履歴の管理](/openai-agents-js/ja/guides/voice-agents/build#session-history)
 
-- さまざまなトランスポート層についてさらに学ぶ
-
-  - [WebRTC](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-webrtc)
-  - [WebSocket](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-websocket)
-  - [独自のトランスポートメカニズムを構築](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism)
+- 異なるトランスポート層についてさらに学ぶ
+  - [ WebRTC ](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-webrtc)
+  - [ WebSocket ](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-websocket)
+  - [独自のトランスポートメカニズムの構築](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism)
diff --git a/docs/src/content/docs/ja/index.mdx b/docs/src/content/docs/ja/index.mdx
diff --git a/packages/agents/README.md b/packages/agents/README.md
