操作シナリオ
AgentScope Agentは、タスク実行時に複数ラウンドの推論、モデル呼び出し、ツール呼び出し、Embedding呼び出しなどの実行データを生成します。Tencent Cloud AgentScope Agent可観測SDK tencentcloud-agentobs-sdk-agentscopeをインストールすることで、1行のinit()初期化コードで自動的に計装を完了し、TraceデータをCLS（Cloud Log Service）に報告できます。
接続が完了すると、Tencent Cloud Agent可観測性で以下の情報を確認できます：
Agent、推論ステップ、モデル、ツール、およびEmbedding呼び出しの間の完全な実行関係。
各ステップの実行時間、モデル初回トークン遅延（TTFT）、Token使用量、終了理由。
モデルリクエストパラメータ、入出力メッセージ、ツール定義、ツールパラメータ、ツール結果。
ツール呼び出し失敗後の再試行プロセス、および権限制御、コンテキスト圧縮、手動介入などの重要なライフサイクルイベント。
同一Session、Turn、StepにおけるTraceの関連関係。
本文では以下の2つの接続方法を提供します。実際の状況に応じて選択できます：
|
| Skillに対応したAIツールを使用し、AIがログトピックを作成または再利用し、SDKのインストール、設定、検証を完了します。 | 手動設定を減らし、接続後に自然言語でTraceデータを分析することを希望します。 |
| SDKをインストールし、CLS Endpoint、ログトピック、アクセス認証情報を設定し、コード内でinit()を呼び出します。 | 接続パラメータを細かく制御する必要がある場合、または使用するツールがSkillに対応していない場合です。 |
前提条件
接続を開始する前に、以下の準備作業が完了していることを確認してください：
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です。 AgentScopeをインストール済みであり、アプリケーションが正常に動作することを確認しています。
Python 3.10以降をインストール済みであり、アプリケーション用に独立したPython仮想環境を作成しています。
方法1：Skillによるクイック接続と分析
Skill対応のAIツールを使用している場合は、Tencent Cloud Agent可観測性アシスタントを使用してアクセスと分析を自動的に完了できます。このSkillはログトピックを作成または再利用し、AgentScopeプロジェクトを認識してSDKのインストール、構成、検証を完了できます。 AIツールに以下の内容を入力してください：
Tencent Cloud Agent可観測性アシスタントSkillを使用してください：
https://skillhub.cn/skills/tencentcloud-cls-agent-obs
現在のAgentScopeベースで開発されたAgentをTencent Cloud Agent可観測性に接続してください。
接続完了後、分析ニーズを直接記述することもできます。例えば：
このAgentの直近1時間の実行状況を分析し、最も時間がかかり、Token消費が最も多く、失敗が最も多いモデルまたはツール呼び出しを特定します。
方法2：手動設定による接続
SDK、ログトピック、アクセス証明書などのパラメータをきめ細かく制御する必要がある場合、または使用するツールがSkillをサポートしていない場合は、以下の手順に従って手動で接続を完了してください。
ステップ1：Agent可観測アプリケーションの作成
2. アプリケーションアクセスをクリックし、ページの指示に従ってアプリケーションを作成します。
3. 新しく作成したアプリケーションの右側にある編集をクリックし、TraceログトピックIDをコピーします。このIDは後続の構成でCLS_TOPIC_IDに使用します。
ステップ2：SDKのインストール
AgentScopeアプリケーションが存在するPython仮想環境に入り、以下のコマンドを実行します：
pip install tencentcloud-agentobs-sdk-agentscope
py -m pip install tencentcloud-agentobs-sdk-agentscope
ステップ3：ローカルでのインストルメンテーション検証
Agentを作成する前にSDKをインポートして初期化します：
from tencentcloud_agentobs_sdk_agentscope import init
init()
agent = Agent(
name="assistant",
system_prompt="...",
model=model,
toolkit=toolkit,
)
reply = await agent.reply(
UserMsg(name="user", content="北京の天気はどうですか？"),
)
CLSアクセス証明書が設定されていない場合、SDKはSpanを標準出力に出力し、Agentの実行を中断しません。一度Agentリクエストを実行して、標準出力にAgent、Step、Chat、またはToolなどのSpanが表示されることを確認してください。
説明：
init()はAgentScopeのバージョンを自動的に検出し、初期化後に作成されたAgentに対して計装を行います。
AgentScope v1およびv2は、同じinit()接続方式を使用します。
Agent、モデル、ツールを作成する前にinit()を呼び出してください。そうしないと、作成済みのオブジェクトが自動的に計装されない可能性があります。
ステップ4：CLS接続情報の設定
CLS Endpoint、TraceログトピックID、およびTencent Cloudアクセス証明書を設定します：
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=<TraceログトピックID>
export CLS_SECRET_ID=<SecretId>
export CLS_SECRET_KEY=<SecretKey>
$env:CLS_ENDPOINT = "ap-guangzhou.cls.tencentcs.com"
$env:CLS_TOPIC_ID = "<TraceログトピックID>"
$env:CLS_SECRET_ID = "<SecretId>"
$env:CLS_SECRET_KEY = "<SecretKey>"
|
CLS_ENDPOINT
| はい | CLS APIアクセスポイントです。詳細については、リージョンとアクセスドメインをご参照ください。広州を例にすると、プライベートドメインはap-guangzhou.cls.tencentyun.com、パブリックドメインはap-guangzhou.cls.tencentcs.comです。 |
CLS_TOPIC_ID
| はい | |
CLS_SECRET_ID
| はい | Tencent Cloudアクセス認証情報SecretIdです。APIキー管理にアクセスして取得してください。 |
CLS_SECRET_KEY
| はい | Tencent Cloudアクセス認証情報SecretKeyです。APIキー管理にアクセスして取得してください。 |
説明：
アクセス証明書は機密情報に属します。環境変数を通じて注入し、最小権限とローテーション可能な一時証明書を使用することをお勧めします。
ステップ5：CLS接続性の検証
以下のコマンドを実行して、設定を確認し、テストSpanを送信してください：
python -m tencentcloud_agentobs_sdk_agentscope.cls_config verify
py -m tencentcloud_agentobs_sdk_agentscope.cls_config verify
コマンドは順に設定を確認し、CLS SDKを初期化し、テストSpanを構築してデータを送信します。広州を例にとると、以下の結果が表示された場合、検証に成功したことを示します：
設定チェックに合格しました。
CLS SDKの初期化に成功しました。
テストSpanが構築されました。
送信に成功しました。
検証に成功しました。Spanはap-guangzhou.cls.tencentcs.comに報告されました。
ステップ6：Agentの実行と結果の検証
元の方法でAgentScopeアプリケーションを起動し、モデルまたはツール呼び出しを含むテストリクエストを1回発行します。リクエスト完了後、1回の更新サイクルを待ってから、以下の手順で検証します：
2. ステップ1で作成したアプリケーションに入ります。 3. 呼び出しチェーンページを開き、テストリクエストを含む時間範囲を選択します。
4. 最新のTraceを開き、Agent、Step、Chat、Tool、またはEmbeddingなどのSpanが含まれているかどうかを確認します。
5. 特定のSpanを選択し、その所要時間、ステータス、入出力、Token使用量、モデルリクエストパラメータなどのデータを確認します。
よくあるご質問
ローカルでSpanが出力されない
以下の順序で確認してください：
1. tencentcloud-agentobs-sdk-agentscopeがインストールされていることを確認します。
2. init()がエージェント作成前に実行されていることを確認します。
3. テストリクエストが実際にAgent、モデル、またはツール呼び出しをトリガーしたことを確認します。
4. アプリケーションがSDKでサポートされているAgentScopeバージョンを使用していることを確認します。
接続性検証の失敗
以下の順序で確認してください：
1. CLS_ENDPOINTにプロトコルプレフィックスまたはパスが含まれていないことを確認します。
2. CLS_ENDPOINTがTraceログトピックと同じリージョンに存在することを確認してください。
3. CLS_TOPIC_IDがトピック名やアプリケーションIDではなく、ログトピックIDであることを確認してください。
4. CLS_SECRET_IDおよびCLS_SECRET_KEYが有効であることを確認してください。
5. アクセスキーが対象ログトピックにデータを書き込む権限を持っていることを確認してください。
6. 現在の環境が設定されたCLS Endpointにアクセスできることを確認してください。
トレース内のTokenまたは一部のモデル属性の欠落
Tokenおよびモデル属性はモデルクライアントの戻り値に由来します。モデルサービスが対応するフィールドを返さない場合、Agent可観測性は正確な値を推定できません。まず、使用しているモデルクライアントがUsage、レスポンスID、終了理由、TTFTなどの情報を提供しているかどうかを確認してください。
トレース内の入出力またはツールパラメータの欠落
アプリケーションまたはSDKがコンテンツ収集を無効にしているかどうかを確認してください。コンテンツ収集を無効にしても、呼び出しツリー、所要時間、ステータス、Token使用量の報告には影響しません。
同一リクエストにおけるトレースの重複
アプリケーションでTencent Cloud AgentScope SDK、AgentScope公式Tracing、またはその他のOpenTelemetry自動インストルメンテーションが同時に有効になっており、データが同じログトピックに送信されているかどうかを確認してください。対照検証の場合を除き、同じAgentインスタンスでは1つのTrace報告経路のみを保持することを推奨します。
SDKの異常がAgentの動作に影響するかどうか
いいえ。SDKは観測コンポーネントがビジネスをブロックしない設計原則に従い、設定が欠落している場合やSDKに異常が発生した場合は縮退し、アラートと修復ガイドを出力します。