From d2a9fe9b5961573dc6b2408567c3bad9b882e3d5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 7 Apr 2026 21:55:05 +0000 Subject: [PATCH] Update all translated document pages --- docs/ja/tracing.md | 103 ++++++++++++++++++++------------------- docs/ko/tracing.md | 98 ++++++++++++++++++++----------------- docs/zh/tracing.md | 119 +++++++++++++++++++++++---------------------- 3 files changed, 166 insertions(+), 154 deletions(-) diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index dd512baa20..9824fb2a44 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,61 +4,61 @@ search: --- # トレーシング -Agents SDK には組み込みのトレーシングがあり、エージェント実行中のイベントを包括的に記録します: LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生したカスタムイベントも含まれます。[Traces ダッシュボード](https://platform.openai.com/traces) を使うことで、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 +Agents SDK にはビルトインのトレーシングが含まれており、エージェント実行中のイベントの包括的な記録を収集します: LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらに発生したカスタムイベントも含まれます。[Traces ダッシュボード](https://platform.openai.com/traces) を使うと、開発中および本番環境でワークフローをデバッグ、可視化、監視できます。 !!!note - トレーシングはデフォルトで有効です。一般的な無効化方法は 3 つあります: + トレーシングはデフォルトで有効です。一般的には次の 3 つの方法で無効化できます: 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます - 2. [`set_tracing_disabled(True)`][agents.set_tracing_disabled] を使って、コード内でグローバルにトレーシングを無効化できます - 3. [`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して、単一の実行でトレーシングを無効化できます + 2. コード内で [`set_tracing_disabled(True)`][agents.set_tracing_disabled] を使って、グローバルにトレーシングを無効化できます + 3. 単一の実行に対しては、[`agents.run.RunConfig.tracing_disabled`][] を `True` に設定して無効化できます -***OpenAI の API を使用し、Zero Data Retention (ZDR) ポリシー下で運用している組織では、トレーシングは利用できません。*** +***OpenAI の API を利用し、Zero Data Retention ( ZDR ) ポリシー下で運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース**は 1 つの「ワークフロー」におけるエンドツーエンドの単一操作を表します。トレースはスパンで構成されます。トレースには次のプロパティがあります: - - `workflow_name`: 論理的なワークフローまたはアプリです。たとえば「Code generation」や「Customer service」です。 - - `trace_id`: トレースの一意 ID です。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: 同じ会話の複数トレースを関連付けるための任意のグループ ID です。たとえば、チャットスレッド ID を使えます。 +- **トレース**は「ワークフロー」の単一のエンドツーエンド操作を表します。トレースはスパンで構成されます。トレースには次のプロパティがあります: + - `workflow_name`: 論理的なワークフローまたはアプリです。たとえば「コード生成」や「カスタマーサービス」です。 + - `trace_id`: トレースの一意な ID です。渡さない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 + - `group_id`: 同じ会話内の複数のトレースを関連付けるための任意のグループ ID です。たとえばチャットスレッド ID を使用できます。 - `disabled`: True の場合、トレースは記録されません。 - - `metadata`: トレースの任意メタデータです。 + - `metadata`: トレースの任意のメタデータです。 - **スパン**は開始時刻と終了時刻を持つ操作を表します。スパンには次があります: - `started_at` と `ended_at` のタイムスタンプ。 - - 属するトレースを表す `trace_id` - - このスパンの親スパンを指す `parent_id`（存在する場合） - - スパンに関する情報である `span_data`。たとえば `AgentSpanData` には Agent の情報、`GenerationSpanData` には LLM 生成の情報などが含まれます。 + - `trace_id`: 所属するトレースを表します + - `parent_id`: このスパンの親スパン (存在する場合) を指します + - `span_data`: スパンに関する情報です。たとえば、`AgentSpanData` にはエージェントに関する情報、`GenerationSpanData` には LLM 生成に関する情報などが含まれます。 ## デフォルトトレーシング -デフォルトで SDK は次をトレースします: +デフォルトでは、SDK は次をトレースします: - `Runner.{run, run_sync, run_streamed}()` 全体は `trace()` でラップされます。 -- エージェントが実行されるたびに `agent_span()` でラップされます +- エージェントが実行されるたびに、`agent_span()` でラップされます - LLM 生成は `generation_span()` でラップされます - 関数ツール呼び出しはそれぞれ `function_span()` でラップされます - ガードレールは `guardrail_span()` でラップされます - ハンドオフは `handoff_span()` でラップされます -- 音声入力（speech-to-text）は `transcription_span()` でラップされます -- 音声出力（text-to-speech）は `speech_span()` でラップされます +- 音声入力 ( speech-to-text ) は `transcription_span()` でラップされます +- 音声出力 ( text-to-speech ) は `speech_span()` でラップされます - 関連する音声スパンは `speech_group_span()` の子になる場合があります -デフォルトでトレース名は「Agent workflow」です。`trace` を使う場合はこの名前を設定できます。または [`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定できます。 +デフォルトでは、トレース名は「Agent workflow」です。`trace` を使う場合はこの名前を設定でき、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の宛先へ送信できます（置き換えまたは副次的な宛先として）。 +さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを別の送信先にプッシュできます (置き換え先または副次的な送信先として)。 -## 長時間稼働ワーカーと即時エクスポート +## 長時間実行ワーカーと即時エクスポート -デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、 -数秒ごとにバックグラウンドでトレースをエクスポートし、メモリー内キューがサイズしきい値に達した場合はより早く実行し、 -さらにプロセス終了時に最終フラッシュも実行します。Celery、 -RQ、Dramatiq、または FastAPI バックグラウンドタスクのような長時間稼働ワーカーでは、これにより通常は追加コードなしで -トレースが自動的にエクスポートされますが、各ジョブ完了直後には Traces ダッシュボードに -表示されない場合があります。 +デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、トレースを +数秒ごとにバックグラウンドでエクスポートし、メモリ内キューがサイズしきい値に達した場合はより早く実行され、 +さらにプロセス終了時に最終フラッシュも行います。Celery、 +RQ、Dramatiq、または FastAPI のバックグラウンドタスクのような長時間実行ワーカーでは、これは通常、 +追加コードなしでトレースが自動エクスポートされることを意味しますが、各ジョブ終了直後には +Traces ダッシュボードにすぐ表示されない場合があります。 作業単位の終了時に即時配信保証が必要な場合は、 -トレースコンテキスト終了後に [`flush_traces()`][agents.tracing.flush_traces] を呼び出してください。 +トレースコンテキストを抜けた後に [`flush_traces()`][agents.tracing.flush_traces] を呼び出してください。 ```python from agents import Runner, flush_traces, trace @@ -96,13 +96,13 @@ async def run(prompt: str, background_tasks: BackgroundTasks): ``` [`flush_traces()`][agents.tracing.flush_traces] は現在バッファされているトレースとスパンが -エクスポートされるまでブロックするため、部分的に構築されたトレースをフラッシュしないよう -`trace()` が閉じた後で呼び出してください。デフォルトのエクスポート遅延を許容できる場合は、 -この呼び出しは省略できます。 +エクスポートされるまでブロックするため、部分的に構築されたトレースをフラッシュしないよう、 +`trace()` が閉じた後に呼び出してください。デフォルトのエクスポート遅延で問題ない場合は、 +この呼び出しを省略できます。 ## 上位レベルトレース -場合によっては、複数の `run()` 呼び出しを単一のトレースの一部にしたいことがあります。これは、コード全体を `trace()` でラップすることで実現できます。 +場合によっては、`run()` の複数回の呼び出しを単一のトレースの一部にしたいことがあります。これは、コード全体を `trace()` でラップすることで実現できます。 ```python from agents import Agent, Runner, trace @@ -117,49 +117,49 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run` への 2 回の呼び出しが `with trace()` でラップされているため、個々の実行は 2 つのトレースを作成するのではなく、全体トレースの一部になります。 +1. `Runner.run` の 2 回の呼び出しは `with trace()` でラップされているため、個別に 2 つのトレースを作成するのではなく、全体トレースの一部になります。 ## トレース作成 -[`trace()`][agents.tracing.trace] 関数を使ってトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります: +トレース作成には [`trace()`][agents.tracing.trace] 関数を使用できます。トレースは開始と終了が必要です。方法は 2 つあります: -1. **推奨**: `with trace(...) as my_trace` のように、トレースをコンテキストマネージャーとして使います。これにより適切なタイミングで自動的にトレースが開始・終了されます。 -2. [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を手動で呼び出すこともできます。 +1. **推奨**: `with trace(...) as my_trace` のように、トレースをコンテキストマネージャーとして使用します。これにより、適切なタイミングで自動的にトレースが開始・終了されます。 +2. 手動で [`trace.start()`][agents.tracing.Trace.start] と [`trace.finish()`][agents.tracing.Trace.finish] を呼び出すこともできます。 -現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。これは並行処理でも自動的に機能することを意味します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 +現在のトレースは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) を通じて追跡されます。これは並行処理でも自動的に機能することを意味します。トレースを手動で開始/終了する場合は、現在のトレースを更新するために `start()`/`finish()` に `mark_as_current` と `reset_current` を渡す必要があります。 ## スパン作成 -さまざまな [`*_span()`][agents.tracing.create] メソッドを使ってスパンを作成できます。一般的には、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するための [`custom_span()`][agents.tracing.custom_span] 関数も利用できます。 +スパン作成には、さまざまな [`*_span()`][agents.tracing.create] メソッドを使用できます。一般的には、スパンを手動で作成する必要はありません。カスタムスパン情報を追跡するために [`custom_span()`][agents.tracing.custom_span] 関数が利用できます。 スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これは Python の [`contextvar`](https://docs.python.org/3/library/contextvars.html) で追跡されます。 ## 機密データ -一部のスパンは機密性の可能性があるデータを取得する場合があります。 +一部のスパンは機密性の高い可能性があるデータを取得する場合があります。 -`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] を使ってそのデータ取得を無効化できます。 +`generation_span()` は LLM 生成の入力/出力を保存し、`function_span()` は関数呼び出しの入力/出力を保存します。これらには機密データが含まれる可能性があるため、[`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] でそのデータの取得を無効化できます。 -同様に、Audio スパンにはデフォルトで入力/出力音声の base64 エンコード済み PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定して、この音声データの取得を無効化できます。 +同様に、音声スパンにはデフォルトで入力音声と出力音声の base64 エンコードされた PCM データが含まれます。[`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] を設定することで、この音声データの取得を無効化できます。 -デフォルトでは `trace_include_sensitive_data` は `True` です。アプリ実行前に環境変数 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` を `true/1` または `false/0` に設定することで、コードを書かずにデフォルトを設定できます。 +デフォルトで `trace_include_sensitive_data` は `True` です。アプリ実行前に `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 環境変数を `true/1` または `false/0` に設定することで、コードを変更せずにデフォルト値を設定できます。 ## カスタムトレーシングプロセッサー トレーシングの高レベルアーキテクチャは次のとおりです: -- 初期化時に、トレース作成を担当するグローバル [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 -- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、これがトレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。`BackendSpanExporter` はスパンとトレースをバッチで OpenAI バックエンドにエクスポートします。 +- 初期化時に、トレース作成を担うグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 +- `TraceProvider` を [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] で構成し、このプロセッサーがトレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。`BackendSpanExporter` はスパンとトレースをバッチで OpenAI バックエンドにエクスポートします。 -このデフォルト設定をカスタマイズして、代替または追加のバックエンドにトレースを送信したり、エクスポーターの動作を変更したりするには、次の 2 つの方法があります: +このデフォルト設定をカスタマイズして、トレースを別または追加のバックエンドに送信したり、エクスポーターの挙動を変更したりするには、次の 2 つの方法があります: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] は、準備でき次第トレースとスパンを受け取る**追加**のトレースプロセッサーを追加できます。これにより、OpenAI バックエンドへの送信に加えて独自処理を行えます。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] は、デフォルトプロセッサーを独自のトレースプロセッサーで**置き換える**ことができます。これは、そうする `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送信されないことを意味します。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] を使うと、準備できたトレースとスパンを受け取る **追加の** トレースプロセッサーを追加できます。これにより、トレースを OpenAI バックエンドに送信しつつ、独自の処理も実行できます。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] を使うと、デフォルトプロセッサーを独自のトレースプロセッサーで **置き換え** できます。これは、そうする `TracingProcessor` を含めない限り、トレースが OpenAI バックエンドに送信されないことを意味します。 ## 非 OpenAI モデルでのトレーシング -トレーシングを無効化せずに OpenAI Traces ダッシュボードで無料トレーシングを有効化するために、非 OpenAI モデルで OpenAI API キーを使用できます。アダプター選択と設定時の注意点については、Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションを参照してください。 +非 OpenAI モデルでも OpenAI API キーを使うことで、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料トレーシングを有効にできます。アダプター選択とセットアップ時の注意点は、Models ガイドの [Third-party adapters](models/index.md#third-party-adapters) セクションを参照してください。 ```python import os @@ -180,7 +180,7 @@ agent = Agent( ) ``` -単一実行にのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` で渡してください。 +単一の実行に対してのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` 経由で渡してください。 ```python from agents import Runner, RunConfig @@ -193,12 +193,12 @@ await Runner.run( ``` ## 追加ノート -- Openai Traces ダッシュボードで無料トレースを確認できます。 +- Openai Traces ダッシュボードで無料トレースを表示します。 ## エコシステム統合 -以下のコミュニティおよびベンダー統合は、OpenAI Agents SDK のトレーシングサーフェスをサポートしています。 +次のコミュニティおよびベンダー統合は、OpenAI Agents SDK のトレーシングインターフェースをサポートしています。 ### 外部トレーシングプロセッサー一覧 @@ -224,4 +224,5 @@ await Runner.run( - [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) - [PostHog](https://posthog.com/docs/llm-analytics/installation/openai-agents) - [Traccia](https://traccia.ai/docs/integrations/openai-agents) -- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) \ No newline at end of file +- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) +- [HoneyHive](https://docs.honeyhive.ai/v2/integrations/openai-agents) \ No newline at end of file diff --git a/docs/ko/tracing.md b/docs/ko/tracing.md index 5579463a83..9c10056feb 100644 --- a/docs/ko/tracing.md +++ b/docs/ko/tracing.md @@ -4,55 +4,61 @@ search: --- # 트레이싱 -Agents SDK에는 내장 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생하는 이벤트(LLM 생성, 도구 호출, 핸드오프, 가드레일, 사용자 정의 이벤트 포함)에 대한 포괄적인 기록을 수집합니다. [Traces 대시보드](https://platform.openai.com/traces)를 사용하면 개발 중과 프로덕션에서 워크플로를 디버깅, 시각화, 모니터링할 수 있습니다. +Agents SDK에는 기본 제공 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생한 이벤트의 포괄적인 기록을 수집합니다: LLM 생성, 도구 호출, 핸드오프, 가드레일, 그리고 발생하는 사용자 정의 이벤트까지 포함됩니다. [Traces 대시보드](https://platform.openai.com/traces)를 사용하면 개발 중과 프로덕션에서 워크플로를 디버그, 시각화, 모니터링할 수 있습니다. !!!note - 트레이싱은 기본적으로 활성화되어 있습니다. 다음 세 가지 일반적인 방법으로 비활성화할 수 있습니다: + 트레이싱은 기본적으로 활성화되어 있습니다. 다음의 일반적인 세 가지 방법으로 비활성화할 수 있습니다: 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1`을 설정하여 전역적으로 트레이싱을 비활성화할 수 있습니다 - 2. 코드에서 [`set_tracing_disabled(True)`][agents.set_tracing_disabled]로 전역적으로 트레이싱을 비활성화할 수 있습니다 - 3. 단일 실행에 대해 [`agents.run.RunConfig.tracing_disabled`][]를 `True`로 설정하여 트레이싱을 비활성화할 수 있습니다 + 2. 코드에서 [`set_tracing_disabled(True)`][agents.set_tracing_disabled]를 사용해 전역적으로 트레이싱을 비활성화할 수 있습니다 + 3. 단일 실행에 대해 [`agents.run.RunConfig.tracing_disabled`][]를 `True`로 설정해 트레이싱을 비활성화할 수 있습니다 -***OpenAI API를 사용하면서 Zero Data Retention(ZDR) 정책을 적용하는 조직에서는 트레이싱을 사용할 수 없습니다.*** +***OpenAI API를 사용하면서 ZDR(Zero Data Retention) 정책으로 운영하는 조직에서는 트레이싱을 사용할 수 없습니다.*** ## 트레이스와 스팬 - **트레이스**는 하나의 "워크플로"에 대한 단일 end-to-end 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: - - `workflow_name`: 논리적 워크플로 또는 앱입니다. 예: "Code generation" 또는 "Customer service" + - `workflow_name`: 논리적 워크플로 또는 앱입니다. 예: "코드 생성" 또는 "고객 서비스" - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>`이어야 합니다 - - `group_id`: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 + - `group_id`: 선택적 그룹 ID로, 같은 대화의 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 - `disabled`: True이면 트레이스가 기록되지 않습니다 - `metadata`: 트레이스용 선택적 메타데이터입니다 - **스팬**은 시작 시간과 종료 시간이 있는 작업을 나타냅니다. 스팬에는 다음이 있습니다: - `started_at` 및 `ended_at` 타임스탬프 - - `trace_id`: 해당 스팬이 속한 트레이스를 나타냄 - - `parent_id`: 이 스팬의 상위 스팬을 가리킴(있는 경우) - - `span_data`: 스팬에 대한 정보입니다. 예를 들어 `AgentSpanData`는 에이전트 정보, `GenerationSpanData`는 LLM 생성 정보 등을 포함합니다 + - 소속된 트레이스를 나타내는 `trace_id` + - 이 스팬의 부모 스팬을 가리키는 `parent_id`(있는 경우) + - 스팬에 대한 정보인 `span_data` 예: `AgentSpanData`에는 Agent 정보가, `GenerationSpanData`에는 LLM 생성 정보가 포함됩니다 ## 기본 트레이싱 기본적으로 SDK는 다음을 트레이싱합니다: -- 전체 `Runner.{run, run_sync, run_streamed}()`는 `trace()`로 감싸집니다 -- 에이전트가 실행될 때마다 `agent_span()`으로 감싸집니다 -- LLM 생성은 `generation_span()`으로 감싸집니다 -- 함수 도구 호출은 각각 `function_span()`으로 감싸집니다 -- 가드레일은 `guardrail_span()`으로 감싸집니다 -- 핸드오프는 `handoff_span()`으로 감싸집니다 -- 오디오 입력(speech-to-text)은 `transcription_span()`으로 감싸집니다 -- 오디오 출력(text-to-speech)은 `speech_span()`으로 감싸집니다 -- 관련 오디오 스팬은 `speech_group_span()` 아래에 부모-자식으로 배치될 수 있습니다 +- 전체 `Runner.{run, run_sync, run_streamed}()`는 `trace()`로 래핑됩니다 +- 에이전트가 실행될 때마다 `agent_span()`으로 래핑됩니다 +- LLM 생성은 `generation_span()`으로 래핑됩니다 +- 함수 도구 호출은 각각 `function_span()`으로 래핑됩니다 +- 가드레일은 `guardrail_span()`으로 래핑됩니다 +- 핸드오프는 `handoff_span()`으로 래핑됩니다 +- 오디오 입력(음성-텍스트)은 `transcription_span()`으로 래핑됩니다 +- 오디오 출력(텍스트-음성)은 `speech_span()`으로 래핑됩니다 +- 관련 오디오 스팬은 `speech_group_span()` 아래에 부모로 연결될 수 있습니다 -기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하면 이 이름을 설정할 수 있고, [`RunConfig`][agents.run.RunConfig]를 통해 이름과 기타 속성을 구성할 수도 있습니다. +기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하면 이 이름을 설정할 수 있고, [`RunConfig`][agents.run.RunConfig]를 사용하면 이름 및 기타 속성을 구성할 수 있습니다. 또한 [사용자 정의 트레이스 프로세서](#custom-tracing-processors)를 설정해 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상). ## 장기 실행 워커와 즉시 내보내기 -기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 몇 초마다 백그라운드에서 트레이스를 내보내거나, 메모리 내 큐가 크기 임계값에 도달하면 더 빨리 내보내며, 프로세스 종료 시 최종 flush도 수행합니다. Celery, RQ, Dramatiq 또는 FastAPI 백그라운드 작업 같은 장기 실행 워커에서는 보통 추가 코드 없이도 트레이스가 자동으로 내보내지지만, 각 작업이 끝난 직후 Traces 대시보드에 즉시 표시되지 않을 수 있습니다. +기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 트레이스를 +몇 초마다 백그라운드에서 내보내거나, 메모리 내 큐가 크기 트리거에 도달하면 더 빨리 내보내며, +프로세스 종료 시 최종 플러시도 수행합니다. Celery, +RQ, Dramatiq 또는 FastAPI 백그라운드 작업 같은 장기 실행 워커에서는 일반적으로 트레이스가 +추가 코드 없이 자동으로 내보내지지만, 각 작업이 끝난 직후에는 Traces 대시보드에 즉시 +표시되지 않을 수 있습니다. -작업 단위 종료 시 즉시 전달 보장이 필요하다면, 트레이스 컨텍스트가 종료된 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출하세요. +작업 단위 종료 시 즉시 전달 보장이 필요하다면 +트레이스 컨텍스트를 종료한 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출하세요. ```python from agents import Runner, flush_traces, trace @@ -89,11 +95,14 @@ async def run(prompt: str, background_tasks: BackgroundTasks): return {"status": "queued"} ``` -[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬이 내보내질 때까지 블로킹하므로, 부분적으로 구성된 트레이스를 flush하지 않으려면 `trace()`가 닫힌 뒤 호출해야 합니다. 기본 내보내기 지연이 허용 가능한 경우 이 호출은 생략할 수 있습니다. +[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬이 +내보내질 때까지 블로킹하므로, 부분적으로 구성된 트레이스를 플러시하지 않도록 `trace()`가 +닫힌 뒤 호출하세요. 기본 내보내기 지연 시간이 허용 가능하다면 이 호출은 +생략할 수 있습니다. ## 상위 수준 트레이스 -경우에 따라 `run()` 호출 여러 개를 하나의 트레이스로 묶고 싶을 수 있습니다. 이 경우 전체 코드를 `trace()`로 감싸면 됩니다. +때로는 여러 `run()` 호출을 하나의 단일 트레이스에 포함하고 싶을 수 있습니다. 이 경우 전체 코드를 `trace()`로 래핑하면 됩니다. ```python from agents import Agent, Runner, trace @@ -108,49 +117,49 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. `Runner.run`에 대한 두 호출이 `with trace()`로 감싸져 있으므로, 각 실행은 별도의 트레이스 두 개를 만드는 대신 전체 트레이스의 일부가 됩니다 +1. 두 번의 `Runner.run` 호출이 `with trace()`로 래핑되어 있으므로, 개별 실행이 각각 두 개의 트레이스를 만드는 대신 전체 트레이스의 일부가 됩니다 ## 트레이스 생성 -[`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작과 종료가 필요하며, 이를 위한 두 가지 방법이 있습니다: +[`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작과 종료가 필요하며, 방법은 두 가지입니다: 1. **권장**: 트레이스를 컨텍스트 매니저로 사용합니다. 즉 `with trace(...) as my_trace` 형태입니다. 이렇게 하면 적절한 시점에 트레이스가 자동으로 시작/종료됩니다 -2. [`trace.start()`][agents.tracing.Trace.start]와 [`trace.finish()`][agents.tracing.Trace.finish]를 수동 호출할 수도 있습니다 +2. [`trace.start()`][agents.tracing.Trace.start]와 [`trace.finish()`][agents.tracing.Trace.finish]를 수동으로 호출할 수도 있습니다 -현재 트레이스는 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적됩니다. 즉, 동시성 환경에서도 자동으로 동작합니다. 트레이스를 수동으로 시작/종료하는 경우 현재 트레이스를 갱신하려면 `start()`/`finish()`에 `mark_as_current`와 `reset_current`를 전달해야 합니다. +현재 트레이스는 Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)를 통해 추적됩니다. 이는 동시성 환경에서도 자동으로 작동함을 의미합니다. 트레이스를 수동으로 시작/종료하는 경우 현재 트레이스를 갱신하기 위해 `start()`/`finish()`에 `mark_as_current`와 `reset_current`를 전달해야 합니다. ## 스팬 생성 -다양한 [`*_span()`][agents.tracing.create] 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로 스팬을 수동으로 만들 필요는 없습니다. 사용자 정의 스팬 정보를 추적하기 위해 [`custom_span()`][agents.tracing.custom_span] 함수를 사용할 수 있습니다. +다양한 [`*_span()`][agents.tracing.create] 메서드를 사용해 스팬을 생성할 수 있습니다. 일반적으로는 스팬을 수동으로 만들 필요가 없습니다. 사용자 정의 스팬 정보를 추적하기 위한 [`custom_span()`][agents.tracing.custom_span] 함수도 제공됩니다. -스팬은 자동으로 현재 트레이스에 속하며, Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)로 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. +스팬은 자동으로 현재 트레이스의 일부가 되며, Python [`contextvar`](https://docs.python.org/3/library/contextvars.html)로 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. ## 민감한 데이터 -일부 스팬은 잠재적으로 민감한 데이터를 캡처할 수 있습니다. +일부 스팬은 잠재적으로 민감한 데이터를 수집할 수 있습니다. -`generation_span()`은 LLM 생성의 입력/출력을 저장하고, `function_span()`은 함수 호출의 입력/출력을 저장합니다. 여기에 민감한 데이터가 포함될 수 있으므로 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 통해 해당 데이터 캡처를 비활성화할 수 있습니다. +`generation_span()`은 LLM 생성의 입력/출력을 저장하고, `function_span()`은 함수 호출의 입력/출력을 저장합니다. 여기에는 민감한 데이터가 포함될 수 있으므로 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data]를 통해 해당 데이터 수집을 비활성화할 수 있습니다. -마찬가지로 오디오 스팬에는 기본적으로 입력/출력 오디오에 대한 base64 인코딩 PCM 데이터가 포함됩니다. [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]를 구성해 이 오디오 데이터 캡처를 비활성화할 수 있습니다. +마찬가지로 오디오 스팬에는 기본적으로 입력/출력 오디오용 base64 인코딩 PCM 데이터가 포함됩니다. [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data]를 구성해 이 오디오 데이터 수집을 비활성화할 수 있습니다. -기본적으로 `trace_include_sensitive_data`는 `True`입니다. 코드를 변경하지 않고도 앱 실행 전에 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 환경 변수를 `true/1` 또는 `false/0`으로 내보내 기본값을 설정할 수 있습니다. +기본적으로 `trace_include_sensitive_data`는 `True`입니다. 앱 실행 전에 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 환경 변수를 `true/1` 또는 `false/0`으로 내보내 코드 없이 기본값을 설정할 수 있습니다. ## 사용자 정의 트레이싱 프로세서 트레이싱의 상위 수준 아키텍처는 다음과 같습니다: -- 초기화 시 트레이스 생성을 담당하는 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider]를 생성합니다 -- `TraceProvider`를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 구성하고, 이 프로세서는 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 전송하며, `BackendSpanExporter`는 스팬과 트레이스를 배치로 OpenAI 백엔드에 내보냅니다 +- 초기화 시 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider]를 생성하며, 이는 트레이스 생성을 담당합니다 +- `TraceProvider`는 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 구성되며, 이 프로세서는 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 전송하고, 해당 exporter는 스팬과 트레이스를 배치로 OpenAI 백엔드에 내보냅니다 -이 기본 구성을 사용자 지정하여 대체 또는 추가 백엔드로 트레이스를 보내거나 exporter 동작을 수정하려면 두 가지 방법이 있습니다: +기본 구성을 사용자 지정해 대체 또는 추가 백엔드로 트레이스를 전송하거나 exporter 동작을 수정하려면 두 가지 옵션이 있습니다: -1. [`add_trace_processor()`][agents.tracing.add_trace_processor]를 사용하면 준비된 트레이스와 스팬을 수신하는 **추가** 트레이스 프로세서를 더할 수 있습니다. 이를 통해 OpenAI 백엔드 전송과 더불어 자체 처리를 수행할 수 있습니다 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors]를 사용하면 기본 프로세서를 사용자 정의 트레이스 프로세서로 **교체**할 수 있습니다. 이 경우 해당 동작을 수행하는 `TracingProcessor`를 포함하지 않으면 트레이스가 OpenAI 백엔드로 전송되지 않습니다 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor]를 사용하면 준비된 트레이스와 스팬을 수신할 **추가** 트레이스 프로세서를 추가할 수 있습니다. 이를 통해 OpenAI 백엔드로 전송하는 것에 더해 자체 처리를 수행할 수 있습니다 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors]를 사용하면 기본 프로세서를 사용자 정의 트레이스 프로세서로 **대체**할 수 있습니다. 이 경우 해당 작업을 수행하는 `TracingProcessor`를 포함하지 않으면 트레이스가 OpenAI 백엔드로 전송되지 않습니다 -## non-OpenAI 모델에서의 트레이싱 +## 비 OpenAI 모델에서의 트레이싱 -트레이싱을 비활성화할 필요 없이 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화하려면 non-OpenAI 모델에 OpenAI API 키를 사용할 수 있습니다. 어댑터 선택 및 설정 시 주의사항은 Models 가이드의 [Third-party adapters](models/index.md#third-party-adapters) 섹션을 참조하세요. +트레이싱을 비활성화할 필요 없이 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화하기 위해 비 OpenAI 모델과 함께 OpenAI API 키를 사용할 수 있습니다. 어댑터 선택과 설정 시 주의사항은 Models 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션을 참고하세요. ```python import os @@ -171,7 +180,7 @@ agent = Agent( ) ``` -단일 실행에만 다른 트레이싱 키가 필요하다면 전역 exporter를 변경하는 대신 `RunConfig`로 전달하세요. +단일 실행에 대해서만 다른 트레이싱 키가 필요하다면 전역 exporter를 변경하는 대신 `RunConfig`를 통해 전달하세요. ```python from agents import Runner, RunConfig @@ -184,7 +193,7 @@ await Runner.run( ``` ## 추가 참고 사항 -- Openai Traces dashboard에서 무료 트레이스를 확인하세요 +- Openai Traces 대시보드에서 무료 트레이스를 확인하세요 ## 에코시스템 통합 @@ -215,4 +224,5 @@ await Runner.run( - [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) - [PostHog](https://posthog.com/docs/llm-analytics/installation/openai-agents) - [Traccia](https://traccia.ai/docs/integrations/openai-agents) -- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) \ No newline at end of file +- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) +- [HoneyHive](https://docs.honeyhive.ai/v2/integrations/openai-agents) \ No newline at end of file diff --git a/docs/zh/tracing.md b/docs/zh/tracing.md index fc8173fd39..df6ddc8761 100644 --- a/docs/zh/tracing.md +++ b/docs/zh/tracing.md @@ -4,60 +4,60 @@ search: --- # 追踪 -Agents SDK 包含内置追踪功能，可在智能体运行期间收集完整的事件记录：LLM 生成、工具调用、任务转移、安全防护措施，甚至发生的自定义事件。使用[Traces 控制台](https://platform.openai.com/traces)，你可以在开发和生产阶段调试、可视化并监控你的工作流。 +Agents SDK 包含内置追踪，可在智能体运行期间收集完整的事件记录：LLM 生成、工具调用、任务转移、安全防护措施，甚至发生的自定义事件。使用[Traces 控制台](https://platform.openai.com/traces)，你可以在开发和生产中调试、可视化并监控工作流。 !!!note - 追踪默认启用。你可以通过三种常见方式禁用： + 默认启用追踪。你可以通过三种常见方式禁用它： 1. 你可以通过设置环境变量 `OPENAI_AGENTS_DISABLE_TRACING=1` 全局禁用追踪 - 2. 你可以在代码中通过 [`set_tracing_disabled(True)`][agents.set_tracing_disabled] 全局禁用追踪 + 2. 你可以在代码中使用 [`set_tracing_disabled(True)`][agents.set_tracing_disabled] 全局禁用追踪 3. 你可以通过将 [`agents.run.RunConfig.tracing_disabled`][] 设为 `True` 来禁用单次运行的追踪 -***对于在 OpenAI API 下使用零数据保留（ZDR）策略的组织，追踪功能不可用。*** +***对于在 OpenAI API 下使用零数据保留（ZDR）策略的组织，追踪不可用。*** ## Traces 与 spans -- **Traces** 表示“工作流”的一次端到端操作。它们由 Span 组成。Traces 具有以下属性： +- **Traces** 表示“工作流”的一次端到端操作。它由 Span 组成。Traces 具有以下属性： - `workflow_name`：这是逻辑工作流或应用。例如“代码生成”或“客户服务”。 - - `trace_id`：Trace 的唯一 ID。如果你未传入则自动生成。格式必须为 `trace_<32_alphanumeric>`。 - - `group_id`：可选的组 ID，用于关联同一会话中的多个 Trace。例如，你可以使用聊天线程 ID。 - - `disabled`：如果为 True，则不会记录该 Trace。 - - `metadata`：Trace 的可选元数据。 -- **Spans** 表示具有开始和结束时间的操作。Spans 包含： + - `trace_id`：trace 的唯一 ID。如果你未传入，会自动生成。格式必须为 `trace_<32_alphanumeric>`。 + - `group_id`：可选的组 ID，用于关联同一会话中的多个 traces。例如，你可以使用聊天线程 ID。 + - `disabled`：若为 True，则不会记录该 trace。 + - `metadata`：trace 的可选元数据。 +- **Spans** 表示具有开始和结束时间的操作。Spans 具有： - `started_at` 和 `ended_at` 时间戳。 - - `trace_id`，表示其所属的 Trace - - `parent_id`，指向该 Span 的父 Span（如果有） - - `span_data`，即 Span 的信息。例如，`AgentSpanData` 包含智能体信息，`GenerationSpanData` 包含 LLM 生成信息，等等。 + - `trace_id`，表示其所属的 trace + - `parent_id`，指向该 Span 的父 Span（如有） + - `span_data`，即该 Span 的信息。例如，`AgentSpanData` 包含智能体信息，`GenerationSpanData` 包含 LLM 生成信息等。 ## 默认追踪 默认情况下，SDK 会追踪以下内容： -- 整个 `Runner.{run, run_sync, run_streamed}()` 会包裹在 `trace()` 中。 -- 每次智能体运行都会包裹在 `agent_span()` 中 -- LLM 生成会包裹在 `generation_span()` 中 -- 每次工具调用都会分别包裹在 `function_span()` 中 -- 安全防护措施会包裹在 `guardrail_span()` 中 -- 任务转移会包裹在 `handoff_span()` 中 -- 音频输入（语音转文本）会包裹在 `transcription_span()` 中 -- 音频输出（文本转语音）会包裹在 `speech_span()` 中 -- 相关音频 Span 可能作为 `speech_group_span()` 的子级 +- 整个 `Runner.{run, run_sync, run_streamed}()` 都包裹在 `trace()` 中。 +- 每次智能体运行都包裹在 `agent_span()` 中 +- LLM 生成包裹在 `generation_span()` 中 +- 每次工具调用都分别包裹在 `function_span()` 中 +- 安全防护措施包裹在 `guardrail_span()` 中 +- 任务转移包裹在 `handoff_span()` 中 +- 音频输入（语音转文本）包裹在 `transcription_span()` 中 +- 音频输出（文本转语音）包裹在 `speech_span()` 中 +- 相关音频 spans 可能作为 `speech_group_span()` 的子级 -默认情况下，Trace 名称为“Agent workflow”。如果你使用 `trace`，可以设置该名称；你也可以通过 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。 +默认情况下，trace 名称为“Agent workflow”。如果你使用 `trace`，可以设置该名称；你也可以通过 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。 -此外，你还可以设置[自定义追踪进程](#custom-tracing-processors)，将 Trace 推送到其他目标（作为替代或次级目标）。 +此外，你可以设置[自定义追踪进程](#custom-tracing-processors)，将 traces 推送到其他目的地（作为替代或次要目的地）。 -## 长时间运行的 worker 与立即导出 +## 长时间运行的 worker 与即时导出 -默认的 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 会在后台每隔几秒导出一次追踪， -或在内存队列达到大小触发阈值时更早导出， -并且在进程退出时执行最终 flush。在 Celery、 -RQ、Dramatiq 或 FastAPI 后台任务等长时间运行的 worker 中，这意味着追踪通常会自动导出， -无需额外代码，但每个任务刚结束后它们可能不会立即出现在 Traces 控制台中。 +默认的 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 会在后台每隔几秒导出一次 traces， +或者在内存队列达到大小触发条件时更早导出， +并且在进程退出时执行最终刷新。在 Celery、 +RQ、Dramatiq 或 FastAPI 后台任务等长时间运行的 worker 中，这意味着 traces 通常会自动导出， +无需额外代码，但它们可能不会在每个任务结束后立即出现在 Traces 控制台中。 -如果你需要在一个工作单元结束时立即送达的保证，请调用 -[`flush_traces()`][agents.tracing.flush_traces]（在 trace 上下文退出后）。 +如果你需要在一个工作单元结束时立即交付的保证，请在 +trace 上下文退出后调用 [`flush_traces()`][agents.tracing.flush_traces]。 ```python from agents import Runner, flush_traces, trace @@ -94,13 +94,13 @@ async def run(prompt: str, background_tasks: BackgroundTasks): return {"status": "queued"} ``` -[`flush_traces()`][agents.tracing.flush_traces] 会阻塞直到当前缓冲的 traces 和 spans -导出完成，因此应在 `trace()` 关闭后调用，以避免刷新到部分构建的 trace。若默认 -导出延迟可接受，则可跳过此调用。 +[`flush_traces()`][agents.tracing.flush_traces] 会阻塞，直到当前缓冲的 traces 和 spans +导出完成，因此请在 `trace()` 关闭后调用，以避免刷新尚未完整构建的 trace。若可接受 +默认导出延迟，则可跳过此调用。 -## 更高层级的 traces +## 高层级 traces -有时你可能希望多次调用 `run()` 属于同一个 trace。你可以通过将整段代码包裹在 `trace()` 中来实现。 +有时你可能希望多次 `run()` 调用属于同一个 trace。你可以通过将整段代码包裹在 `trace()` 中来实现。 ```python from agents import Agent, Runner, trace @@ -115,49 +115,49 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. 由于两次对 `Runner.run` 的调用都包裹在 `with trace()` 中，单次运行将归入整体 trace，而不是创建两个 trace。 +1. 由于两次 `Runner.run` 调用都包裹在 `with trace()` 中，单次运行将成为整体 trace 的一部分，而不是创建两个 trace。 ## 创建 traces -你可以使用 [`trace()`][agents.tracing.trace] 函数创建 trace。Trace 需要被启动和结束。你有两种方式： +你可以使用 [`trace()`][agents.tracing.trace] 函数来创建 trace。trace 需要被启动和结束。你有两个选项： -1. **推荐**：将 trace 用作上下文管理器，即 `with trace(...) as my_trace`。这样会在正确的时间自动启动和结束 trace。 +1. **推荐**：将 trace 用作上下文管理器，即 `with trace(...) as my_trace`。这会在正确时间自动启动并结束 trace。 2. 你也可以手动调用 [`trace.start()`][agents.tracing.Trace.start] 和 [`trace.finish()`][agents.tracing.Trace.finish]。 -当前 trace 通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。这意味着它可自动适配并发场景。如果你手动启动/结束 trace，则需要向 `start()`/`finish()` 传入 `mark_as_current` 和 `reset_current` 以更新当前 trace。 +当前 trace 通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。这意味着它可自动适配并发。若你手动启动/结束 trace，则需要向 `start()`/`finish()` 传入 `mark_as_current` 和 `reset_current` 来更新当前 trace。 ## 创建 spans -你可以使用各种 [`*_span()`][agents.tracing.create] 方法创建 span。通常你不需要手动创建 span。可使用 [`custom_span()`][agents.tracing.custom_span] 函数跟踪自定义 span 信息。 +你可以使用各种 [`*_span()`][agents.tracing.create] 方法来创建 span。通常，你不需要手动创建 spans。也提供了 [`custom_span()`][agents.tracing.custom_span] 函数来跟踪自定义 span 信息。 -Spans 会自动归属于当前 trace，并嵌套在最近的当前 span 下，该状态通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。 +Spans 会自动归属于当前 trace，并嵌套在最近的当前 span 下，而该状态通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。 ## 敏感数据 -某些 span 可能会捕获潜在的敏感数据。 +某些 spans 可能会捕获潜在敏感数据。 -`generation_span()` 会存储 LLM 生成的输入/输出，`function_span()` 会存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用这类数据的采集。 +`generation_span()` 会存储 LLM 生成的输入/输出，`function_span()` 会存储函数调用的输入/输出。这些内容可能包含敏感数据，因此你可以通过 [`RunConfig.trace_include_sensitive_data`][agents.run.RunConfig.trace_include_sensitive_data] 禁用这些数据的捕获。 -同样，音频 span 默认会包含输入和输出音频的 base64 编码 PCM 数据。你可以通过配置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 禁用该音频数据采集。 +类似地，音频 spans 默认包含输入与输出音频的 base64 编码 PCM 数据。你可以通过配置 [`VoicePipelineConfig.trace_include_sensitive_audio_data`][agents.voice.pipeline_config.VoicePipelineConfig.trace_include_sensitive_audio_data] 禁用这些音频数据的捕获。 -默认情况下，`trace_include_sensitive_data` 为 `True`。你可以在运行应用前导出 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 环境变量并设为 `true/1` 或 `false/0`，从而无需改代码设置默认值。 +默认情况下，`trace_include_sensitive_data` 为 `True`。你可以在运行应用前通过导出 `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` 环境变量并设为 `true/1` 或 `false/0` 来在无代码情况下设置默认值。 ## 自定义追踪进程 -追踪的高层架构如下： +追踪的高层架构为： -- 在初始化时，我们会创建全局 [`TraceProvider`][agents.tracing.setup.TraceProvider]，负责创建 traces。 -- 我们为 `TraceProvider` 配置 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，它将 traces/spans 批量发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者再将 spans 和 traces 批量导出到 OpenAI 后端。 +- 初始化时，我们会创建全局 [`TraceProvider`][agents.tracing.setup.TraceProvider]，其负责创建 traces。 +- 我们将 `TraceProvider` 配置为使用 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，该进程会将 traces/spans 批量发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者再将 spans 和 traces 批量导出到 OpenAI 后端。 -若要自定义此默认设置，将 traces 发送到替代或附加后端，或修改导出器行为，你有两种选择： +要自定义此默认设置，以将 traces 发送到替代或附加后端，或修改导出器行为，你有两个选项： -1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加一个**额外的**追踪进程，在 traces 和 spans 就绪时接收它们。这使你可以在发送 traces 到 OpenAI 后端之外执行自己的处理。 -2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自己的追踪进程**替换**默认进程。这意味着除非你包含可执行该发送行为的 `TracingProcessor`，否则 traces 不会发送到 OpenAI 后端。 +1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许你添加**额外的**追踪进程，它会在 traces 和 spans 就绪时接收它们。这使你可以在发送到 OpenAI 后端之外执行自己的处理。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自己的追踪进程**替换**默认进程。这意味着除非你包含一个会这样做的 `TracingProcessor`，否则 traces 不会发送到 OpenAI 后端。 ## 使用非 OpenAI 模型进行追踪 -你可以将 OpenAI API key 与非 OpenAI 模型一起使用，以在 OpenAI Traces 控制台中启用免费追踪，而无需禁用追踪。有关适配器选择与设置注意事项，请参阅 Models 指南中的[第三方适配器](models/index.md#third-party-adapters)部分。 +你可以将 OpenAI API key 与非 OpenAI 模型一起使用，以在 OpenAI Traces 控制台中启用免费追踪，而无需禁用追踪。有关适配器选择和设置注意事项，请参阅 Models 指南中的[第三方适配器](models/index.md#third-party-adapters)部分。 ```python import os @@ -178,7 +178,7 @@ agent = Agent( ) ``` -如果你只需要为单次运行使用不同的追踪 key，请通过 `RunConfig` 传入，而不是修改全局导出器。 +如果你仅需为单次运行使用不同的追踪密钥，请通过 `RunConfig` 传入，而不是更改全局导出器。 ```python from agents import Runner, RunConfig @@ -191,12 +191,12 @@ await Runner.run( ``` ## 附加说明 -- 在 Openai Traces 控制台查看免费追踪。 +- 在 Openai Traces 控制台查看免费 traces。 -## 生态集成 +## 生态系统集成 -以下社区与厂商集成支持 OpenAI Agents SDK 的追踪接口。 +以下社区与供应商集成支持 OpenAI Agents SDK 追踪接口。 ### 外部追踪进程列表 @@ -222,4 +222,5 @@ await Runner.run( - [Agenta](https://docs.agenta.ai/observability/integrations/openai-agents) - [PostHog](https://posthog.com/docs/llm-analytics/installation/openai-agents) - [Traccia](https://traccia.ai/docs/integrations/openai-agents) -- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) \ No newline at end of file +- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) +- [HoneyHive](https://docs.honeyhive.ai/v2/integrations/openai-agents) \ No newline at end of file