Fix browser and cloudflare trace exports (#50)

* test(integration): use latest version in integration tests

* test(integration): add vite-react tests

* fix(tracing): disable tracing and automatic exports in cloudflare and browser

* fix abortcontroller setup and update cloudflare example

* Create proud-berries-kiss.md

* apply threepointone's changes

Co-authored-by: Sunil Pai <[email protected]>

* update changeset

* docs: update tracing/troubleshooting docs

* remove unncessary test logging

* adjust debug message

* add withtrace to example

* update japanese docs

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Sunil Pai <[email protected]>

Author: 3 people

.changeset/proud-berries-kiss.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-core': patch
+---
+
+Add force flush to global provider. Consistently default disable logging loop in Cloudflare Workers and Browser

docs/src/content/docs/guides/tracing.mdx

@@ -5,6 +5,7 @@ description: Learn how to trace your agent runs
 
 import { Aside, Code } from '@astrojs/starlight/components';
 import customTraceExample from '../../../../../examples/docs/custom-trace.ts?raw';
+import cloudflareWorkers from '../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw';
 
 The Agents SDK includes built-in tracing, collecting a comprehensive record of events during an agent
 run: LLM generations, tool calls, handoffs, guardrails, and even custom events that occur. Using the
@@ -22,6 +23,18 @@ Tracing is enabled by default. There are two ways to disable tracing:
 
 </Aside>
 
+## Export loop lifecycle
+
+In most environments traces will automatically be exported on a regular interval. In the browser or in Cloudflare Workers, this functionality is disabled by default. Traces will still get exported if too many are queued up but they are not exported on a regular interval. Instead you should use `getGlobalTraceProvider().forceFlush()` to manually export the traces as part of your code's lifecycle.
+
+For example, in a Cloudflare Worker, you should wrap your code into a `try/catch/finally` block and use force flush with `waitUntil` to ensure that traces are exported before the worker exits.
+
+<Code
+  lang="typescript"
+  code={cloudflareWorkers.replace(/\s+\/\/ @ts-expect-error.*$/m, '')}
+  meta="{13}"
+/>
+
 ## Traces and spans
 
 - **Traces** represent a single end-to-end operation of a "workflow". They're composed of Spans. Traces have the following properties:

docs/src/content/docs/guides/troubleshooting.mdx

@@ -15,7 +15,7 @@ The OpenAI Agents SDK is supported on the following server environments:
 
 - **Cloudflare Workers**: The Agents SDK can be used in Cloudflare Workers, but currently comes with some limitations:
   - The SDK current requires `nodejs_compat` to be enabled
-  - The SDK can currently only be imported using dynamic imports `await import('@openai/agents')`
+  - Traces need to be manually flushed at the end of the request. [See the tracing guide](/openai-agents-js/guides/tracing#export-loop-lifecycle) for more details.
   - Due to Cloudflare Workers' limited support for `AsyncLocalStorage` some traces might not be accurate
 - **Browsers**:
   - Tracing is currently not supported in browsers

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

@@ -5,92 +5,102 @@ description: Learn how to trace your agent runs
 
 import { Aside, Code } from '@astrojs/starlight/components';
 import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw';
+import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw';
 
-Agents SDK にはトレーシング機能が組み込まれており、エージェントの実行中に発生する LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで、あらゆるイベントを詳細に記録します。  
-[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発時および本番環境でワークフローをデバッグ、可視化、監視できます。
+Agents SDK にはビルトインの トレーシング が含まれており、エージェント実行中の LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで網羅的に記録します。[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発時や本番環境でワークフローをデバッグ、可視化、監視できます。
 
 <Aside type="note">
 
-トレーシングはデフォルトで有効になっています。無効にする方法は次の 2 つです。
+トレーシングはデフォルトで有効です。無効化する方法は 2 つあります。
 
 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化する
-2. [`RunConfig.tracingDisabled`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#tracingdisabled) を `true` に設定して単一の実行のみ無効化する
+2. 1 回の実行だけ無効化したい場合は [`RunConfig.tracingDisabled`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#tracingdisabled) に `true` を設定する
 
-**_OpenAI の Zero Data Retention (ZDR) ポリシー下で API を利用している組織では、トレーシングは利用できません。_**
+**_OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングは利用できません。_**
 
 </Aside>
 
+## エクスポートループのライフサイクル
+
+多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers ではこの機能はデフォルトで無効になっています。キューに溜まりすぎた場合はエクスポートされますが、定期的にはエクスポートされません。そのため、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を呼び出して手動でエクスポートしてください。
+
+たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックにラップし、`waitUntil` とともに force flush を呼び出して、ワーカー終了前にトレースがエクスポートされるようにします。
+
+<Code
+  lang="typescript"
+  code={cloudflareWorkers.replace(/\s+\/\/ @ts-expect-error.*$/m, '')}
+  meta="{13}"
+/>
+
 ## トレースとスパン
 
-- **トレース**: 1 つの「ワークフロー」のエンドツーエンドの操作を表します。トレースはスパンで構成され、次のプロパティがあります:
-  - `workflow_name`: 論理的なワークフローまたはアプリ名。例: 「Code generation」や「Customer service」
+- **トレース (Trace)** はワークフローの単一のエンドツーエンド操作を表します。トレースはスパンで構成され、次のプロパティを持ちます:
+  - `workflow_name`: 論理的なワークフローまたはアプリ名。例: "Code generation" や "Customer service"
   - `trace_id`: トレースの一意 ID。指定しない場合は自動生成。形式は `trace_<32_alphanumeric>`
-  - `group_id`: 省略可。同じ会話からの複数トレースを関連付けるためのグループ ID。例: チャットスレッド ID など
-  - `disabled`: `true` の場合、このトレースは記録されません
+  - `group_id`: 任意のグループ ID。同じ会話からの複数トレースをリンクするために使用。例: チャットスレッド ID
+  - `disabled`: `true` の場合、このトレースは記録されない
   - `metadata`: トレースに付与する任意のメタデータ
-- **スパン**: 開始時刻と終了時刻を持つ操作を表します。スパンには次があります:
+- **スパン (Span)** は開始時刻と終了時刻を持つ操作を表します。スパンは以下を持ちます:
   - `started_at` と `ended_at` タイムスタンプ
-  - 所属トレースを示す `trace_id`
-  - 親スパンを指す `parent_id`（存在する場合）
-  - スパンに関する情報を保持する `span_data`。例: `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など
+  - 所属するトレースを示す `trace_id`
+  - 親スパンを指す `parent_id` (存在する場合)
+  - スパンに関する情報を含む `span_data`。たとえば `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など
 
 ## デフォルトのトレーシング
 
-デフォルトでは、SDK は次をトレースします:
+デフォルトでは SDK が次をトレースします:
 
-- `run()` または `Runner.run()` 全体を `Trace` でラップ
+- `run()` または `Runner.run()` 全体を 1 つの `Trace` でラップ
 - エージェントが実行されるたびに `AgentSpan` でラップ
 - LLM 生成を `GenerationSpan` でラップ
 - 関数ツール呼び出しをそれぞれ `FunctionSpan` でラップ
 - ガードレールを `GuardrailSpan` でラップ
 - ハンドオフを `HandoffSpan` でラップ
 
-トレース名はデフォルトで 「Agent workflow」 です。`withTrace` を使用して名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他プロパティを設定できます。
+トレース名はデフォルトで "Agent workflow" です。`withTrace` を使用してこの名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。
 
-さらに、[カスタムトレースプロセッサ](#custom-tracing-processors) を設定して、他の送信先へトレースを送信（置換または追加）することもできます。
+さらに、[カスタムトレースプロセッサ](#custom-tracing-processors) を設定して、（置き換えまたは追加の送信先として）他の場所にトレースを送信できます。
 
 ### 音声エージェントのトレーシング
 
-`RealtimeAgent` と `RealtimeSession` を OpenAI Realtime API のデフォルト設定で使用している場合、トレーシングは Realtime API 側で自動的に行われます。`RealtimeSession` で `tracingDisabled: true` を設定するか、`OPENAI_AGENTS_DISABLE_TRACING` 環境変数を使用すると無効化できます。
+デフォルトの OpenAI Realtime API とともに `RealtimeAgent` と `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、`OPENAI_AGENTS_DISABLE_TRACING` 環境変数を使用して無効化しない限り、トレーシングは自動的に Realtime API 側で行われます。
 
 詳細は [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。
 
-## 上位トレース
+## 高レベルのトレース
 
-複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合、コード全体を `withTrace()` でラップします。
+複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合はコード全体を `withTrace()` でラップします。
 
 <Code lang="typescript" code={customTraceExample} />
 
-1. `withTrace()` で 2 回の `run` 呼び出しをラップしているため、各実行は個別にトレースを作成せず、全体のトレースに含まれます。
+1. 2 回の `run` 呼び出しは `withTrace()` でラップされているため、個別のトレースを作成せず全体トレースの一部になります。
 
 ## トレースの作成
 
-[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数でトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` で手動で新しいトレースを生成し、それを `withTrace()` に渡すことも可能です。
+[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使ってトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` で手動で新しいトレースを作成し、それを `withTrace()` に渡すことも可能です。
 
-現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または同等の環境ポリフィルにより追跡されるため、並列処理でも自動的に機能します。
+現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルを通じて追跡されます。これにより並行処理でも自動的に機能します。
 
 ## スパンの作成
 
-`createGenerationSpan()` や `createFunctionSpan()` など、各種 `create*Span()` メソッドでスパンを作成できます。通常は手動でスパンを作成する必要はありません。カスタムスパンを追跡するには [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) を使用してください。
+`createGenerationSpan()` や `createFunctionSpan()` などの `create*Span()` メソッドを使ってスパンを作成できます。一般的には手動でスパンを作成する必要はありません。カスタムスパンを追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) も用意されています。
 
-スパンは自動的に現在のトレースに含まれ、最も近い現在のスパンの下にネストされます。これも [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または同等の環境ポリフィルで追跡されます。
+スパンは自動的に現在のトレースに属し、最も近い現在のスパンの下にネストされます。これも [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルで追跡されます。
 
-## 機微データ
+## 機微なデータ
 
-一部のスパンは機微なデータを収集する可能性があります。
+一部のスパンは機微なデータを記録する場合があります。
 
-`createGenerationSpan()` は LLM 生成の入力／出力、`createFunctionSpan()` は関数呼び出しの入力／出力を保存します。これらに機微データが含まれる場合があるため、[`RunConfig.traceIncludeSensitiveData`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) でデータ収集を無効化できます。
+`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。これらに機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) で記録を無効化できます。
 
-## カスタムトレースプロセッサ
+## カスタムトレーシングプロセッサ
 
-トレーシングの高レベル構成は次のとおりです:
+トレーシングの高レベルアーキテクチャは次のとおりです:
 
-- 初期化時にグローバル [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成します。これはトレースを作成し、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) で取得できます。
-- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を介してトレース／スパンをバッチ送信し、[`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) がそれらをバッチで OpenAI バックエンドへエクスポートします。
+- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成し、これは [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできます
+- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成され、バッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) にトレース／スパンを送信し、OpenAI バックエンドへバッチエクスポートします
 
-デフォルト設定を変更し、別のバックエンドへの送信やエクスポーターの挙動を変更する場合、次の 2 つの方法があります:
+このデフォルト設定をカスタマイズして別のバックエンドへ送信したり、エクスポータの挙動を変更したりする場合は、次の 2 つの方法があります:
 
-1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor)  
-   既定の送信先に加えて、トレース／スパンが準備完了時に受け取れる **追加** のトレースプロセッサを登録できます。
-2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors)  
-   既定のプロセッサを **置換** し、独自のトレースプロセッサのみを使用できます。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります。
+1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) を使用して **追加** のトレースプロセッサを登録し、トレース／スパンを受け取って独自処理を行う（OpenAI バックエンドへの送信はそのまま）
+2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) を使用してデフォルトのプロセッサを **置き換え** る。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります