Skip to content

Commit 08508ab

Browse files
dkundel-openaidkundel-openai
committed
update japanese docs
1 parent e15fad5 commit 08508ab

File tree

2 files changed

+61
-65
lines changed

2 files changed

+61
-65
lines changed

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

Lines changed: 44 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -7,104 +7,100 @@ import { Aside, Code } from '@astrojs/starlight/components';
77
import customTraceExample from '../../../../../../examples/docs/custom-trace.ts?raw';
88
import cloudflareWorkers from '../../../../../../examples/docs/tracing/cloudflareWorkers.ts?raw';
99

10-
Agents SDK にはトレーシング機能が組み込まれており、エージェント実行中に発生するイベント — LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベント — を網羅的に記録します。
11-
[Traces ダッシュボード](https://platform.openai.com/traces) を使うと、開発時および本番環境でワークフローをデバッグ、可視化、監視できます。
10+
Agents SDK にはビルトインの トレーシング が含まれており、エージェント実行中の LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらにはカスタムイベントまで網羅的に記録します。[Traces ダッシュボード](https://platform.openai.com/traces) を使用すると、開発時や本番環境でワークフローをデバッグ、可視化、監視できます。
1211

1312
<Aside type="note">
1413

1514
トレーシングはデフォルトで有効です。無効化する方法は 2 つあります。
1615

17-
1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、トレーシングを全体で無効化する
18-
2. 単一の実行に対して [`RunConfig.tracingDisabled`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#tracingdisabled) を `true` に設定する
16+
1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定してグローバルに無効化する
17+
2. 1 回の実行だけ無効化したい場合は [`RunConfig.tracingDisabled`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#tracingdisabled) に `true` を設定する
1918

20-
**_OpenAI の API を Zero Data Retention (ZDR) ポリシーでご利用の組織では、トレーシングを使用できません。_**
19+
**_OpenAI の API を Zero Data Retention (ZDR) ポリシーで利用している組織では、トレーシングは利用できません。_**
2120

2221
</Aside>
2322

24-
## Export loop lifecycle
23+
## エクスポートループのライフサイクル
2524

26-
ほとんどの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザーや Cloudflare Workers では、この機能はデフォルトで無効になっています。キューにたまり過ぎた場合は自動でエクスポートされますが、定期的には行われません。そのため、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を呼び出して手動でトレースをエクスポートしてください。
25+
多くの環境では、トレースは一定間隔で自動的にエクスポートされます。ブラウザや Cloudflare Workers ではこの機能はデフォルトで無効になっています。キューに溜まりすぎた場合はエクスポートされますが、定期的にはエクスポートされません。そのため、コードのライフサイクルの一部として `getGlobalTraceProvider().forceFlush()` を呼び出して手動でエクスポートしてください。
2726

28-
たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックに包み、`waitUntil` と共に forceFlush を呼び出して、ワーカー終了前にトレースがエクスポートされるようにします。
27+
たとえば Cloudflare Worker では、コードを `try/catch/finally` ブロックにラップし、`waitUntil` とともに force flush を呼び出して、ワーカー終了前にトレースがエクスポートされるようにします。
2928

3029
<Code
3130
lang="typescript"
3231
code={cloudflareWorkers.replace(/\s+\/\/ @ts-expect-error.*$/m, '')}
3332
meta="{13}"
3433
/>
3534

36-
## Traces and spans
35+
## トレースとスパン
3736

38-
- **Traces** はワークフロー全体の 1 回のエンドツーエンド操作を表します。次のプロパティがあります:
39-
- `workflow_name`: 論理的なワークフローまたはアプリ名。例︰"Code generation" や "Customer service"
40-
- `trace_id`: トレースの一意な ID。渡さない場合は自動生成。形式は `trace_<32_alphanumeric>`
41-
- `group_id`: 省略可。同一会話の複数トレースを関連付けるための ID。例︰チャットスレッド ID
42-
- `disabled`: `true` の場合、このトレースは記録されません
37+
- **トレース (Trace)** はワークフローの単一のエンドツーエンド操作を表します。トレースはスパンで構成され、次のプロパティを持ちます:
38+
- `workflow_name`: 論理的なワークフローまたはアプリ名。例: "Code generation" や "Customer service"
39+
- `trace_id`: トレースの一意 ID。指定しない場合は自動生成。形式は `trace_<32_alphanumeric>`
40+
- `group_id`: 任意のグループ ID。同じ会話からの複数トレースをリンクするために使用。例: チャットスレッド ID
41+
- `disabled`: `true` の場合、このトレースは記録されない
4342
- `metadata`: トレースに付与する任意のメタデータ
44-
- **Spans** は開始時刻と終了時刻を持つ操作を表します。プロパティは次のとおりです:
43+
- **スパン (Span)** は開始時刻と終了時刻を持つ操作を表します。スパンは以下を持ちます:
4544
- `started_at` と `ended_at` タイムスタンプ
46-
- `trace_id`: 所属するトレース ID
47-
- `parent_id`: 親 Span がある場合、その Span の ID
48-
- `span_data`: Span の情報。例︰`AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など
45+
- 所属するトレースを示す `trace_id`
46+
- 親スパンを指す `parent_id` (存在する場合)
47+
- スパンに関する情報を含む `span_data`。たとえば `AgentSpanData` はエージェント情報、`GenerationSpanData` は LLM 生成情報など
4948

50-
## Default tracing
49+
## デフォルトのトレーシング
5150

52-
デフォルトで SDK は以下をトレースします:
51+
デフォルトでは SDK が次をトレースします:
5352

54-
- `run()` または `Runner.run()` 全体を `Trace` でラップ
53+
- `run()` または `Runner.run()` 全体を 1 つの `Trace` でラップ
5554
- エージェントが実行されるたびに `AgentSpan` でラップ
5655
- LLM 生成を `GenerationSpan` でラップ
5756
- 関数ツール呼び出しをそれぞれ `FunctionSpan` でラップ
5857
- ガードレールを `GuardrailSpan` でラップ
5958
- ハンドオフを `HandoffSpan` でラップ
6059

61-
デフォルトのトレース名は "Agent workflow" です。`withTrace` を使ってこの名前を変更できます。または [`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前や他のプロパティを設定できます。
60+
トレース名はデフォルトで "Agent workflow" です。`withTrace` を使用してこの名前を設定するか、[`RunConfig.workflowName`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#workflowname) で名前やその他のプロパティを設定できます。
6261

63-
さらに、[カスタム trace プロセッサ](#custom-tracing-processors) を設定して、トレースを他の送信先へ出力（置換または追加送信）できます。
62+
さらに、[カスタムトレースプロセッサ](#custom-tracing-processors) を設定して、（置き換えまたは追加の送信先として）他の場所にトレースを送信できます。
6463

65-
### Voice agent tracing
64+
### 音声エージェントのトレーシング
6665

67-
デフォルトの OpenAI Realtime API で `RealtimeAgent` と `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を指定するか、`OPENAI_AGENTS_DISABLE_TRACING` 環境変数を設定しない限り、トレーシングは Realtime API 側で自動的に行われます。
66+
デフォルトの OpenAI Realtime API とともに `RealtimeAgent` と `RealtimeSession` を使用している場合、`RealtimeSession` で `tracingDisabled: true` を設定するか、`OPENAI_AGENTS_DISABLE_TRACING` 環境変数を使用して無効化しない限り、トレーシングは自動的に Realtime API 側で行われます。
6867

69-
詳細は [音声エージェントの概要](/openai-agents-js/guides/voice-agents) をご覧ください。
68+
詳細は [音声エージェントの概要](/openai-agents-js/ja/guides/voice-agents) を参照してください。
7069

71-
## Higher level traces
70+
## 高レベルのトレース
7271

73-
複数回の `run()` 呼び出しを 1 つのトレースとしてまとめたい場合は、コード全体を `withTrace()` でラップします。
72+
複数回の `run()` 呼び出しを 1 つのトレースにまとめたい場合があります。その場合はコード全体を `withTrace()` でラップします。
7473

7574
<Code lang="typescript" code={customTraceExample} />
7675

77-
1. `withTrace()` で 2 回の `run` 呼び出しをラップしているため、それぞれが個別のトレースを作らず、全体トレースの一部になります。
76+
1. 2 回の `run` 呼び出しは `withTrace()` でラップされているため、個別のトレースを作成せず全体トレースの一部になります。
7877

79-
## Creating traces
78+
## トレースの作成
8079

81-
[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数でトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` で手動生成し、それを `withTrace()` に渡す方法もあります。
80+
[`withTrace()`](/openai-agents-js/openai/agents-core/functions/withtrace/) 関数を使ってトレースを作成できます。あるいは `getGlobalTraceProvider().createTrace()` で手動で新しいトレースを作成し、それを `withTrace()` に渡すことも可能です。
8281

83-
現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage)（および同等の環境ポリフィル）で管理されるため、並行処理でも自動的に機能します。
82+
現在のトレースは [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルを通じて追跡されます。これにより並行処理でも自動的に機能します。
8483

85-
## Creating spans
84+
## スパンの作成
8685

87-
`create*Span()` メソッド（例︰`createGenerationSpan()`, `createFunctionSpan()` など）で Span を生成できます。通常は手動で作成する必要はありません。カスタム情報を追跡したい場合は [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) を使用してください。
86+
`createGenerationSpan()` や `createFunctionSpan()` などの `create*Span()` メソッドを使ってスパンを作成できます。一般的には手動でスパンを作成する必要はありません。カスタムスパンを追跡するための [`createCustomSpan()`](/openai-agents-js/openai/agents-core/functions/createcustomspan/) も用意されています。
8887

89-
Span は自動的に現在のトレースに含まれ、最も近い現在の Span の下にネストされます。この管理も [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) により行われます。
88+
スパンは自動的に現在のトレースに属し、最も近い現在のスパンの下にネストされます。これも [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) または各環境のポリフィルで追跡されます。
9089

91-
## Sensitive data
90+
## 機微なデータ
9291

93-
一部の Span では機密データが記録される可能性があります。
92+
一部のスパンは機微なデータを記録する場合があります。
9493

95-
`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。機密データを含む恐れがある場合は [`RunConfig.traceIncludeSensitiveData
96-
`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) を使って記録を無効化できます。
94+
`createGenerationSpan()` は LLM 生成の入出力を、`createFunctionSpan()` は関数呼び出しの入出力を保存します。これらに機微なデータが含まれる可能性があるため、[`RunConfig.traceIncludeSensitiveData`](/openai-agents-js/openai/agents-core/type-aliases/runconfig/#traceincludesensitivedata) で記録を無効化できます。
9795

98-
## Custom tracing processors
96+
## カスタムトレーシングプロセッサ
9997

100-
トレーシングの高レベル構成は次のとおりです。
98+
トレーシングの高レベルアーキテクチャは次のとおりです:
10199

102-
- 初期化時にグローバル [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) が作成され、[`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) から取得できます。
103-
- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) を使用して Span と Trace をバッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) に送信し、OpenAI バックエンドへエクスポートします。
100+
- 初期化時にグローバルな [`TraceProvider`](/openai-agents-js/openai/agents-core/classes/traceprovider) を作成し、これは [`getGlobalTraceProvider()`](/openai-agents-js/openai/agents-core/functions/getglobaltraceprovider/) からアクセスできます
101+
- `TraceProvider` は [`BatchTraceProcessor`](/openai-agents-js/openai/agents-core/classes/batchtraceprocessor/) で構成され、バッチで [`OpenAITracingExporter`](/openai-agents-js/openai/agents-openai/classes/openaitracingexporter/) にトレース／スパンを送信し、OpenAI バックエンドへバッチエクスポートします
104102

105-
このデフォルト設定をカスタマイズして、別のバックエンドへ送信したりエクスポーターの動作を変更したりするには、次のいずれかを使用します。
103+
このデフォルト設定をカスタマイズして別のバックエンドへ送信したり、エクスポータの挙動を変更したりする場合は、次の 2 つの方法があります:
106104

107-
1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor)
108-
既定の送信に加えて **追加** の Trace プロセッサを登録し、トレースや Span を受信して独自処理を行えます。
109-
2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors)
110-
デフォルトのプロセッサを **置換** して独自プロセッサを設定します。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります。
105+
1. [`addTraceProcessor()`](/openai-agents-js/openai/agents-core/functions/addtraceprocessor) を使用して **追加** のトレースプロセッサを登録し、トレース／スパンを受け取って独自処理を行う（OpenAI バックエンドへの送信はそのまま）
106+
2. [`setTraceProcessors()`](/openai-agents-js/openai/agents-core/functions/settraceprocessors) を使用してデフォルトのプロセッサを **置き換え** る。OpenAI バックエンドへ送信したい場合は、その機能を持つ `TracingProcessor` を含める必要があります

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

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,38 +3,38 @@ title: トラブルシューティング
33
description: Learn how to troubleshoot issues with the OpenAI Agents SDK.
44
---
55

6-
## 対応環境
6+
## サポートされる実行環境
77

8-
OpenAI Agents SDK は、以下のサーバー環境でサポートされます:
8+
OpenAI Agents SDK は次のサーバー環境でサポートされています:
99

10-
- Node.js 22 以降
11-
- Deno 2.35 以降
12-
- Bun 1.2.5 以降
10+
- Node.js 22+
11+
- Deno 2.35+
12+
- Bun 1.2.5+
1313

1414
### 制限付きサポート
1515

16-
- **Cloudflare Workers**: Agents SDK は Cloudflare Workers でも使用できますが、現時点では以下の制限があります
17-
- SDK には `nodejs_compat` を有効にする必要があります
18-
- リクエスト終了時にトレースを手動でフラッシュする必要があります。詳細は [トレーシングガイドを参照](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle)
19-
- Cloudflare Workers では `AsyncLocalStorage` のサポートが限定的なため、一部のトレースが正確でない場合があります
20-
- **ブラウザ**:
16+
- **Cloudflare Workers**: Agents SDK は Cloudflare Workers でも利用できますが、いくつか制限があります:
17+
- 現在 SDK では `nodejs_compat` を有効にする必要があります
18+
- リクエスト終了時にトレースを手動でフラッシュする必要があります。詳細は [トレーシング](/openai-agents-js/ja/guides/tracing#export-loop-lifecycle) を参照してください
19+
- Cloudflare Workers が `AsyncLocalStorage` を十分にサポートしていないため、一部のトレースが正確でない場合があります
20+
- **Browsers**:
2121
- ブラウザでは現在トレーシングはサポートされていません
2222
- **v8 isolates**:
23-
- 適切なブラウザ向けポリフィルを備えたバンドラーを使用すれば SDK を v8 isolates 向けにバンドルできますが、トレーシングは機能しません
24-
- v8 isolates での動作は十分にテストされていません
23+
- 適切なブラウザ用ポリフィルを有するバンドラーを使えば v8 isolates 向けに SDK をバンドルできますが、トレーシングは動作しません
24+
- v8 isolates については十分なテストが行われていません
2525

2626
## デバッグログ
2727

28-
SDK で問題が発生した場合、デバッグログを有効にすると状況を詳しく把握できます。
28+
SDK の利用中に問題が発生した場合、デバッグログを有効にすると詳細情報を取得できます。
2929

30-
`DEBUG` 環境変数を `openai-agents:*` に設定してデバッグログを有効にします。
30+
`DEBUG` 環境変数を `openai-agents:*` に設定するとデバッグログが有効になります。
3131

3232
```bash
3333
DEBUG=openai-agents:*
3434
```
3535

36-
また、特定のコンポーネントに絞ってデバッグすることもできます:
36+
特定部分だけを対象にデバッグすることもできます:
3737

38-
- `openai-agents:core` — SDK のメイン実行ロジック
39-
- `openai-agents:openai` — OpenAI API への呼び出し
38+
- `openai-agents:core` — SDK の主要な実行ロジック
39+
- `openai-agents:openai` — OpenAI API 呼び出し
4040
- `openai-agents:realtime` — Realtime Agents コンポーネント

0 commit comments

Comments
 (0)