「収益上位10件の顧客を見つけて、再エンゲージメント用のセグメントを作成して」とStudioに依頼すると、AIは単に回答するだけでなく、計画を立てます。リクエストをステップに分解し、各ステップに適切なツールを選択し、順番に実行して、結果を一貫したレスポンスにまとめます。このオーケストレーションを理解することで、より効果的なコラボレーターになれます。
AIが実行するすべてのアクションはチャットストリームで確認できます。ツール呼び出しは展開可能なカードとして表示され、実行されたコマンド、クエリ、またはAPIリクエストの詳細が確認できます。バックグラウンドで何かが行われることはありません。結果に基づいて行動する前に、AIが行ったすべての判断を確認できます。
Studioがリクエストを処理する内部ロジック（タスクの分解、ツールの選択、マルチターン実行、コンテキスト管理）を理解することで、より良いプロンプトを作成し、AIの動作を予測し、期待通りに動作しない場合のトラブルシューティングができるようになります。
- Treasure AI Studioにサインイン済み（はじめに）
- チャットインターフェースへの習熟（AI Chat Interface）
- 推奨：ご自身のドメインに対応したアクティブなスキル（Skills & Marketplace）
AIは検索エンジンではなく、計画を立て、行動し、適応するエージェントです。AIの思考プロセスを理解することで、以下のことが可能になります。
- より良いプロンプトを作成する — 具体的なリクエストはより効率的な実行計画を生み出します
- ツール選択を予測する — どのようなツールが存在するかを理解することで、AIを適切なアプローチへ誘導できます
- 予期しない結果をデバッグする — 出力が正しくない場合、ツール呼び出しを遡ってロジックがどこで分岐したかを特定できます
送信するすべてのメッセージは、同じオーケストレーションパイプラインに従います。舞台裏で何が起きているかを説明します。
AIがメッセージを読む前に、Studioは作業コンテキストを組み立てます。
| コンテキストレイヤー | 含まれる内容 | ソース |
|---|---|---|
| システムプロンプト | コアの動作ルール、利用可能なツール、実行環境 | プラットフォーム（組み込み） |
| プロジェクトコンテキスト | プロジェクトの指示、デフォルトデータベース、カスタムルール | プロジェクト設定 |
| アクティブなスキル | ドメイン固有のプレイブック（SQLパターン、セグメントスキーマなど） | スキルの選択内容 |
| 会話履歴 | このセッションでの過去のメッセージ、ツールの結果、AIのレスポンス | 現在のチャット |
| セッション内メモリ | 会話中にAIが記録した重要な情報 | AIが管理（In-Session Memoryを参照） |
この階層化されたコンテキストにより、AIはお客様の環境を「把握」できます。「上位顧客をクエリして」というリクエストが機能するのは、プロジェクトコンテキストにデフォルトデータベースが含まれており、アクティブなTrinoスキルがAIにtd_interval()の使用方法を教えているためです。
コンテキストはセッション開始時に組み立てられ、会話の進行に合わせて更新されます。スキルはセッション開始時にロックされます。会話の途中でスキルの選択を変更するには、新しいチャットを開始する必要があります。プロジェクトコンテキストと会話履歴はリアルタイムで更新されます。
AIは上記のすべてのコンテキストを踏まえてメッセージを読み、計画に分解します。これは思考フェーズ（レスポンスが始まる前に表示される「Thinking...」インジケーター）の間に行われます。
シンプルなリクエスト（単一ステップ）：
"pageviewsテーブルの行数は？"
→ 計画: 1つのクエリを実行（SELECT COUNT(*) FROM pageviews）複雑なリクエスト（マルチステップ）：
"収益上位10件の顧客を見つけて、セグメントを作成し、
再エンゲージメント用のメールキャンペーンを作成して"
→ 計画:
1. 顧客の収益データをクエリ（Trino SQL）
2. 結果を分析してセグメント基準を定義
3. 基準を含むセグメントYAMLを生成
4. セグメント定義を検証
5. メールキャンペーンのコンテンツを生成
6. キャンペーンをプレビューAIが計画を明示的に宣言するとは限りませんが、チャットストリームのツール呼び出しの順序を通じて展開を確認できます。
複雑なタスクの場合は、リクエストを「まず計画を立て、その後実行してください：」で始めましょう。これにより、AIはアクションを実行する前に実行計画を表示するようになり、ツールが呼び出される前に調整する機会が得られます。
計画の各ステップに対して、AIは以下の要素に基づいて利用可能なツールから選択します。
| 要素 | 選択への影響 |
|---|---|
| タスクの種類 | クエリタスク → tdx queryを使用したBash、ファイル生成 → 書き込みツール、データ探索 → tdx describe |
| アクティブなスキル | スキルはAIにツール固有のパターンを教えます。Trinoスキルは汎用SQLではなくtdx query -e trinoの使用を促します |
| 過去の結果 | ステップNの出力がステップN+1のツール選択に影響します。クエリが失敗した場合、オプティマイザースキルが起動することがあります |
| ユーザーの指示 | 明示的な指示（「これにはHiveを使って」）はAIのデフォルトの選択を上書きします |
| カテゴリ | ツール | 機能 |
|---|---|---|
| クエリ実行 | Bash経由のtdx query | Treasure AIデータベースに対してTrino/Hive SQLを実行 |
| データ探索 | tdx databases、tdx tables、tdx describe | データベースの参照、テーブルの一覧表示、スキーマの確認 |
| ファイル操作 | Read、Write、Edit、Glob、Grep | 作業ディレクトリ内のファイルの読み書き |
| CDP操作 | tdx ps、tdx sg、tdx journey | 親セグメント、子セグメント、ジャーニーの管理 |
| ファイル表示 | open_file | 生成されたファイル（HTMLチャート、ドキュメント、画像）をファイルビューアーに表示 |
| ワークフロー管理 | tdx wfコマンド | Treasure ワークフローの作成、監視、デバッグ |
| 外部Integration | MCPサーバーツール（接続時） | Google Calendarのクエリ、Gleanの検索、HubSpotの連絡先管理 |
ツールが選択されると、AIはそれを実行し、結果をリアルタイムでストリーミングします。
- ツール呼び出しカードが表示される — ツール名、実行内容の説明、ローディングインジケーターが表示されます
- 実行が行われる — コマンド、クエリ、またはAPIコールがサーバーサイドで実行されます
- 結果が返される — ツール呼び出しカードが結果（またはエラー）で更新されます
- AIが結果を処理する — AIは結果を読み取り、次のステップを決定します
- サイクルが繰り返される — タスクが完了するまで、各計画ステップに対してステップ1〜4が繰り返されます
ツール呼び出しカードを展開すると、実行されたクエリ、返されたAPIレスポンス、または書き込まれたファイルなど、正確な入力と出力を確認できます。
すべてのステップが完了すると、AIは結果を一貫したレスポンスにまとめます。
- テキストサマリー — 主要な発見、推奨事項、または説明
- 生成されたファイル — ファイルパネルにレンダリングされたチャート、テーブル、またはダッシュボード
- ファイル出力 — プレビューおよびダウンロード可能な生成済みPPTX、DOCX、XLSX、またはPDFファイル
- 次のステップの提案 — AIは結果に基づいてフォローアップアクションを提案することがあります
複雑な分析作業は、1つのメッセージに収まることはほとんどありません。オーケストレーターは、各メッセージが前の結果の上に積み重なる反復的なマルチターンワークフロー向けに設計されています。
AIは会話の完全なコンテキストを維持します。これには以下が含まれます。
- 実行したすべてのクエリとその結果
- 生成または変更したすべてのファイル
- お客様の修正や改善（「いいえ、米国リージョンのみでフィルタリングして」）
- ツール呼び出しの結果（エラーや再試行を含む）
これにより、「今度はリージョン別に分解して」と言うだけで、AIはどのクエリ結果を参照しているか、どのデータベースをクエリするか、どのスキルパターンを適用するかを把握できます。
会話を閉じて再度開いた場合：
- Web — ツール呼び出し履歴とコンテキストを含む完全なセッション状態がサーバーから復元されます
- Desktop — セッションは保存されたトランスクリプトから再開され、ツールを再実行することなく完全な会話状態が復元されます
Studioは会話をテキストとして再生するのではなく、セッションレベルの状態再開を使用します。これにより、ツールの結果や推論チェーンを含むAIの完全な内部コンテキストが保持されるため、再開した会話は継続的な会話と同じように動作します。
会話が長くなると、最終的にAIのコンテキストウィンドウの上限に近づきます。Studioはこれを自動的に管理します。
| メカニズム | 機能 |
|---|---|
| 自動コンパクト | コンテキストがいっぱいになると、AIは最近のコンテキストと重要な情報を保持しながら古いメッセージを要約します |
/compactコマンド | コンテキストスペースを解放するために手動でコンパクションを実行します |
/contextコマンド | 現在使用中のコンテキスト量を確認します |
/clearコマンド | 会話をクリアして、クリーンなコンテキストで新たに開始します |
長い分析セッションでは、新しい分析スレッドを開始する前に/compactを積極的に使用しましょう。これにより、以前の作業からの重要な発見を保持しながら、新しいツール呼び出しと結果のためのスペースを確保できます。
一般的なオーケストレーションパターンを理解することで、AIの動作を予測しやすくなります。
データ分析で最も一般的なパターン：
ユーザー: 過去90日間の1日あたりのサインアップ数のトレンドを表示して
AI: 1. [ツール: tdx query] td_interval(-90d)を使用してTrino SQLを実行
2. [思考] 結果セットを分析 — トレンド、スパイク、異常を特定
3. [ツール: open_file] 生成されたHTMLチャートをファイルビューアーで開く
4. [テキスト] 発見を要約：「サインアップは23%の上昇トレンドを示しています...」CDPの設定タスクで一般的なパターン：
ユーザー: 過去30日間に購入したユーザーのセグメントを作成して
AI: 1. [ツール: tdx ps desc] 利用可能な属性の親セグメントスキーマを確認
2. [ツール: tdx query] データの可用性と行数を確認するためにクエリを実行
3. [思考] 正しいセグメントルールの演算子とフィールド名を決定
4. [ツール: Write] セグメントYAML定義を生成
5. [ツール: tdx sg validate] CDP API仕様に対してYAMLを検証
6. [テキスト] プッシュコマンドとともに検証済みセグメントを提示ワークフローやクエリのトラブルシューティングで一般的なパターン：
ユーザー: ワークフローdaily_etlが昨夜失敗した原因は？
AI: 1. [ツール: tdx wf sessions] 最近のワークフローセッションを一覧表示
2. [ツール: tdx wf attempt logs] 昨夜の実行の失敗ログを読み取る
3. [思考] 根本原因を特定（例：テーブルが見つからない、タイムアウト）
4. [テキスト] 失敗の原因を説明し、修正案を提案
5. [ツール: Write] エラーハンドリングを含む更新された.digファイルを生成成果物の作成で一般的なパターン：
ユーザー: Q1データから四半期ビジネスレビューのデッキを作成して
AI: 1. [ツール: tdx query] 収益、ユーザー数、エンゲージメントに関する複数のクエリを実行
2. [ツール: open_file] 各メトリクスの生成されたHTMLチャートを開く
3. [ツール: Write] 各セクションのスライドを含むPPTXを作成
4. [テキスト] レビュー用にデッキを提示
ユーザー: Q1とQ4を比較するスライドを追加して、収益チャートを積み上げ棒グラフにして
AI: 5. [ツール: tdx query] 比較クエリを実行
6. [ツール: Write] 新しいスライドとチャートタイプでPPTXを更新
7. [テキスト] 更新されたデッキを提示| プラクティス | 効果的な理由 |
|---|---|
| データソースを具体的に指定する | 「marketing.campaignsテーブルをクエリして」は「キャンペーンデータを見て」よりも速く処理されます。AIが探索ステップをスキップできるためです |
| 出力フォーマットを指定する | 「ファネルチャートで表示して」と指定することで、AIが誤った可視化を推測することを防げます |
| 制約条件を提供する | 「過去30日間と米国リージョンのみを使用して」と指定することで、クエリが絞り込まれ、実行時間が短縮されます |
| 過去の結果を参照する | 「前のクエリと同じフィルターを使って」とすることで、再構築せずにコンテキストを活用できます |
| 関連するスキルをアクティブにする | ドメインスキルはAIにプラットフォーム固有のパターンと関数を教えます |
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| AIが多すぎるクエリを実行する | リクエストが曖昧で、AIがデータを理解しようと探索している | より具体的に指定する：テーブル名、カラム名、時間範囲を明記する |
| 誤ったチャートタイプが表示される | AIのデフォルト選択が意図と一致していない | 明示的に指定する：「棒グラフで表示して」 |
| 構文エラーでクエリが失敗する | AIが使用しているエンジンで利用できない関数を使用した | trino または hive スキルをアクティブにして正しい構文を誘導する |
| AIが多くの質問をしてくる | AIが意図を把握できていない | 最初からより多くのコンテキストを提供する |
| 長いセッションでコンテキストが不足してきた | ツールの結果が多すぎてコンテキストウィンドウが埋まっている | /compact を実行して古いメッセージを要約する |
| AIが失敗したアプローチを繰り返す | AIがエラーから学習できていない可能性がある | 何が問題だったかを明示的に伝える：「そのクエリはタイムアウトしました — より短い時間範囲を使用してください」 |
システム全体を理解したいユーザー向けの説明です：
| 項目 | Web | Desktop (Mac) |
|---|---|---|
| 実行環境 | サーバーサイドのサンドボックス（セキュアワーカー） | サーバーサイドのサンドボックス（Webと同じ） |
| ツールの利用可否 | 同じコアツール — クエリ、ファイル操作、チャート | Webと同じコアツール |
| セッション管理 | ワーカープールによるサーバー管理 | サーバー管理（API経由で接続） |
| コンテキストの永続化 | サーバーサイドのストレージ | ローカルトランスクリプト付きのサーバーサイドストレージ |
| ストリーミング | ストリームAPI経由のSSE | ストリームAPI経由のSSE（Electron IPCを通じてリレー） |
WebとDesktopはどちらも同じサーバーサイドの実行インフラストラクチャに接続します。各チャットセッションは、アカウントのプラグインがプリインストールされたClaude Agent SDKを実行する専用ワーカーインスタンスによってサポートされています。DesktopはネイティブのmacOS統合（メニューバー、自動更新、ディープリンク）を追加しますが、WebとAPIおよびストリーミングレイヤーは共通です。
このガイドを読み終えると、以下のことができるようになります：
- リクエスト処理の5つのステージ（コンテキストの組み立て、分解、ツール選択、実行、結果の組み立て）を説明できる
- AIが特定のタスクに対してどのツールを使用するかを決定する方法を説明できる
-
/compactと/contextを使用して長い会話を管理できる - チャットストリームのツール呼び出しカードを展開して、マルチステップの実行をトレースできる
- 効率的な実行プランを生成するプロンプトを作成できる
| 問題 | 解決策 |
|---|---|
| AIが以前のコンテキストを「忘れた」ように見える | 長い会話は自動的にコンパクト化されている可能性があります。/context を実行して確認するか、特定の結果を明示的に参照してください |
| ツール呼び出しが遅い | 大規模なクエリや複雑な操作には時間がかかります。ツール呼び出しカードで進捗を確認してください |
| AIが誤ったツールを選択した | 明示的に指示する：「このクエリにはHiveエンジンで tdx query を使用して」 |
| 再開後にセッションの状態が異なる | Desktopはトランスクリプトから再開し、Webはサーバーの状態から復元します。どちらもシームレスに動作するはずです — そうでない場合は新しいチャットを開始してください |
- AIチャットインターフェース — チャットUIの操作について詳しく学ぶ
- スキルとマーケットプレイス — オーケストレーションを誘導するスキルを設定する
- セッション内メモリ — AIがセッション内でコンテキストを記憶する仕組み
- セキュリティと権限 — セキュリティとAudit Log
- TDXコマンド — オーケストレーターが呼び出すCLIツール