> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Mastra platform の Trace Intelligence

Trace Intelligence は、Agent のインタラクション全体に繰り返し現れるパターンを見つけます。Mastra Observability が取得した Trace を分析し、4つの次元について Trace signal を生成して、類似する Trace signal を theme にクラスタリングします。

Trace Intelligence を使用すると、次のような疑問を調査できます。

- ユーザーは何を達成しようとしているのか？
- どの目標が成功しやすく、未解決のままになり、または阻害されるのか？
- 成功したインタラクションと失敗したインタラクションには、どのような Agent の振る舞いが見られるのか？
- ユーザーの感情は、目標や結果とどのように関係しているのか？

> **プライベートベータ:** Trace Intelligence は、選ばれた Mastra platform プロジェクトを対象に招待制で提供されています。

## アクセス権を取得する

1. [Trace Intelligence プライベートベータフォーム](https://mastra.ai/trace-intelligence)を送信して、アクセスを申請します。
2. [Mastra platform Observability](https://mastra.zisheng.pro/ja/docs/mastra-platform/observability) が有効で、完了した Agent の Trace が **Traces** に表示されていることを確認します。
3. `@mastra/core@1.53.0` 以上および `mastra@1.20.2` 以上が必要です。プロジェクトをアップグレードしてから、登録対象のプロジェクトに Studio をデプロイまたは再デプロイします。プライベートベータ期間中は、ローカル Studio と Server のみのデプロイはサポートされません。
4. デプロイ済みの Studio を開き、サイドバーで **Intelligence** を選択します。
5. Agent に代表的なトラフィックを送り、分析が完了するまで待ちます。

Mastra がプロジェクトを登録した後は、Agent の定義や呼び出しを変更する必要はありません。

### データが利用可能になるタイミング

Trace Intelligence が繰り返し現れるパターンを特定するには、1つの Agent について十分な数の処理済み Trace が必要です。通常、その Agent からの**完了済み Trace が100件以上**処理されると、最初の theme を利用できるようになります。

分析パイプラインは非同期で実行されるため、Trace Intelligence の準備が整う前に **Traces** の Trace 数が100に達することがあります。しきい値に達してから処理に数分かかる場合があります。分析できない Trace は件数に含まれないため、100は最小値であり、UI の厳密なトリガーではありません。

Trace Intelligence は、Trace が増えると自動的に更新されます。Studio が関係フローを表示するには、少なくとも2種類の Trace signal に theme が必要です。

代表的なトラフィックを使用してください。少数のテストプロンプトを繰り返すと、広範な theme が1つだけ生成されたり、大部分が Noise になったりするなど、代表性のない結果になることがあります。

## 分析を理解する

分析可能な完了済み Trace ごとに、4つの Trace signal が生成されます。

| Trace signal  | 意味                                               |
| ------------- | ------------------------------------------------ |
| **Goal**      | ユーザーが達成または完了しようとしていること。                          |
| **Outcome**   | 最終的な状態。完了、一部完了、阻害、失敗、未解決、不明のいずれかです。              |
| **Behavior**  | Tool の使用、省略、再試行、失敗、回復など、観測可能な Agent のアクションとパターン。 |
| **Sentiment** | ユーザーの感情的な状態や態度。                                  |

theme は、類似する Trace signal から生成されたクラスタです。クラスタリングは Trace signal の種類ごとに個別に行われます。1つの Trace が、Goal、Outcome、Behavior、Sentiment の各次元でそれぞれ別の theme に属することがあります。

### theme と関係

フローチャートは、隣接する Trace signal 列の theme を接続します。

- **node** は theme を表します。その件数は、選択した snapshot でその theme に割り当てられた個別 Trace の数です。
- **ribbon** は、隣接する両方の列で theme に割り当てられた Trace を接続します。その幅は共有される Trace 数を表します。
- node または ribbon にポインターを合わせるかフォーカスすると、その関係だけが表示されます。

フローが示すのは関連性であり、因果関係や実行順序ではありません。たとえば、Goal と Outcome の間にある ribbon は、同じ Trace 内で両方の theme が発生したことを意味します。Goal が Outcome を引き起こしたことを示すものではありません。

### 分布、Other、Noise

フローの下にあるカードには、各 Trace signal の theme 分布が表示されます。

- **Trace count**: 選択した snapshot で theme に割り当てられた個別 Trace の数。
- **Stage share**: その Trace signal について分析された Trace のうち、theme に割り当てられた割合。

Studio は、Trace signal の種類ごとに最も一般的な theme を表示します。チャートを過密にせず合計を維持するため、小さな theme を **Other** にまとめることがあります。

**Noise** には、選択した snapshot で繰り返し現れる theme に一貫して一致しなかった要約が含まれます。必ずしもエラーや低品質なインタラクションを示すものではありません。Noise には、まれなリクエストや新たに現れつつあるパターンが含まれることがあります。また、曖昧なインタラクションや無関係なケースが含まれる場合もあります。Noise の割合が大きい場合、トラフィックが非常に多様であるか、安定した theme を形成するためのデータが不足している可能性があります。

### snapshot

snapshot は、一連の Trace に対する移動分析ウィンドウです。snapshot は重なることがあるため、Trace 数を合計しないでください。ウィンドウ間でトラフィック量が変化する可能性があるため、Trace count と Stage share を併せて比較してください。

theme は snapshot 間で持続、消失、分割、統合、または再出現することがあります。theme の名前と説明は固定された分類体系ではなく、生成された要約として扱ってください。

## Trace Intelligence ページを使用する

1. **Agent** セレクターを使用して、分析を利用できる Agent を切り替えます。最初の theme の準備が整うまで、Agent は表示されません。
2. フローで theme を選択すると、すべての列がその theme を含む Trace に絞り込まれます。
3. **View theme details** を選択すると、説明、Trace count、Stage share、生成された例、履歴を確認できます。
4. **Clear filter** を選択すると、完全なフローに戻ります。

次の操作も行えます。

- 分布カードで theme を選択して、詳細と生成された例の要約を開きます。
- 分布カードで **Noise** を選択して、分布と生成された例の要約を確認します。
- 分布カードをドラッグして Trace signal 列を並べ替え、異なる視点から関係を確認します。
- タイムラインで snapshot を選択するか、**Play** を選択して theme の経時変化を確認します。
- theme の履歴を開いて、theme が持続したか、対象範囲がどのように変化したかを確認します。

Trace が2,000件を超える snapshot では、theme によるフローの絞り込みを利用できません。別の snapshot を選択するか、アクティブなフィルターを解除して完全なフローに戻ってください。theme と Noise の詳細は引き続き分布カードから確認できます。

## トラブルシューティング

### サイドバーに Intelligence が表示されない

Mastra が正しいプロジェクトを登録したこと、ベータ対応の Mastra バージョンを使用していること、Studio を再デプロイしたことを確認してください。プライベートベータはローカル Studio をサポートしていません。

### Agent が表示されない

完了済み Trace が **Traces** に表示されていることを確認してください。Agent が表示されるのは、最初の theme の準備が整ってからです。最近 Trace が100件に達した場合は、非同期処理が完了するまで待ってください。

### 関係フローを利用できない

フローには、少なくとも2種類の Trace signal の theme が必要です。代表的なトラフィックを引き続き送信し、処理が完了するまで待ってください。

### 要約の大部分が Noise になる

より多くの代表的なトラフィックを収集し、後の snapshot と比較してください。多様なインタラクションやまれなインタラクションはグループ化しにくい一方、テストプロンプトを繰り返すと代表性のない分布になることがあります。

## プライベートベータの制限

- Trace Intelligence は、デプロイ済み Studio に登録されたプロジェクトでのみ利用できます。
- 初回分析には、Agent ごとに少なくとも100件の処理済み Trace が必要です。Agent によっては、さらに多くの Trace が必要になる場合があります。
- 結果は、取得した Trace の多様性と品質に左右されます。
- Trace signal の要約、theme のラベル、クラスタリング、しきい値、UI の動作は、ベータ期間中に変更される可能性があります。

フィードバックを報告するときは、organization ID、project ID、agent ID、選択した snapshot、および問題を示す theme または Noise の例を含めてください。

## 関連項目

- [Mastra platform の Observability](https://mastra.zisheng.pro/ja/docs/mastra-platform/observability)
- [Mastra platform の Studio](https://mastra.zisheng.pro/ja/docs/mastra-platform/studio)