Tencent Engineering、DeepSeek ハーネス大規模運用の課題と調査手法を公開

腾讯云日志服务 2026-08-24 17:36 广东

全景 Agent 可观测方案

作者：trumphuang

一、導入

Agent はすでに多くのチームの日常開発プロセスに組み込まれています。規模が大きくなるにつれ、利用者の関心は単なる「結果が正しいか」だけでなく、以下の 3 点へと移っています。

• 処理時間の内訳：モデル推論に費やされた時間と、ツール実行に費やされた時間はどちらが多いのか
• トークン消費の傾向：どのセッションで、どのモデルに対してトークンが多く消費されているのか
• 失敗箇所の特定：どこでエラーが発生し、中断したのか。また、その過程を遡って追跡できるか

DeepSeek Harness（以下 DSH と表記）は、DeepSeek がオープンソース化した Agent フレームワークです。セッションの軌跡表示や、Session イベントの永続化、ツール呼び出しの検索機能を標準で備えています。ただし、DSH の可観測性は「ローカル環境」「単一セッション」「リアルタイム」に限定されています。

一方、「一連のタスク全体の性能を把握する」「一定期間のコスト分布を分析する」「数日前の失敗事例を再現する」といったニーズには、セッションやマシンを跨いだ構造化されたリンクデータが不可欠です。これらは長期的な保存と管理が必要です。

腾讯云 Agent 可観測性は、既存の OneSuite Agent 観測能力を基盤としつつ、DSH 専用の収集プラグインを提供します。このプラグインはネイティブ形式でマウントされ、実行プロセスを構造化された呼び出しチェーンとして復元します。タスクと推論ラウンド、モデル呼び出し、ツール呼び出し、セッション間の関連性を網羅し、リンク検索や集計分析、プラットフォーム固有のアラートダッシュボードなどの機能と連携することで、DSH 向けの包括的な Agent 可観測ソリューションを構築しています。

二、DeepSeek Harness の動作原理

DSH はオープンソース化されたコーディング用 Agent フレームワークで、コマンド名は dsh です。大規模言語モデル（LLM）が制御された環境下で、ファイルの読み書きやコマンド実行、外部サービスの呼び出しを行い、その結果に基づいて次のアクションを決定し、タスクを完遂させることを目的としています。

アーキテクチャ上、DSH は「Cordis マイクロカーネル」と「フルプラグイン化」を採用しています。カーネルはプロファイルに基づいたプラグインの組み立てとライフサイクル管理のみを担当します。モデルアダプター、ツールセット、サンドボックスポリシー、セッション永続化などはすべてプラグインとして実装されており、Web 版、TUI（テキストユーザーインターフェース）版、ヘッドレス版の 3 つの形態が同じカーネルを共有しています。可観測性機能もこの層にマウントされます。

実行モデルは ReAct ループです。1 つのユーザータスクを 1 つの「turn」と呼び、その turn 内でモデルが推論を行い、ツールを呼び出し、結果を観察する一連の動作を 1 つの「step」と定義します。ループ回数や使用するツールの選定は、実行時にモデルが動的に決定するため、実行前の段階で実行構造を事前に特定することはできません。

image 图 1 DSH の階層構造、1 つのターンにおける実行順序、そして外部へ出力される 2 つのデータ

2.1 DSH が備えている機能

上記のようなイベントフローとディスクへの記録データを踏まえると、DSH 自体には以下の 3 つの観測機能が標準で用意されています。

• セッション軌跡: ブラウザ内でラウンドごとに整理された実行履歴テーブルです。個々のレコードにおけるトークン使用量や所要時間を確認できます。
• Session イベントフローのディスク保存: 完全なイベントフローは zstd で圧縮された JSONL 形式で $DSH_HOME/sessions/ ディレクトリに保存されます。データは損なわれることなく記録されています。
• ツール呼び出しの検索: ツールの呼び出しパラメータと返却結果はイベントフロー内に記録されており、セッション全文での検索も可能です。

image 図 2 DSH が提供するセッション軌跡ビュー

2.2 なぜこのデータの上に呼び出し関係の分析が必要なのか

DSH のプロセスデータは、時間順に並べられたセッションイベントのシーケンスとして保存されています。しかし現時点では、個々の処理間の呼び出し関係や、それぞれの所要時間の統計情報は含まれていません。

実際の業務でデプロイ規模を拡大し、マシン台数が増加すると、以下の 3 つの問題が顕在化します。

これらの機能を実装するための共通の前提条件は、1 つのタスクを「親子関係」と「時間区間」を持つ呼び出しツリーとして再構築し、データをセッションやマシンを超えて集約・長期保存できるようにすることです。

三、腾讯云 Agent 可观测（Tencent Cloud Agent Observability）が提供する機能

既存の OneSuite Agent の能力をベースに、DSH 能力プラグイン層に DSH プラグインをマウントし、ランタイムのイベントバスとストリーミングパイプラインへ接続します。ここでは主に以下の 3 つのことに注力しています。

• サブスクリプション: ライフサイクルイベントを購読します。モデルのストリーミングパイプラインには中間層（ミドルウェア）を設け、データを改変することなく断片的に観測します。コードへの挿入（インストルメンテーション）や変更は行いません。
• モデリング: プラグイン内で状態ツリーを維持し、ばらばらのイベントを 5 レベルの呼び出しツリーとして再構築します。これを OpenTelemetry GenAI のセマンティック規約に準拠した Span としてマッピングします。

データはバッチで直接 Tencent Cloud の Agent 可観測性プラットフォームへ送信されます。Collector や常駐の収集プロセスを経由しません。

3.1 データ基盤：5 レベルの呼び出しツリー

プラグインからの報告される呼び出しチェーンは、DSH（DeepSeek Shell）の実行構造と一対一で対応する 5 つの階層に分かれています。1 つの turn は 1 つのタスクに対応し、turn の内部には複数の step が含まれます。各 step 内ではモデル呼び出しやツール呼び出しが行われます。

image 図 3：5 レベルの Span モデルと各層が担う情報

1 つの turn に 1 つの trace を割り当てます。多輪対話では、gen_ai.session.id を用いて横方向にリンクさせ、長期間のセッションで単一のチェーンが無限に膨張するのを防ぎます。

再試行はマージされません。実際のモデル呼び出しごとに独立した chat Span が生成され、dsh.llm.attempt で序号（試行回数）がマークされます。

中断も完全な記録として描画します。ストリームの未完了、step の終了がツールより先行するケース、ユーザーによる中断など、あらゆるエラー発生シーンで、エラーコード付きの Span が補完されて送信されます。

各層のプロパティはすべて OpenTelemetry GenAI のセマンティック規約に従っており、既存の可観測性システムとの整合性を保ちつつ、将来的に他の Agent フレームワークを導入する際にも統一された基準を維持できます。

図 4：全体技術アーキテクチャとデータフロー

Agent の実行構造はモデルがランタイム時に決定するため、階層の深さは固定されていません。しかし、チェーンデータには明確な親子関係と完全な時間範囲が必要です。このギャップを埋めるため、プラグインは状態ツリーと遅延送信（delayed emission）処理を組み合わせて、包括的な収集・報告機能を構築しています。

図 5：1 つの turn の完全な処理ロジック：イベントフロー → 状態ツリー → Span 送信 → バッチ報告

四、導入後に腾讯云 Agent 可観測性で確認できること

導入後、DSH のすべてのタスクは完全なチェーンとして記録され、セッション、モデル、ツールなどの各维度で集計されます。

完全な呼び出しチェーン——entry / agent / step / chat / tool の5層を段階的に展開し、親子関係と各層の消費時間比率が明確に可視化されます。

消費時間の分布——エンドツーエンドと1ラウンドごとの所要時間、モデル推論とツール実行それぞれの占める割合、そして最初のトークン到達までの遅延と P95 分位数を確認できます。

トークン数とコスト——入力と出力をそれぞれ集計し、単発のモデル呼び出しまで詳細を掘り下げたり、セッションやモデル単位で集約・ランキング表示したりすることが可能です。

呼び出しの詳細——モデル名、完了理由、リトライ回数、ツール名、消費時間、エラー状況などを統計的に把握できます。

失敗箇所の特定——各層の Span は独立したステータスを持ち、エラータイプのカスタマイズもサポートしています。これにより、モデル側の失敗、ツール側の失敗、ループ中断などを明確に区別して分析することが可能です。

検索とアラート——Traces（トレース）、Spans（スパン）、Sessions（セッション）の3つの視点から、Trace ID や Session ID、ステータスに基づいた検索が可能です。また、消費時間や失敗率に対してアラートを設定することもできます。

以下は一部の機能です。より多くの機能は、Agent 可観測性コンソールでお試しください。

図 6 可観測性パネル - トークン消費部分

図 7 呼び出しチェーンパネル - DeepSeek Harness タスクの完全な実行プロセス

五、導入実践

現在、tencentcloud-agentobs-sdk-dsh の正式版がリリースされ、DSH コミュニティのプラグインマーケットにも登録されています（対応バージョンは DSH >=0.1.0-rc.6 =22.19.0）。

前提条件

ログサービス CLS を有効化し、ログ書き込み権限を持つアクセス認証情報を準備してください。CAM サブアカウントまたは一時的なキーの使用を推奨します。

DSH がインストールされていること（バージョン >=0.1.0-rc.6 > .npmrc）

pnpm install

headless / harness プロファイルも同様に、パスを ~/.dsh/profiles/headless または ~/.dsh/profiles/harness に変更してください。

接続情報の設定

方法 1：環境変数（推奨）

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 CLS_SERVICE_NAME=dsh-agent # 可选，用于区分实例或业务

dsh --profile web

方式二：手动调整插件配置文件

编辑 $DSH_HOME/profiles//cordis.patch.yml，未设置 DSH_HOME 时默认为 ~/.dsh/profiles//cordis.patch.yml：

• id: cls-observability

config:

endpoint: ap-guangzhou.cls.tencentcs.com

topicId: your-topic-id

secretId: your-secret-id

secretKey: your-secret-key

serviceName: dsh-agent

captureContent: true

batchMaxSize: 32

flushIntervalMs: 5000

debug: false

显式插件配置优先于环境变量。以及访问凭证属于敏感信息，建议通过环境变量或密钥管理工具注入，不要将真实 SecretId 与 SecretKey 提交到代码仓库。

启动并验证

dsh --profile web

启动后发起一次测试任务，至少触发一次模型调用

卸载插件

dsh plugin --profile web remove tencentcloud-agentobs-sdk-dsh

dsh plugin --profile headless remove tencentcloud-agentobs-sdk-dsh

dsh plugin --profile harness remove tencentcloud-agentobs-sdk-dsh

コンテンツキャプチャの無効化

デフォルトでは、プロンプト、レスポンス、ツールの引数や結果がスパンに付与されます。これを無効にするには、以下のように設定してください。

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false

dsh --profile web

または、プラグイン設定で captureContent: false を指定します。

設定ファイルの全項目一覧

• 項目：デフォルト値 / 説明
• enabled：true / 収集を無効化してもプラグインはアンインストールされません
• endpoint：CLS_ENDPOINT / CLS API のエンドポイント
• topicId：CLS_TOPIC_ID / CLS ログトピック ID
• secretId：CLS_SECRET_ID / Tencent Cloud SecretId
• secretKey：CLS_SECRET_KEY / Tencent Cloud SecretKey
• serviceName：deepseek-harness / サービス名
• captureContent：true / プロンプト、レスポンス、ツールの内容をキャプチャします（false に設定すると無効化）
• contentMaxChars：128000 / 単一のコンテンツ属性で許可される最大文字数

batchMaxSize

32

毎バッチの最大 span 数

maxQueueSize

2048

キュー上限。これを超えると最も古い span が破棄される

flushIntervalMs

5000

定期フラッシュ間隔（ミリ秒）

retryTimes

3

アップロード時の再試行回数

debug

false

デバッグログを有効にする

六、腾讯云 Agent 可观测还提供哪些接入方式与能力

DSH プラグインは導入形態の一つに過ぎません。これに加えて、腾讯云 Agent 可観測では以下のデータ収集方法も提供しており、いずれも同一のデータモデルに書き込まれます。そのため、単一コンソール内でデータの閲覧や横断比較が可能です。

現在、導入エコシステムは着実に拡充されており、汎用 Agent フレームワーク（LangChain や OpenAI Agent SDK など）やコーディング用 Agent（CodeX や Claude Code など）への対応も順次追加されています。

データ収集後、コンソール側で利用可能な分析機能は以下の通りです。

アプリケーション一覧

導入済みおよび集計中のアプリケーション、前日の書き込み量と Token 総数、各アプリケーションのリージョン・ステータス・導入タイプを確認できます。

ダッシュボード

• 概要: リクエスト数とエラー数、モデル呼び出し回数、Input/Output の Token 数、Agent とモデルの Top10、平均 TTFT（Time To First Token）など。
• パフォーマンス: 応答時間のヒストグラム、P50/P90/P99 パーセンタイルの推移、モデルごとの平均応答時間 Top10 など。
• コスト & Token
• アプリケーション観測: generation、tool、chain、agent、retriever、guardrail、event などのタイプ別に呼び出し分布と応答時間を分析します。

呼び出しチェーン（Trace）

Traces と Span の 2 つのビューを提供。ステータスやエラータイプ（ツール呼び出し失敗、LLM 呼び出し失敗、Root span のステータスコード異常、Agent 実行失敗）でフィルタリングできます。また、Trace ID や Session ID、応答時間での絞り込みも可能です。詳細ページでは呼び出しツリー、各ノードの Input/Output データ、およびエラーの根本原因特定機能を提供します。

セッション

Session 単位で Trace を集約。会話期間、Trace 数、Token 数、コストでフィルタリングし、複数回にわたる対話の文脈を復元できます。

アラート機能

応答時間や失敗率など、主要な指標に対して異常を検知した際のアラートを設定可能です。

七、总结

DSH 原生のトラジェクトリビューとイベントストリームのディスク書き込みは、ローカル環境・単一セッション・リアルタイムでのデバッグ課題を解決するものです。本稿で提案する手法はこれらを基盤とし、同一のランタイムイベントを構造化された 5 レイヤーの呼び出しチェーンとして再構築します。これにより、セッション横断集約や複数マシンからのデータ集約、長期保存、アラート機能が補完され、DeepSeek Harness 向けの運用監視体制を迅速に構築できるようになります。

プロジェクト GitHub：

https://github.com/TencentCloud/tencentcloud-agentobs-sdk-dsh

関連する導入ガイド：

Agent 可観測アプリケーション詳細：

https://cloud.tencent.com/document/product/614/133517

AI Coding Agent データの接続（Onesuite-Pilot）：

Langfuse SDK を使用して Trace データを CLS へ送信する方法：

https://cloud.tencent.com/document/product/614/135910

Agent の可観測性に関するご質問やご提案は、以下のコミュニティグループまでお気軽にご参加ください。

WeChat で開くにはこちらへ