tencent cloud

Cloud Log Service

ドキュメントCloud Log ServiceAgent可観測性アクセスガイドAgentフレームワークと自社開発アプリケーションの接続OpenAI Agentデータの接続

OpenAI Agentデータの接続

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-10-12 15:13:58
AI翻訳

操作シナリオ

OpenAI Agent SDKは、Agentアプリケーションを構築するためのPythonフレームワークです。Agentは実行時に複数ラウンドのモデル推論、ツール呼び出し、サブAgent呼び出しを生成する可能性があります。Tencent Cloud Agent可観測SDK tencentcloud-agentobs-sdk-openai-agentをインストールすることで、OpenAI AgentsのTraceデータを自動的に収集し、CLS（Cloud Log Service）に報告できます。
接続が完了すると、Tencent Cloud Agent可観測性で以下の情報を確認できます：
1回のRunner.run()またはRunner.run_sync()の完全な呼び出しチェーン、およびAgent、推論ラウンド、モデル呼び出し、ツール呼び出し間の親子関係。
モデル呼び出しの入力Token、出力Token、初回Token遅延（TTFT）、終了理由、入力メッセージ、出力メッセージ。
ツール名、呼び出しパラメータ、戻り値、エラータイプ、エラー情報。
サブAgentのネスト関係、および各層Agentのモデル呼び出し回数、ツール呼び出し回数、Token使用量。
同一セッション内の複数ラウンドリクエストの関連関係。
本文では以下の2つの接続方法を提供します。実際の状況に応じて選択できます：
アクセス方法
説明
推奨シナリオ
Skillに対応したAIツールを使用し、AIがログトピックを作成または再利用し、SDKのインストール、設定、検証を完了します。
手動設定を減らし、接続後に自然言語でTraceデータを分析することを希望します。
SDKをインストールし、CLS Endpoint、ログトピック、アクセス認証情報を設定し、コード内でsetup()を呼び出します。
接続パラメータを細かく制御する必要がある場合、または使用するツールがSkillに対応していない場合です。

前提条件

接続する前に、以下の準備作業が完了していることを確認してください：
CLSを有効にしました。
CLS書き込み権限を持つアクセス証明書（CAMサブアカウント、CAM Role、一時キーなど）を準備しました。TencentCloud APIキー情報はAPIキー管理から取得してください。
接続に必要なリージョンアクセスポイント（endpoint）を取得しました：Agentアプリケーションが所在するリージョンのCLSアクセスポイントドメインです。詳細はリージョンとアクセスドメインをご参照ください。広州リージョンを例にすると、方式1ではRegion（例：ap-guangzhou）を記入します。方式2ではドメインを記入し、プライベートネットワークドメインはap-guangzhou.cls.tencentyun.com、パブリックネットワークドメインはap-guangzhou.cls.tencentcs.comです。

方法1：Skillによるクイック接続と分析

Skill対応のAIツールを使用している場合は、Tencent Cloud Agent可観測性アシスタントを使用してアクセスと分析を自動的に完了できます。このSkillはログトピックを作成または再利用し、OpenAI Agentプロジェクトを認識してSDKのインストール、構成、検証を完了できます。
AIツールに以下の内容を入力してください：
Tencent Cloud Agent可観測性アシスタントSkillを使用してください：
https://skillhub.cn/skills/tencentcloud-cls-agent-obs
現在のOpenAI AgentをTencent Cloud Agent可観測性に接続してください。
接続完了後、分析ニーズを直接記述することもできます。例えば：
このAgentの直近1時間の実行状況を分析し、最も時間がかかり、Token消費が最も多く、失敗が最も多いモデルまたはツール呼び出しを特定します。

方法2：手動設定による接続

SDK、ログトピック、アクセス証明書などのパラメータをきめ細かく制御する必要がある場合、または使用するツールがSkillをサポートしていない場合は、以下の手順に従って手動で接続を完了してください。

ステップ1：Agent可観測アプリケーションの作成

1. CLSコンソール > Agent可観測性ページに入ります。
2. アプリケーションアクセスをクリックし、ページの指示に従ってアプリケーションを作成します。
3. 新しく作成したアプリケーションの右側にある編集をクリックし、TraceログトピックIDをコピーします。このIDは後続の構成でCLS_TOPIC_IDに使用します。

ステップ2：SDKのインストール

OpenAI Agents SDKプロジェクトのPython仮想環境で以下のコマンドを実行します：
macOS / Linux
Windows（PowerShell）
pip install tencentcloud-agentobs-sdk-openai-agent
py -m pip install tencentcloud-agentobs-sdk-openai-agent

ステップ3：環境変数の設定

CLS Endpoint、ログトピックID、Tencent Cloudアクセスキー、OpenAI API Keyを設定します。以下の例では広州リージョンの内部ネットワークを例にします：
macOS / Linux
Windows（PowerShell）
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=your-topic-id
export CLS_SECRET_ID=your-secret-id
export CLS_SECRET_KEY=your-secret-key
export OPENAI_API_KEY=sk-xxx
$env:CLS_ENDPOINT = "ap-guangzhou.cls.tencentcs.com"
$env:CLS_TOPIC_ID = "your-topic-id"
$env:CLS_SECRET_ID = "your-secret-id"
$env:CLS_SECRET_KEY = "your-secret-key"
$env:OPENAI_API_KEY = "sk-xxx"
環境変数
必須/任意
説明
CLS_ENDPOINT
はい
CLSリージョンのEndpointです。EndpointとTraceログトピックは同一リージョンに配置する必要があります。リージョンとアクセスドメイン名を参照してください。広州リージョンを例にすると、プライベートドメイン名はap-guangzhou.cls.tencentyun.com、パブリックドメイン名はap-guangzhou.cls.tencentcs.comです。
CLS_TOPIC_ID
はい
Agent可観測アプリケーションに対応するTraceログトピックIDです。アプリケーションIDを入力しないでください。
CLS_SECRET_ID
はい
Tencent CloudアクセスキーIDです。アクセスキーには対象ログトピックへの書き込み権限が必要です。
CLS_SECRET_KEY
はい
Tencent CloudアクセスキーKey。
OPENAI_API_KEY
はい
OpenAIモデルサービスのAPIキーです。
説明：
アクセス証明書は機密情報に属します。環境変数を通じて注入し、最小権限とローテーション可能な一時証明書を使用することをお勧めします。

ステップ4：収集の初期化

初回のRunner.run()またはRunner.run_sync()呼び出し前にsetup()を実行します。既存のAgentコードを変更する必要はありません。
import os

from tencentcloud_agentobs_sdk_openai_agent import CLSConfig, setup

setup(
    CLSConfig(
        endpoint=os.environ["CLS_ENDPOINT"],
        topic_id=os.environ["CLS_TOPIC_ID"],
        secret_id=os.environ["CLS_SECRET_ID"],
        secret_key=os.environ["CLS_SECRET_KEY"],
    )
)

# 以下は既存のOpenAI Agents SDKコードです。
from agents import Agent, Runner

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    model="gpt-4o",
)

result = Runner.run_sync(agent, "北京の天気はどうですか？")
print(result.final_output)
環境変数でCLSパラメータを設定済みの場合は、直接実行できます：
from tencentcloud_agentobs_sdk_openai_agent import setup

setup()
注意：
setup()は、初めてAgentを実行する前に呼び出す必要があります。アプリケーションの起動エントリで一度呼び出し、プロセッサの重複登録と重複Traceの生成を回避することをお勧めします。

ステップ5：Agentの実行と結果の検証

1. モデル呼び出しを含むAgentタスクを一度実行します。完全な呼び出しツリーを確認するために、同時にツール呼び出しをトリガーすることをお勧めします。
2. CLSコンソール > Agent可観測性ページに入ります。
3. 手順1で作成したアプリケーションに入ります。
4. 呼び出しチェーンページを開き、テストリクエストを含む時間範囲を選択します。
5. 最新のTraceを開き、Agent、Step、Chat、Tool、またはEmbeddingなどのSpanが含まれているかどうかを確認します。
6. 特定のSpanを選択し、その所要時間、ステータス、入出力、Token使用量、モデルリクエストパラメータなどのデータを確認します。

よくあるご質問

CLSにTraceデータがない

以下の順序で確認してください：
1. 初回のRunner.run()またはRunner.run_sync()呼び出し前にsetup()を実行済みであることを確認してください。
2. CLS_ENDPOINTがTraceログトピックと同じリージョンに存在することを確認してください。
3. CLS_TOPIC_IDがAgent可観測性アプリケーションIDではなく、ログトピックIDであることを確認してください。
4. アクセスキーが対象ログトピックへの書き込み権限を持っていることを確認してください。
5. 実行環境が設定されたCLS Endpointにアクセスできることを確認してください。
6. テストタスクの完了後、少なくとも1回の更新サイクルを待ってからデータを照会してください。
7. ローカルディスク保存を有効にした後、JSONLファイルにSpanが生成されているかどうかを確認し、収集問題と報告問題を区別してください。

Traceにメッセージまたはツールコンテンツがない

コンテンツ収集ポリシーがoffに設定されているかどうか、および環境変数OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTがメッセージコンテンツ収集を無効にしているかどうかを確認してください。コンテンツ収集を無効にしても、呼び出しツリー、Token、所要時間、ステータスなどのデータの報告には影響しません。

同一実行でのTrace重複

アプリケーションがsetup()を重複して呼び出していないか、または複数の収集コンポーネントを通じて同じデータを同じログトピックに送信していないかを確認してください。対照検証の場合を除き、同一プロセスでは本SDKを一度だけ初期化することをお勧めします。

サブAgentが呼び出しツリーに表示されない

サブAgentがOpenAI Agents SDKの標準的な呼び出し方法で実行されていることを確認し、サブAgentがRunnerに対応するTraceのライフサイクル内で実行されているかどうかを確認してください。SDKはspan.parent_idに基づいて親子関係を復元します。

Agentの実行はレポート異常の影響を受けるか

SDKの観測リンクはAgentビジネスを中断しません。設定が欠落している場合や初期化が異常な場合、SDKは診断情報を縮退出力します。ネットワークやサーバー側が異常な場合、SDKはバッファリングして再送信します。
前の記事へ: Onesuite-Pilot バージョン情報次の記事へ: AgentScopeデータの接続

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック

キーワードで検索
    Enter keywords to search documentation