diff --git a/docs/ja/tracing.md b/docs/ja/tracing.md index a5fc9e7e29..67a089b5bc 100644 --- a/docs/ja/tracing.md +++ b/docs/ja/tracing.md @@ -4,35 +4,35 @@ 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` に設定して、単一の実行に対してトレーシングを無効化できます + 1. 環境変数 `OPENAI_AGENTS_DISABLE_TRACING=1` を設定して、グローバルにトレーシングを無効化できます + 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 ) ポリシーの下で運用している組織では、トレーシングは利用できません。*** ## トレースとスパン -- **トレース**は「ワークフロー」の単一のエンドツーエンド操作を表します。トレースはスパンで構成されます。トレースには次のプロパティがあります。 +- **トレース** は「ワークフロー」の単一のエンドツーエンド操作を表します。スパンで構成されます。トレースには次のプロパティがあります。 - `workflow_name`: 論理的なワークフローまたはアプリです。たとえば「Code generation」や「Customer service」です。 - `trace_id`: トレースの一意な ID です。指定しない場合は自動生成されます。形式は `trace_<32_alphanumeric>` である必要があります。 - - `group_id`: オプションのグループ ID で、同じ会話からの複数のトレースを関連付けるために使用します。たとえばチャットスレッド ID を使用できます。 + - `group_id`: 同じ会話からの複数のトレースを関連付けるための任意のグループ ID です。たとえば、チャットスレッド ID を使用できます。 - `disabled`: True の場合、トレースは記録されません。 - - `metadata`: トレースのオプションのメタデータです。 -- **スパン**は開始時刻と終了時刻を持つ操作を表します。スパンには次があります。 + - `metadata`: トレースの任意のメタデータです。 +- **スパン** は開始時刻と終了時刻を持つ操作を表します。スパンには次があります。 - `started_at` と `ended_at` のタイムスタンプ。 - - `trace_id`。所属するトレースを表します - - `parent_id`。このスパンの親スパン(存在する場合)を指します - - `span_data`。スパンに関する情報です。たとえば `AgentSpanData` にはエージェントの情報が含まれ、`GenerationSpanData` には LLM 生成の情報が含まれます。 + - `trace_id`: 属するトレースを表します + - `parent_id`: このスパンの親スパン(存在する場合)を指します + - `span_data`: スパンに関する情報です。たとえば `AgentSpanData` にはエージェントの情報、`GenerationSpanData` には LLM 生成の情報などが含まれます。 -## デフォルトのトレーシング +## デフォルトトレーシング -デフォルトでは、 SDK は次をトレースします。 +デフォルトで、 SDK は次をトレースします。 - `Runner.{run, run_sync, run_streamed}()` 全体は `trace()` でラップされます。 - エージェントが実行されるたびに、`agent_span()` でラップされます @@ -42,15 +42,15 @@ Agents SDK には組み込みのトレーシングが含まれており、エー - ハンドオフは `handoff_span()` でラップされます - 音声入力( speech-to-text )は `transcription_span()` でラップされます - 音声出力( text-to-speech )は `speech_span()` でラップされます -- 関連する音声スパンは `speech_group_span()` の配下になる場合があります +- 関連する音声スパンは `speech_group_span()` の子になる場合があります -デフォルトでは、トレース名は「Agent workflow」です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] で名前やその他のプロパティを設定することもできます。 +デフォルトで、トレース名は「Agent workflow」です。`trace` を使用する場合はこの名前を設定できます。また、[`RunConfig`][agents.run.RunConfig] で名前や他のプロパティを設定することもできます。 -さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へ送ることができます(置き換えまたは副次的な送信先として)。 +さらに、[カスタムトレースプロセッサー](#custom-tracing-processors) を設定して、トレースを他の送信先へプッシュできます(置き換えまたは二次送信先として)。 -## 高レベルのトレース +## 上位レベルトレース -場合によっては、複数回の `run()` 呼び出しを単一のトレースの一部にしたいことがあります。これはコード全体を `trace()` でラップすることで実現できます。 +場合によっては、`run()` への複数回の呼び出しを 1 つのトレースに含めたいことがあります。これを行うには、コード全体を `trace()` でラップします。 ```python from agents import Agent, Runner, trace @@ -71,43 +71,43 @@ async def main(): [`trace()`][agents.tracing.trace] 関数を使用してトレースを作成できます。トレースは開始と終了が必要です。方法は 2 つあります。 -1. **推奨**: `with trace(...) as my_trace` のように、トレースをコンテキストマネージャーとして使用します。これにより、適切なタイミングでトレースが自動的に開始・終了されます。 +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) によって追跡されます。 +スパンは自動的に現在のトレースの一部となり、最も近い現在のスパンの下にネストされます。これは 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` として export します。 -## カスタムトレースプロセッサー +## カスタムトレーシングプロセッサー トレーシングの高レベルアーキテクチャは次のとおりです。 - 初期化時に、トレース作成を担当するグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。 -- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、トレース/スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信します。`BackendSpanExporter` はスパンとトレースをバッチで OpenAI バックエンドにエクスポートします。 +- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定し、トレース / スパンをバッチで [`BackendSpanExporter`][agents.tracing.processors.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 API キーを非 OpenAI モデルとともに使用して、トレーシングを無効化せずに OpenAI Traces ダッシュボードで無料トレーシングを有効化できます。 +OpenAI API キーを非 OpenAI モデルと共に使用して、トレーシングを無効化することなく OpenAI Traces ダッシュボードで無料トレーシングを有効化できます。 ```python import os @@ -128,7 +128,7 @@ agent = Agent( ) ``` -単一の実行に対してのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` 経由で渡してください。 +単一の実行でのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに `RunConfig` 経由で渡してください。 ```python from agents import Runner, RunConfig @@ -140,13 +140,13 @@ await Runner.run( ) ``` -## 追加メモ -- Openai Traces ダッシュボードで無料トレースを表示します。 +## 追加の注意事項 +- Openai Traces ダッシュボードで無料トレースを確認します。 -## エコシステム統合 +## エコシステム連携 -以下のコミュニティおよびベンダー統合は、OpenAI Agents SDK のトレーシング機能をサポートしています。 +次のコミュニティおよびベンダー連携は、OpenAI Agents SDK のトレーシングサーフェスをサポートしています。 ### 外部トレーシングプロセッサー一覧 @@ -171,4 +171,5 @@ await Runner.run( - [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) - [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) \ No newline at end of file +- [Traccia](https://traccia.ai/docs/integrations/openai-agents) +- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) \ No newline at end of file diff --git a/docs/ko/tracing.md b/docs/ko/tracing.md index dc391d8c0a..e10cdbcb70 100644 --- a/docs/ko/tracing.md +++ b/docs/ko/tracing.md @@ -4,31 +4,31 @@ search: --- # 트레이싱 -Agents SDK에는 내장 트레이싱이 포함되어 있으며, 에이전트 실행 중 발생하는 이벤트(LLM 생성, 도구 호출, 핸드오프, 가드레일, 사용자 정의 이벤트 포함)의 포괄적인 기록을 수집합니다. [Traces dashboard](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]를 사용해 전역적으로 트레이싱을 비활성화할 수 있습니다 + 1. 환경 변수 `OPENAI_AGENTS_DISABLE_TRACING=1`을 설정하여 전역으로 트레이싱을 비활성화할 수 있습니다 + 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) 정책 하에서 운영하는 조직에서는 트레이싱을 사용할 수 없습니다.*** ## 트레이스와 스팬 -- **Traces**는 하나의 "워크플로"에 대한 단일 종단 간 작업을 나타냅니다. Traces는 Spans로 구성됩니다. Traces에는 다음 속성이 있습니다: - - `workflow_name`: 논리적 워크플로나 앱입니다. 예: "Code generation", "Customer service" +- **트레이스**는 "워크플로"의 단일 end-to-end 작업을 나타냅니다. 트레이스는 스팬으로 구성됩니다. 트레이스에는 다음 속성이 있습니다: + - `workflow_name`: 논리적 워크플로 또는 앱입니다. 예: "Code generation" 또는 "Customer service" - `trace_id`: 트레이스의 고유 ID입니다. 전달하지 않으면 자동 생성됩니다. 형식은 `trace_<32_alphanumeric>`이어야 합니다 - - `group_id`: 선택적 그룹 ID로, 동일한 대화의 여러 트레이스를 연결합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 + - `group_id`: 선택적 그룹 ID로, 같은 대화의 여러 트레이스를 연결하는 데 사용합니다. 예를 들어 채팅 스레드 ID를 사용할 수 있습니다 - `disabled`: True이면 트레이스가 기록되지 않습니다 - - `metadata`: 트레이스용 선택적 메타데이터입니다 -- **Spans**는 시작 시점과 종료 시점이 있는 작업을 나타냅니다. Spans에는 다음이 있습니다: + - `metadata`: 트레이스의 선택적 메타데이터입니다 +- **스팬**은 시작 시간과 종료 시간을 가진 작업을 나타냅니다. 스팬에는 다음이 있습니다: - `started_at` 및 `ended_at` 타임스탬프 - - `trace_id`: 해당 스팬이 속한 트레이스를 나타냅니다 - - `parent_id`: 이 스팬의 상위 스팬(있는 경우)을 가리킵니다 - - `span_data`: 스팬 관련 정보입니다. 예를 들어 `AgentSpanData`는 Agent 정보를, `GenerationSpanData`는 LLM 생성 정보를 포함합니다 + - `trace_id`: 소속된 트레이스를 나타냅니다 + - `parent_id`: 이 스팬의 상위 스팬을 가리킵니다(있는 경우) + - `span_data`: 스팬에 대한 정보입니다. 예를 들어 `AgentSpanData`는 Agent 정보를, `GenerationSpanData`는 LLM 생성 정보를 포함합니다 ## 기본 트레이싱 @@ -42,15 +42,15 @@ Agents SDK에는 내장 트레이싱이 포함되어 있으며, 에이전트 실 - 핸드오프는 `handoff_span()`으로 감싸집니다 - 오디오 입력(음성-텍스트)은 `transcription_span()`으로 감싸집니다 - 오디오 출력(텍스트-음성)은 `speech_span()`으로 감싸집니다 -- 관련 오디오 스팬은 `speech_group_span()` 하위로 중첩될 수 있습니다 +- 관련 오디오 스팬은 `speech_group_span()` 하위로 부모 지정될 수 있습니다 -기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용하면 이 이름을 설정할 수 있고, [`RunConfig`][agents.run.RunConfig]로 이름 및 기타 속성을 구성할 수도 있습니다. +기본적으로 트레이스 이름은 "Agent workflow"입니다. `trace`를 사용할 때 이 이름을 설정할 수 있으며, [`RunConfig`][agents.run.RunConfig]로 이름 및 기타 속성을 구성할 수도 있습니다. -또한 [사용자 정의 트레이스 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상). +또한 [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정해 트레이스를 다른 대상으로 전송할 수 있습니다(대체 또는 보조 대상). ## 상위 수준 트레이스 -경우에 따라 여러 `run()` 호출을 단일 트레이스의 일부로 만들고 싶을 수 있습니다. 이때 전체 코드를 `trace()`로 감싸면 됩니다. +경우에 따라 여러 번의 `run()` 호출을 하나의 트레이스에 포함하고 싶을 수 있습니다. 이 경우 전체 코드를 `trace()`로 감싸면 됩니다. ```python from agents import Agent, Runner, trace @@ -65,49 +65,49 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. 두 번의 `Runner.run` 호출이 `with trace()`로 감싸져 있으므로, 각각의 실행은 별도 트레이스 2개를 만드는 대신 전체 트레이스의 일부가 됩니다 +1. 두 번의 `Runner.run` 호출이 `with trace()`로 감싸져 있으므로, 개별 실행은 각각 두 개의 트레이스를 생성하는 대신 전체 트레이스의 일부가 됩니다 ## 트레이스 생성 [`trace()`][agents.tracing.trace] 함수를 사용해 트레이스를 생성할 수 있습니다. 트레이스는 시작과 종료가 필요합니다. 방법은 두 가지입니다: -1. **권장**: `with trace(...) as my_trace`처럼 컨텍스트 매니저로 사용합니다. 이렇게 하면 적절한 시점에 트레이스가 자동으로 시작/종료됩니다 +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)로 추적되는 가장 가까운 현재 스팬 아래에 중첩됩니다. +스팬은 자동으로 현재 트레이스의 일부가 되며, 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]를 구성하여 이 오디오 데이터 캡처를 비활성화할 수 있습니다. +마찬가지로 Audio 스팬은 기본적으로 입력 및 출력 오디오에 대한 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`으로 export하여 코드 변경 없이 기본값을 설정할 수 있습니다. -## 사용자 정의 트레이싱 프로세서 +## 사용자 지정 트레이싱 프로세서 트레이싱의 상위 수준 아키텍처는 다음과 같습니다: -- 초기화 시 트레이스를 생성하는 역할을 하는 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider]를 생성합니다 -- `TraceProvider`를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 구성하고, 이는 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 전송하며, 해당 Exporter는 스팬과 트레이스를 배치로 OpenAI 백엔드로 내보냅니다 +- 초기화 시 트레이스 생성을 담당하는 전역 [`TraceProvider`][agents.tracing.setup.TraceProvider]를 생성합니다 +- `TraceProvider`를 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 구성하며, 이 프로세서는 트레이스/스팬을 배치로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 전송합니다. `BackendSpanExporter`는 스팬과 트레이스를 배치로 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 백엔드로 전송되지 않습니다 -## 비 OpenAI 모델에서의 트레이싱 +## OpenAI가 아닌 모델에서의 트레이싱 -비 OpenAI 모델에서도 OpenAI API 키를 사용해 트레이싱 비활성화 없이 OpenAI Traces dashboard에서 무료 트레이싱을 활성화할 수 있습니다. +트레이싱을 비활성화할 필요 없이 OpenAI Traces 대시보드에서 무료 트레이싱을 활성화하기 위해 OpenAI API 키를 OpenAI가 아닌 모델과 함께 사용할 수 있습니다. ```python import os @@ -128,7 +128,7 @@ agent = Agent( ) ``` -단일 실행에 대해서만 다른 트레이싱 키가 필요하다면, 전역 exporter를 변경하는 대신 `RunConfig`를 통해 전달하세요. +단일 실행에만 다른 트레이싱 키가 필요하다면 전역 exporter를 변경하는 대신 `RunConfig`를 통해 전달하세요. ```python from agents import Runner, RunConfig @@ -141,7 +141,7 @@ await Runner.run( ``` ## 추가 참고 사항 -- Openai Traces dashboard에서 무료 트레이스를 확인하세요 +- Openai Traces 대시보드에서 무료 트레이스를 확인하세요 ## 에코시스템 통합 @@ -171,4 +171,5 @@ await Runner.run( - [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) - [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) \ No newline at end of file +- [Traccia](https://traccia.ai/docs/integrations/openai-agents) +- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) \ No newline at end of file diff --git a/docs/zh/tracing.md b/docs/zh/tracing.md index f9c05553c3..27dbe97cec 100644 --- a/docs/zh/tracing.md +++ b/docs/zh/tracing.md @@ -4,53 +4,53 @@ search: --- # 追踪 -Agents SDK 内置了追踪功能,可收集智能体运行期间事件的完整记录:LLM 生成、工具调用、任务转移、安全防护措施,甚至包括发生的自定义事件。通过使用[追踪仪表盘](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` 来为单次运行禁用追踪 + 3. 你可以通过将 [`agents.run.RunConfig.tracing_disabled`][] 设为 `True` 来禁用单次运行的追踪 -***对于在使用 OpenAI API 时采用零数据保留(ZDR)策略的组织,追踪功能不可用。*** +***对于在 OpenAI API 下使用零数据保留(ZDR)策略的组织,追踪不可用。*** -## 追踪与跨度 +## Trace 与 Span -- **追踪**表示“工作流”的一次端到端操作。它由多个跨度组成。追踪具有以下属性: - - `workflow_name`:逻辑工作流或应用。例如“代码生成”或“客户服务”。 - - `trace_id`:追踪的唯一 ID。如果你未传入则会自动生成。格式必须为 `trace_<32_alphanumeric>`。 - - `group_id`:可选分组 ID,用于关联同一会话中的多个追踪。例如,你可以使用聊天线程 ID。 - - `disabled`:若为 True,则不会记录该追踪。 - - `metadata`:追踪的可选元数据。 -- **跨度**表示具有开始和结束时间的操作。跨度具有: +- **Traces** 表示一个“工作流”的单次端到端操作。它们由 Spans 组成。Traces 具有以下属性: + - `workflow_name`:逻辑工作流或应用名称。例如“代码生成”或“客户服务”。 + - `trace_id`:Trace 的唯一 ID。如果你不传入会自动生成。格式必须为 `trace_<32_alphanumeric>`。 + - `group_id`:可选分组 ID,用于关联同一会话中的多个 Trace。例如,你可以使用聊天线程 ID。 + - `disabled`:若为 True,则不会记录该 Trace。 + - `metadata`:Trace 的可选元数据。 +- **Spans** 表示具有开始和结束时间的操作。Span 具有: - `started_at` 和 `ended_at` 时间戳。 - - `trace_id`,表示其所属追踪 - - `parent_id`,指向该跨度的父跨度(如有) - - `span_data`,即跨度信息。例如,`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()` 中 -- 相关音频跨度可能会作为 `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()` 中 +- 相关音频 Span 可能会作为子级归入 `speech_group_span()` 下 -默认情况下,追踪名称为“Agent workflow”。如果你使用 `trace`,可以设置此名称;你也可以通过 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。 +默认情况下,Trace 名称为“Agent workflow”。如果你使用 `trace`,可以设置此名称;也可以通过 [`RunConfig`][agents.run.RunConfig] 配置名称和其他属性。 -此外,你还可以设置[自定义追踪处理器](#custom-tracing-processors),将追踪推送到其他目标(作为替代目标或次要目标)。 +此外,你还可以设置[自定义追踪进程](#custom-tracing-processors),将 Trace 推送到其他目标(作为替代或辅助目标)。 -## 更高层级追踪 +## 更高层级的 Trace -有时,你可能希望多次调用 `run()` 都属于同一条追踪。你可以通过将整段代码包裹在 `trace()` 中来实现。 +有时,你可能希望多次对 `run()` 的调用都属于同一个 Trace。你可以通过将整段代码包裹在 `trace()` 中来实现。 ```python from agents import Agent, Runner, trace @@ -65,49 +65,49 @@ async def main(): print(f"Rating: {second_result.final_output}") ``` -1. 由于对 `Runner.run` 的两次调用都被包裹在 `with trace()` 中,因此这些单独运行会成为整体追踪的一部分,而不是创建两条追踪。 +1. 因为两次对 `Runner.run` 的调用都包裹在 `with trace()` 中,所以这些单独运行会属于同一个总体 Trace,而不是创建两个 Trace。 -## 创建追踪 +## 创建 Trace -你可以使用 [`trace()`][agents.tracing.trace] 函数创建追踪。追踪需要被启动和结束。你有两种方式: +你可以使用 [`trace()`][agents.tracing.trace] 函数来创建 Trace。Trace 需要开始和结束。你有两种方式: -1. **推荐**:将 trace 用作上下文管理器,即 `with trace(...) as my_trace`。这样会在正确时间自动启动并结束追踪。 +1. **推荐**:将 trace 用作上下文管理器,即 `with trace(...) as my_trace`。这会在正确的时间自动开始和结束 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` 来更新当前追踪。 +当前 Trace 通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。这意味着它可自动适配并发。如果你手动开始/结束 Trace,需要向 `start()`/`finish()` 传递 `mark_as_current` 和 `reset_current` 来更新当前 Trace。 -## 创建跨度 +## 创建 Span -你可以使用各种 [`*_span()`][agents.tracing.create] 方法创建跨度。通常你无需手动创建跨度。可使用 [`custom_span()`][agents.tracing.custom_span] 函数来追踪自定义跨度信息。 +你可以使用各种 [`*_span()`][agents.tracing.create] 方法来创建 Span。通常你不需要手动创建 Span。可使用 [`custom_span()`][agents.tracing.custom_span] 函数来跟踪自定义 Span 信息。 -跨度会自动归属于当前追踪,并嵌套在最近的当前跨度下;这通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 进行跟踪。 +Span 会自动归属于当前 Trace,并嵌套在最近的当前 Span 下;这同样通过 Python 的 [`contextvar`](https://docs.python.org/3/library/contextvars.html) 跟踪。 ## 敏感数据 -某些跨度可能会捕获潜在敏感数据。 +某些 Span 可能会捕获潜在的敏感数据。 -`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] 禁用该音频数据的捕获。 +类似地,默认情况下,音频 Span 会包含输入和输出音频的 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],后者会将跨度和追踪按批次导出到 OpenAI 后端。 +- 初始化时,我们会创建一个全局 [`TraceProvider`][agents.tracing.setup.TraceProvider],负责创建 Trace。 +- 我们使用 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 配置 `TraceProvider`,它会将 Trace/Span 批量发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter],后者会将 Span 和 Trace 批量导出到 OpenAI 后端。 -要自定义这套默认配置,以将追踪发送到替代或额外后端,或修改导出器行为,你有两个选项: +若要自定义此默认设置,将 Trace 发送到替代或附加后端,或修改导出器行为,你有两种选择: -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] 允许你添加一个**额外的**追踪进程,在 Trace 和 Span 就绪时接收它们。这使你可以在发送到 OpenAI 后端之外执行自己的处理。 +2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许你用自己的追踪进程**替换**默认进程。这意味着除非你包含一个会执行该发送的 `TracingProcessor`,否则 Trace 不会发送到 OpenAI 后端。 ## 使用非 OpenAI 模型进行追踪 -你可以将 OpenAI API 密钥与非 OpenAI 模型一起使用,以在 OpenAI 追踪仪表盘中启用免费追踪,而无需禁用追踪。 +你可以在非 OpenAI 模型中使用 OpenAI API key,在无需禁用追踪的情况下,于 OpenAI Traces 仪表板启用免费追踪。 ```python import os @@ -128,7 +128,7 @@ agent = Agent( ) ``` -如果你只需要为单次运行使用不同的追踪密钥,请通过 `RunConfig` 传入,而不是更改全局导出器。 +如果你只需为单次运行使用不同的追踪 key,请通过 `RunConfig` 传入,而不是更改全局导出器。 ```python from agents import Runner, RunConfig @@ -141,19 +141,19 @@ await Runner.run( ``` ## 附加说明 -- 在 Openai 追踪仪表盘查看免费追踪。 +- 在 Openai Traces 仪表板查看免费 Trace。 ## 生态系统集成 -以下社区和供应商集成支持 OpenAI Agents SDK 的追踪能力。 +以下社区和供应商集成支持 OpenAI Agents SDK 追踪接口。 -### 外部追踪处理器列表 +### 外部追踪进程列表 - [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents) - [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk) - [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents) -- [MLflow(自托管/开源)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) +- [MLflow(self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent) - [MLflow(Databricks 托管)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing) - [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk) - [Pydantic Logfire](https://logfire.pydantic.dev/docs/integrations/llms/openai/#openai-agents) @@ -171,4 +171,5 @@ await Runner.run( - [LangDB AI](https://docs.langdb.ai/getting-started/working-with-agent-frameworks/working-with-openai-agents-sdk) - [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) \ No newline at end of file +- [Traccia](https://traccia.ai/docs/integrations/openai-agents) +- [PromptLayer](https://docs.promptlayer.com/languages/integrations#openai-agents-sdk) \ No newline at end of file