github-featured/openai--openai-agents-python
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: update translated pages

Browse Source
This commit is contained in:
Kazuhiro Sera
2026-07-28 08:10:53 +09:00
parent 88bfb18c2f
commit 421deb7506
4 changed files with 149 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ja/tracing.md
+47 -47
View File
@@ -4,51 +4,51 @@ search:
---
# トレーシング
Agents SDK には組み込みのトレーシング機能があり、エージェント実行中のイベント（LLM 生成、ツール呼び出し、ハンドオフ、ガードレール、さらには発生したカスタムイベントまで）を包括的に記録します。[トレースダッシュボード](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 回の実行に対するトレーシングを無効化できます
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）ポリシーの下で運用している組織では、トレーシングを利用できません。***
## トレースとスパン
- **トレース**は、「ワークフロー」における単一のエンドツーエンド操作を表します。トレースはスパンで構成され、次のプロパティがあります。
- `workflow_name`: 論理的なワークフローまたはアプリです。たとえば「コード生成」や「カスタマーサービス」です。
- `workflow_name`: 論理的なワークフローまたはアプリです。たとえば、「コード生成」や「カスタマーサービス」です。
- `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 は次の項目をトレースします。
- `Runner.{run, run_sync, run_streamed}()` 全体が `trace()` でラップされます。
- 各 Runner 呼び出しが `task_span()` でラップされます。
- 各ランナー呼び出しが `task_span()` でラップされます。
- 各モデルターンが `turn_span()` でラップされます。
- エージェントが実行されるたびに、`agent_span()` でラップされます
- LLM 生成が `generation_span()` でラップされます
- 各関数ツール呼び出しが `function_span()` でラップされます
- ガードレールが `guardrail_span()` でラップされます
- ハンドオフが `handoff_span()` でラップされます
- 音声入力（音声テキスト変換）が `transcription_span()` でラップされます
- 音声出力（テキスト音声変換）が `speech_span()` でラップされます
- 関連する音声スパンは、`speech_group_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] を使用して名前やその他のプロパティを設定することもできます。
よりコンパクトな階層にするには、実行時のタスクスパンとターンスパンの自動生成を無効にします。エージェント、生成、関数、ガードレール、ハンドオフ、カスタムの各スパンは引き続き記録されます。
よりコンパクトな階層にする場合は、その実行についてタスクスパンとターンスパンの自動作成を無効にします。エージェント、生成、関数、ガードレール、ハンドオフ、カスタムの各スパンは引き続き記録されます。
```python
from agents import RunConfig, Runner
@@ -60,11 +60,11 @@ result = await Runner.run(
)
```
さらに、[カスタムトレースプロセッサー](#custom-tracing-processors)を設定して、トレースを別の送信先に送ることもできます（既定の送信先の代替、または追加の送信先として）。
さらに、[カスタムトレーシングプロセッサー](#custom-tracing-processors)を設定して、トレースを別の送信先に送信できます（置き換え先または追加の送信先として使用できます）。
## 長時間実行ワーカーと即時エクスポート
デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、数秒ごと、またはメモリ内キューがサイズのトリガー値に達した時点で、それより早くバックグラウンドでトレースをエクスポートします。また、プロセス終了時には最後のフラッシュも実行します。Celery、RQ、Dramatiq、FastAPI のバックグラウンドタスクなどの長時間実行ワーカーでは、通常、追加のコードなしでトレースが自動的にエクスポートされますが、各ジョブの完了直後にはトレースダッシュボードに表示されない場合があります。
デフォルトの [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] は、数秒ごと、またはメモリ内キューがサイズのしきい値に達した場合はそれより早く、バックグラウンドでトレースをエクスポートします。また、プロセス終了時には最後のフラッシュを実行します。Celery、RQ、Dramatiq、FastAPI のバックグラウンドタスクなどの長時間実行ワーカーでは、通常、追加のコードなしでトレースが自動的にエクスポートされますが、各ジョブの完了直後には Traces ダッシュボードに表示されない場合があります。
作業単位の終了時に即時配信を保証する必要がある場合は、トレースコンテキストの終了後に [`flush_traces()`][agents.tracing.flush_traces] を呼び出します。
@@ -103,7 +103,7 @@ async def run(prompt: str, background_tasks: BackgroundTasks):
return {"status": "queued"}
```
[`flush_traces()`][agents.tracing.flush_traces] は、現在バッファリングされているトレースとスパンのエクスポートが完了するまでブロックします。そのため、構築途中のトレースをフラッシュしないよう、`trace()` が閉じた後に呼び出してください。デフォルトのエクスポート遅延で問題ない場合は、この呼び出しを省略できます。
[`flush_traces()`][agents.tracing.flush_traces] は、現在バッファリングされているトレースとスパンのエクスポートが完了するまでブロックします。そのため、構築途中のトレースをフラッシュしないように、`trace()` が閉じた後に呼び出してください。デフォルトのエクスポート遅延で問題がない場合は、この呼び出しを省略できます。
## 上位レベルのトレース
@@ -122,30 +122,30 @@ async def main():
print(f"Rating: {second_result.final_output}")
```
1. `Runner.run` の 2 回の呼び出しが `with trace()` でラップされているため、個々の実行で 2 つのトレースが作成されるのではなく、全体のトレースの一部になります。
1. 2 回の `Runner.run` 呼び出しが `with trace()` でラップされているため、個別の実行によって 2 つのトレースが作成されるのではなく、全体のトレースに含まれます。
## トレースの作成
[`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` に設定することで、コードを変更せずにデフォルト値を設定できます。
@@ -153,18 +153,18 @@ async def main():
トレーシングの上位レベルのアーキテクチャは次のとおりです。
- 初期化時に、トレースの作成を担うグローバルな [`TraceProvider`][agents.tracing.setup.TraceProvider] を作成します。
- `TraceProvider` に [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] を設定します。これは、トレースとスパンをバッチ単位で [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter] に送信し、`BackendSpanExporter` がスパンとトレースをバッチ単位で OpenAI バックエンドにエクスポートします。
- 初期化時に、トレースの作成を担うグローバルな [`TraceProvider`][agents.tracing.provider.TraceProvider] を作成します。
- [`TraceProvider`][agents.tracing.provider.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] を使用すると、デフォルトのプロセッサーを独自のトレースプロセッサーで**置き換える**ことができます。この場合、OpenAI バックエンドへ送信する `TracingProcessor` を含めない限り、トレースは OpenAI バックエンドに送信されません。
## OpenAI 以外のモデルでのトレーシング
OpenAI API キーを OpenAI 以外のモデルで使用すると、トレーシングを無効化することなく、OpenAI のトレースダッシュボードで無料のトレーシングを有効にできます。アダプターの選択とセットアップ時の注意事項については、モデルガイドの[サードパーティ製アダプター](models/index.md#third-party-adapters)セクションを参照してください。
OpenAI 以外のモデルでも OpenAI API キーを使用すれば、トレーシングを無効にすることなく、OpenAI Traces ダッシュボードで無料のトレーシングを有効にできます。アダプターの選択と設定に関する注意事項については、モデルガイドの[サードパーティ製アダプター](models/index.md#third-party-adapters)セクションを参照してください。
```python
import os
@@ -185,7 +185,7 @@ agent = Agent(
)
```
1 回の実行にのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに、`RunConfig` を介して渡してください。
単一の実行にのみ別のトレーシングキーが必要な場合は、グローバルエクスポーターを変更する代わりに、`RunConfig` を介して渡してください。
```python
from agents import Runner, RunConfig
@@ -197,21 +197,21 @@ await Runner.run(
)
```
## 補足事項
- OpenAI のトレースダッシュボードで無料のトレースを確認できます。
## 追加情報
- OpenAI Traces ダッシュボードで無料のトレースを確認できます。
## エコシステム統合
以下のコミュニティおよびベンダー統合は、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 (self-hosted/OSS)](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
- [MLflow (Databricks hosted)](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
- [Future AGI](https://docs.futureagi.com/docs/tracing/auto/openai_agents/)
- [MLflow（セルフホスト／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)
- [AgentOps](https://docs.agentops.ai/v1/integrations/agentssdk)
@@ -229,9 +229,9 @@ 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)
- [PromptLayer](https://docs.promptlayer.com/features/integrations#openai-agents-sdk)
- [HoneyHive](https://docs.honeyhive.ai/v2/integrations/openai-agents)
- [Asqav](https://www.asqav.com/docs/integrations#openai-agents)
- [Datadog](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation/?tab=python#openai-agents)
- [Latitude](https://docs.latitude.so/telemetry/frameworks/openai-agents)
- [DProvenanceKit](https://dprovenance.dev/openai-agents/)
- [DProvenanceKit](https://dprovenance.dev/openai-agents/)
docs/ko/tracing.md
+42 -42
View File
@@ -4,30 +4,30 @@ search:
---
# 트레이싱
Agents SDK에는 에이전트 실행 중 발생하는 LLM 생성, 도구 호출, 핸드오프, 가드레일, 사용자 지정 이벤트까지 포괄적으로 기록하는 트레이싱 기능이 기본 제공됩니다. [트레이스 대시보드](https://platform.openai.com/traces)를 사용하면 개발 및 프로덕션 환경에서 워크플로를 디버깅하고 시각화하며 모니터링할 수 있습니다.
Agents SDK에는 에이전트 실행 중 발생하는 LLM 생성, 도구 호출, 핸드오프, 가드레일, 사용자 지정 이벤트까지 포괄적으로 기록하는 트레이싱 기능이 내장되어 있습니다. [트레이스 대시보드](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) 정책에 따라 운영되는 조직에서는 트레이싱을 사용할 수 없습니다.***
## 트레이스와 스팬
- **트레이스**는 하나의 "워크플로"에서 수행되는 단일 엔드투엔드 작업을 나타냅니다. 트레이스는 여러 스팬으로 구성되며 다음 속성을 갖습니다.
- `workflow_name`: 논리적 워크플로나 앱입니다. 예를 들어 "코드 생성" 또는 "고객 서비스"입니다.
- `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`(있는 경우)
- 소속된 트레이스를 나타내는 `trace_id`
- 이 스팬의 상위 스팬을 가리키는 `parent_id`(있는 경우)
- 스팬에 관한 정보인 `span_data`. 예를 들어 `AgentSpanData`에는 에이전트에 관한 정보가 포함되고, `GenerationSpanData`에는 LLM 생성에 관한 정보가 포함됩니다.
## 기본 트레이싱
@@ -42,13 +42,13 @@ SDK는 기본적으로 다음 항목을 트레이싱합니다.
- 각 함수 도구 호출은 `function_span()`으로 래핑됩니다
- 가드레일은 `guardrail_span()`으로 래핑됩니다
- 핸드오프는 `handoff_span()`으로 래핑됩니다
- 오디오 입력(음성-텍스트 변환)은 `transcription_span()`으로 래핑됩니다
- 오디오 출력(텍스트-음성 변환)은 `speech_span()`으로 래핑됩니다
- 오디오 입력(음성 텍스트 변환)은 `transcription_span()`으로 래핑됩니다
- 오디오 출력(텍스트 음성 변환)은 `speech_span()`으로 래핑됩니다
- 관련 오디오 스팬은 `speech_group_span()` 아래에 배치될 수 있습니다
기본적으로 트레이스의 이름은 "Agent workflow"입니다. `trace`를 사용하는 경우 이 이름을 설정할 수 있으며, [`RunConfig`][agents.run.RunConfig]를 사용하여 이름과 기타 속성을 구성할 수도 있습니다.
더 간결한 계층 구조를 원한다면 실행에 대한 자동 태스크 및 턴 스팬을 비활성화합니다. 에이전트, 생성, 함수, 가드레일, 핸드오프 및 사용자 지정 스팬은 계속 기록됩니다.
더 간결한 계층 구조가 필요하다면 실행 시 자동 태스크 및 턴 스팬을 비활성화하세요. 에이전트, 생성, 함수, 가드레일, 핸드오프 및 사용자 지정 스팬은 계속 기록됩니다.
```python
from agents import RunConfig, Runner
@@ -60,13 +60,13 @@ result = await Runner.run(
)
```
또한 [사용자 지정 트레이스 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 대상으로 보낼 수 있습니다. 기존 대상을 대체하거나 보조 대상으로 추가할 수 있습니다.
또한 [사용자 지정 트레이싱 프로세서](#custom-tracing-processors)를 설정하여 트레이스를 다른 대상으로 보낼 수 있습니다. 이 대상은 기존 대상을 대체하거나 보조 대상으로 사용할 수 있습니다.
## 장기 실행 워커와 즉시 내보내기
기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 몇 초마다 백그라운드에서 트레이스를 내보내며, 메모리 내 큐가 크기 트리거에 도달하면 더 일찍 내보냅니다. 또한 프로세스가 종료될 때 최종 플러시를 수행합니다. Celery, RQ, Dramatiq 또는 FastAPI 백그라운드 태스크와 같은 장기 실행 워커에서는 일반적으로 추가 코드 없이 트레이스가 자동으로 내보내지지만, 각 작업이 완료된 직후 트레이스 대시보드에 표시되지 않을 수 있습니다.
기본 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]는 몇 초마다 백그라운드에서 트레이스를 내보내며, 인메모리 큐가 크기 임계값에 도달하면 더 일찍 내보냅니다. 또한 프로세스가 종료될 때 최종 플러시를 수행합니다. Celery, RQ, Dramatiq 또는 FastAPI 백그라운드 태스크와 같은 장기 실행 워커에서는 별도의 코드 없이도 일반적으로 트레이스가 자동으로 내보내집니다. 다만 각 작업이 완료된 직후 트레이스 대시보드에 나타나지 않을 수 있습니다.
작업 단위가 끝날 때 즉시 전달되도록 보장해야 한다면 트레이스 컨텍스트가 종료된 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출합니다.
작업 단위가 끝날 때 즉시 전달되도록 보장해야 한다면 트레이스 컨텍스트가 종료된 후 [`flush_traces()`][agents.tracing.flush_traces]를 호출하세요.
```python
from agents import Runner, flush_traces, trace
@@ -103,11 +103,11 @@ async def run(prompt: str, background_tasks: BackgroundTasks):
return {"status": "queued"}
```
[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬을 모두 내보낼 때까지 실행을 차단하므로, 일부만 생성된 트레이스가 플러시되지 않도록 `trace()`가 종료된 후 호출합니다. 기본 내보내기 지연 시간이 허용 가능한 경우에는 이 호출을 생략할 수 있습니다.
[`flush_traces()`][agents.tracing.flush_traces]는 현재 버퍼링된 트레이스와 스팬을 모두 내보낼 때까지 차단하므로, 일부만 구성된 트레이스가 플러시되지 않도록 `trace()`가 종료된 후 호출하세요. 기본 내보내기 지연 시간이 허용 가능한 경우에는 이 호출을 생략할 수 있습니다.
## 상위 수준 트레이스
여러 `run()` 호출을 하나의 트레이스에 포함하려는 경우가 있습니다. 전체 코드를 `trace()`로 래핑하면 됩니다.
여러 `run()` 호출을 하나의 트레이스에 포함해야 할 때가 있습니다. 전체 코드를 `trace()`로 래핑하면 됩니다.
```python
from agents import Agent, Runner, trace
@@ -122,49 +122,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] 함수를 사용하여 트레이스를 생성할 수 있습니다. 트레이스는 시작하고 종료해야 합니다. 다음 두 가지 방법을 사용할 수 있습니다.
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`를 전달해야 합니다.
## 스팬 생성
여러 [`*_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]를 생성합니다.
- [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 트레이스와 스팬을 배치로 전송하는 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]로 `TraceProvider`를 구성합니다. `BackendSpanExporter`는 스팬과 트레이스를 OpenAI 백엔드로 배치 단위로 내보냅니다.
- 초기화 시 트레이스 생성을 담당하는 전역 [`TraceProvider`][agents.tracing.provider.TraceProvider]를 생성합니다.
- 트레이스와 스팬을 배치 단위로 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]에 전송하는 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]를 사용하여 `TraceProvider`를 구성합니다. `BackendSpanExporter`는 스팬과 트레이스를 배치 단위로 OpenAI 백엔드에 내보냅니다.
트레이스를 대체 또는 추가 백엔드로 전송하거나 내보내기 동작을 변경하는 등 기본 설정을 사용자 지정하려면 다음 두 가지 방법을 사용할 수 있습니다.
트레이스를 대체 또는 추가 백엔드로 전송하거나 익스포터 동작을 변경하는 등 이 기본 설정을 사용자 지정하려면 다음 두 가지 방법을 사용할 수 있습니다.
1. [`add_trace_processor()`][agents.tracing.add_trace_processor]를 사용하면 준비되는 트레이스와 스팬을 수신하는 **추가** 트레이스 프로세서를 추가할 수 있습니다. 따라서 OpenAI 백엔드로 트레이스를 전송하는 동시에 자체 처리를 수행할 수 있습니다.
2. [`set_trace_processors()`][agents.tracing.set_trace_processors]를 사용하면 기본 프로세서를 자체 트레이스 프로세서로 **교체**할 수 있습니다. 이 경우 OpenAI 백엔드로 전송하는 `TracingProcessor`를 포함하지 않으면 트레이스가 OpenAI 백엔드로 전송되지 않습니다.
1. [`add_trace_processor()`][agents.tracing.add_trace_processor]를 사용하면 준비된 트레이스와 스팬을 수신할 **추가** 트레이싱 프로세서를 등록할 수 있습니다. 이를 통해 트레이스를 OpenAI 백엔드에 전송하는 것과 별도로 자체 처리를 수행할 수 있습니다.
2. [`set_trace_processors()`][agents.tracing.set_trace_processors]를 사용하면 기본 프로세서를 자체 트레이싱 프로세서로 **교체**할 수 있습니다. 이 경우 OpenAI 백엔드로 전송하는 `TracingProcessor`를 포함하지 않으면 트레이스가 OpenAI 백엔드로 전송되지 않습니다.
## OpenAI 이외 모델을 사용한 트레이싱
## 비 OpenAI 모델을 사용한 트레이싱
OpenAI 이외 모델에 OpenAI API 키를 사용하면 트레이싱을 비활성화하지 않고도 OpenAI 트레이스 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. 어댑터 선택 및 설정 시 주의 사항은 모델 가이드의 [서드파티 어댑터](models/index.md#third-party-adapters) 섹션을 참고하세요.
비 OpenAI 모델과 함께 OpenAI API 키를 사용하면 트레이싱을 비활성화하지 않고도 OpenAI 트레이스 대시보드에서 무료 트레이싱을 활성화할 수 있습니다. 어댑터 선택 및 설정 시 유의 사항은 모델 가이드의 [서드 파티 어댑터](models/index.md#third-party-adapters) 섹션을 참고하세요.
```python
import os
@@ -185,7 +185,7 @@ agent = Agent(
)
```
단일 실행에만 다른 트레이싱 키가 필요한 경우 전역 내보내기를 변경하는 대신 `RunConfig`를 통해 전달합니다.
단일 실행에만 다른 트레이싱 키가 필요한 경우 전역 익스포터를 변경하지 말고 `RunConfig`를 통해 전달하세요.
```python
from agents import Runner, RunConfig
@@ -201,15 +201,15 @@ await Runner.run(
- OpenAI 트레이스 대시보드에서 무료 트레이스를 확인할 수 있습니다.
## 에코시스템 통합
## 생태계 통합
다음 커뮤니티 및 공급업체 통합은 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)
- [Future AGI](https://docs.futureagi.com/docs/tracing/auto/openai_agents/)
- [MLflow (자체 호스팅/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)
@@ -229,9 +229,9 @@ 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)
- [PromptLayer](https://docs.promptlayer.com/features/integrations#openai-agents-sdk)
- [HoneyHive](https://docs.honeyhive.ai/v2/integrations/openai-agents)
- [Asqav](https://www.asqav.com/docs/integrations#openai-agents)
- [Datadog](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation/?tab=python#openai-agents)
- [Latitude](https://docs.latitude.so/telemetry/frameworks/openai-agents)
- [DProvenanceKit](https://dprovenance.dev/openai-agents/)
- [DProvenanceKit](https://dprovenance.dev/openai-agents/)
docs/ref/decorators.md
+3
View File
@@ -0,0 +1,3 @@
# `Decorators`
::: agents.decorators
docs/zh/tracing.md
+57 -57
View File
@@ -4,51 +4,51 @@ search:
---
# 追踪
Agents SDK 内置追踪功能，可收集智能体运行期间发生的各类事件的完整记录：LLM生成、工具调用、任务转移、安全防护措施，甚至包括发生的自定义事件。借助[追踪控制面板](https://platform.openai.com/traces)，你可以在开发和生产环境中调试、可视化和监控工作流。
Agents SDK内置追踪功能，可在智能体运行期间收集完整的事件记录，包括LLM生成、工具调用、任务转移、安全防护措施，乃至发生的自定义事件。使用[追踪记录仪表板](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`，针对单次运行禁用追踪
1. 设置环境变量`OPENAI_AGENTS_DISABLE_TRACING=1`，在全局禁用追踪
2. 在代码中使用[`set_tracing_disabled(True)`][agents.set_tracing_disabled]，在全局禁用追踪
3. 将[`agents.run.RunConfig.tracing_disabled`][]设置为`True`，针对单次运行禁用追踪
***对于使用OpenAI API 且采用零数据保留（ZDR）政策的组织，追踪功能不可用。***
***对于使用OpenAI API并遵循零数据保留（ZDR）政策的组织，追踪功能不可用。***
## 追踪与跨度
- **追踪**表示一次端到端的“工作流”操作。它们由多个跨度组成。追踪具有以下属性：
- **追踪**表示一次“工作流”的端到端操作。追踪由多个跨度组成，并具有以下属性：
- `workflow_name`：逻辑工作流或应用。例如“代码生成”或“客户服务”。
- `trace_id`：追踪的唯一 ID。如果未传入，则会自动生成。格式必须为 `trace_<32_alphanumeric>`。
- `group_id`：可选的组 ID，用于关联同一对话中的多个追踪。例如，你可以使用聊天线程 ID。
- `trace_id`：追踪的唯一 ID。如果未传入，则会自动生成。格式必须为`trace_<32_alphanumeric>`。
- `group_id`：可选的组 ID，用于关联同一对话中的多个追踪。例如，可以使用聊天线程 ID。
- `disabled`：如果为 True，则不会记录该追踪。
- `metadata`：追踪的可选元数据。
- **跨度**表示具有开始和结束时间的操作。跨度具有以下属性：
- `started_at` 和 `ended_at` 时间戳。
- `trace_id`，表示它们所属的追踪
- `parent_id`，指向该跨度的父跨度（如果存在）
- `span_data`，即有关该跨度的信息。例如，`AgentSpanData` 包含有关智能体的信息，`GenerationSpanData` 包含有关 LLM生成的信息，依此类推。
- `started_at`和`ended_at`时间戳。
- `trace_id`，表示其所属的追踪
- `parent_id`，指向此跨度的父跨度（如果有）
- `span_data`，即有关跨度的信息。例如，`AgentSpanData`包含有关智能体的信息，`GenerationSpanData`包含有关LLM生成的信息，依此类推。
## 默认追踪
默认情况下，SDK 会追踪以下内容：
- 整个 `Runner.{run, run_sync, run_streamed}()` 都封装在 `trace()` 中。
- 每次运行器调用都封装在 `task_span()` 中。
- 每个模型轮次都封装在 `turn_span()` 中。
- 每次智能体运行都封装在 `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()`中。
- 每次运行器调用都会封装在`task_span()`中。
- 每个模型轮次都会封装在`turn_span()`中。
- 每次智能体运行都会封装在`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]配置名称及其他属性。
如果你希望层次结构更紧凑，可以针对某次运行禁用自动任务跨度和轮次跨度。智能体、生成、函数、安全防护措施、任务转移和自定义跨度仍会被记录。
如果希望使用更紧凑的层级结构，可以针对某次运行禁用自动创建的任务跨度和轮次跨度。智能体、生成、函数、安全防护措施、任务转移和自定义跨度仍会被记录。
```python
from agents import RunConfig, Runner
@@ -60,13 +60,13 @@ result = await Runner.run(
)
```
此外，你还可以设置[自定义追踪进程](#custom-tracing-processors)，将追踪发送到其他目标（作为替代目标或次要目标）。
此外，你还可以设置[自定义追踪进程](#custom-tracing-processors)，将追踪推送到其他目标位置，以替代原目标位置或作为辅助目标位置。
## 长时间运行的工作进程与即时导出
默认的 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 每隔几秒在后台导出一次追踪，或者在内存队列达到其大小触发阈值时提前导出，并且还会在进程退出时执行最后一次刷新。对于 Celery、RQ、Dramatiq 或 FastAPI 后台任务等长时间运行的工作进程，这意味着通常无需任何额外代码即可自动导出追踪，但它们可能不会在每个作业完成后立即显示在追踪控制面板中。
默认的[`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]每隔几秒在后台导出追踪；当内存队列达到其大小触发阈值时，会提前导出；进程退出时，还会执行最后一次刷新。对于 Celery、RQ、Dramatiq 或 FastAPI 后台任务等长时间运行的工作进程，这意味着通常无需任何额外代码即可自动导出追踪，但每项作业完成后，它们可能不会立即显示在追踪记录仪表板中。
如果需要保证在一个工作单元结束时立即交付，请在追踪上下文退出后调用 [`flush_traces()`][agents.tracing.flush_traces]。
如果需要确保在一个工作单元结束时立即交付，请在追踪上下文退出后调用[`flush_traces()`][agents.tracing.flush_traces]。
```python
from agents import Runner, flush_traces, trace
@@ -103,11 +103,11 @@ async def run(prompt: str, background_tasks: BackgroundTasks):
return {"status": "queued"}
```
[`flush_traces()`][agents.tracing.flush_traces] 会阻塞，直到当前缓冲的追踪和跨度全部导出，因此应在 `trace()` 关闭后调用，以避免刷新尚未完整构建的追踪。如果可以接受默认的导出延迟，则可以跳过此调用。
[`flush_traces()`][agents.tracing.flush_traces]会阻塞，直到当前已缓冲的追踪和跨度全部导出。因此，请在`trace()`关闭后调用它，以避免刷新尚未构建完成的追踪。如果默认导出延迟可以接受，则可以跳过此调用。
## 高层级追踪
有时，你可能希望多次调用 `run()` 时将其纳入同一个追踪。为此，可以将整个代码封装在 `trace()` 中。
有时，你可能希望多次调用`run()`都属于同一个追踪。为此，可以将整个代码封装在`trace()`中。
```python
from agents import Agent, Runner, trace
@@ -122,49 +122,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]。
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) 进行跟踪。这意味着它会自动支持并发。如果手动启动或结束追踪，则需要将 `mark_as_current` 和 `reset_current` 传递给 `start()`/`finish()`，以更新当前追踪。
当前追踪通过 Python 的[`contextvar`](https://docs.python.org/3/library/contextvars.html)进行跟踪，这意味着它可以自动适配并发场景。如果手动启动或结束追踪，则需要将`mark_as_current`和`reset_current`传递给`start()`/`finish()`，以更新当前追踪。
## 跨度创建
## 跨度的创建
你可以使用各种 [`*_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]，负责创建追踪。
- 我们使用 [`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor] 配置 `TraceProvider`，由它将追踪和跨度分批发送到 [`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]，后者再将跨度和追踪分批导出到OpenAI后端。
- 初始化时，会创建全局[`TraceProvider`][agents.tracing.provider.TraceProvider]，负责创建追踪。
- 我们会为`TraceProvider`配置一个[`BatchTraceProcessor`][agents.tracing.processors.BatchTraceProcessor]，由它将追踪/跨度分批发送到[`BackendSpanExporter`][agents.tracing.processors.BackendSpanExporter]；后者会将跨度和追踪分批导出到OpenAI后端。
若要自定义此默认设置，将追踪发送到其他或额外的后端，或修改导出器行为，你有以下两种选择：
若要自定义此默认设置，将追踪发送到其他或更多后端，或修改导出器行为，有以下两种方式：
1. [`add_trace_processor()`][agents.tracing.add_trace_processor] 允许添加一个**额外的**追踪进程，它会在追踪和跨度就绪时接收它们。这样，除了将追踪发送到OpenAI后端之外，你还可以执行自己的处理。
2. [`set_trace_processors()`][agents.tracing.set_trace_processors] 允许使用你自己的追踪进程**替换**默认进程。这意味着，除非你加入能够将追踪发送到OpenAI后端的 `TracingProcessor`，否则追踪不会发送到OpenAI后端。
1. [`add_trace_processor()`][agents.tracing.add_trace_processor]允许添加一个**额外的**追踪进程，它会在追踪和跨度准备就绪时接收它们。这样，除了将追踪发送到OpenAI后端之外，还可以执行自己的处理。
2. [`set_trace_processors()`][agents.tracing.set_trace_processors]允许使用自己的追踪进程**替换**默认进程。这意味着，除非包含一个负责发送到OpenAI后端的`TracingProcessor`，否则追踪不会发送到OpenAI后端。
## 非OpenAI模型追踪
## 非OpenAI模型的追踪
你可以对非OpenAI模型使用 OpenAI API 密钥，从而在 OpenAI追踪控制面板中启用免费追踪，而无需禁用追踪。有关适配器选择和设置注意事项，请参阅模型指南中的[第三方适配器](models/index.md#third-party-adapters)部分。
可以将OpenAI API 密钥与非OpenAI模型配合使用，从而在OpenAI追踪记录仪表板中启用免费追踪，而无需禁用追踪。有关适配器选择和设置注意事项，请参阅模型指南中的[第三方适配器](models/index.md#third-party-adapters)部分。
```python
import os
@@ -185,7 +185,7 @@ agent = Agent(
)
```
如果只需要为单次运行使用其他追踪密钥，请通过 `RunConfig` 传入，而不要更改全局导出器。
如果仅需为单次运行使用不同的追踪密钥，请通过`RunConfig`传入，而不要更改全局导出器。
```python
from agents import Runner, RunConfig
@@ -198,18 +198,18 @@ await Runner.run(
```
## 补充说明
- 可在 OpenAI追踪控制面板中查看免费追踪。
- 可在OpenAI追踪记录仪表板中查看免费的追踪记录。
## 生态系统集成
以下社区和供应商集成支持 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)
- [Future AGI](https://docs.futureagi.com/docs/tracing/auto/openai_agents/)
- [MLflow（自托管/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)
@@ -229,9 +229,9 @@ 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)
- [PromptLayer](https://docs.promptlayer.com/features/integrations#openai-agents-sdk)
- [HoneyHive](https://docs.honeyhive.ai/v2/integrations/openai-agents)
- [Asqav](https://www.asqav.com/docs/integrations#openai-agents)
- [Datadog](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation/?tab=python#openai-agents)
- [Latitude](https://docs.latitude.so/telemetry/frameworks/openai-agents)
- [DProvenanceKit](https://dprovenance.dev/openai-agents/)
- [DProvenanceKit](https://dprovenance.dev/openai-agents/)