suvvy-mcp

Suvvy MCP

概要

Suvvyは、メッセージングチャネルに接続してクライアントとコミュニケーションを取る、LLMを活用したチャットボット（ボット）を作成するためのプラットフォームです。各ボットには、システムプロンプト、ナレッジベース、チャネル連携、任意のカスタムツール（アクション）が備わっています。

要件： Suvvyの管理はすべて、Suvvy MCPサーバーを通じて行います。お使いの環境で設定されていない場合は、ドキュメントを参照してください：https://docs.suvvy.ai

このスキルで「MCPを確認する」または「MCPで利用可能」と記載されている場合は、該当するMCPツールのスキーマを直接確認してください。ツールの説明と引数の定義が、パラメーターの詳細を確認するための正式な情報源です。

リファレンスの使用： 機能について少しでも言及する場合は、作業を続ける前に、該当するreferences/ファイルを必ず読み込んでください。迷った場合は読み込んでください。メインファイルの概要だけに頼らないでください。

まず計画を立て、その後で構築する

ボットを新規作成したり大幅に変更したりする前に、必ず計画を立ててください。計画が確定する前にAPIを呼び出してはいけません。

ユーザーからボットの構築や設定を依頼された場合、すぐに実行を始めてはいけません。代わりに、次の手順に従ってください。

1. 以下のテンプレートを使って完全な計画を作成する
2. 計画をユーザーに提示する — 各設計上の選択理由を説明する
3. 明示的な承認を得る — ユーザーが計画を確認または修正するまで待つ
4. 承認後にのみ実行する — 承認された計画に沿って、手順ごとに進める

新しいボットの構築、大きな機能の追加、ナレッジベースの再構成など、相互に関連する複数の判断が必要な変更には、すべてこの手順を適用します。

計画テンプレート：

**Bot plan:**
- **Role:** [what the bot does and for what company]
- **Knowledge Base:** [FAQ Documents / Vector Knowledge Base / Vector Documents / Tables — list what will be created]
- **Custom Tools:** [actions/webhooks needed — list with purpose]
- **Bot Settings:** [key settings to configure]
- **Dialogue Flow:** [step-by-step interaction logic]
- **Channels:** [where the bot will operate — note: configured manually in dashboard]

ユーザーとのコミュニケーション

対象ユーザーは技術に詳しくありません。 プラットフォームの内部的な仕組みを知らず、知る必要もありません。技術的な仕組みではなく、実現する結果を伝えてください。

（ユーザーから明示的に求められない限り）決して見せてはいけないもの

関数名とパラメーター名 — ユーザーに見せてはいけません。

• ❌ 「title_for_searchパラメーターを指定してcreate_faq_documentを呼び出します……」
• ❌ 「llm_settings.temperature_modeをstabilityに更新します」
• ❌ 「history_type: last_messagesを設定します」

内部オブジェクトID — 裏側に隠しておいてください。

• ❌ 「ボットID：a1b2c3d4-...」
• ❌ 「あなたのボットのinstance_idはxyzです」

代わりに、このように伝える

実行するAPI呼び出しではなく、何が行われるかを説明してください。

これではなく	こう伝える
「ボットを作成するためにcreate_instanceを呼び出します」	「ボットを作成します」
「history_type: last_messagesを設定します」	「直近のN件のメッセージだけを記憶するよう、ボットを設定します」
「llm_settings.temperature_mode: stabilityを更新します」	「ボットの回答が安定して予測可能になるようにします」
「title_for_searchを指定してfaq_documentを作成します」	「……についてのドキュメントをナレッジベースに追加します」
「Custom Toolにwebhookタイプのステップを追加します」	「……の際にお客様のAPIにアクセスするよう設定します」

IDが必要な場合

次の場合に限り、IDを伝えてください。

• ユーザーが明示的に尋ねた場合（「私のボットのIDは何ですか？」）
• 別のシステムで手動設定するためにIDが必要な場合

それ以外の場合は、技術的な仕組みを表に出さないでください。

モデル名は最新のリストからのみ使用する

内部コード（llm_code）でモデルを呼んだり、記憶にある名前を使ったりしてはいけません。古くなっている可能性があります。ユーザーにモデル名を伝える前に、次の手順を実行してください。

1. get_llm_listを呼び出し、現在利用可能なモデルの一覧を取得します。
2. 内部コードではなく、応答に含まれるユーザー向けのモデル名を使います。

❌ 「モデルを選択してください：claude-sonnet-4-6またはgpt-4o」 ✅ 「モデルを選択してください：Claude SonnetまたはGPT-4o」

料金と残高はトークンではなく通貨で伝える

ユーザーにトークン単位の金額を見せてはいけません。必ず通貨に換算してください。

1. get_balance_token_ratesを呼び出し、各モデルのトークン換算レートを取得します。
2. トークン数を金額に換算します。
3. 最終的な金額のみを通貨でユーザーに提示します（例：「1回の対話あたり約3.2 ₽」）。

❌ 「1回の対話の料金は1,200トークンです」 ✅ 「1回の対話の料金は約1.8 ₽です」

用語

概念	主な用語	コード／MCP 用語	ロシア語	別名／略称
主なエンティティ	ボット	instance	Бот, Агент	エージェント
ナレッジベース	ナレッジベース	—	База знаний	БЗ
ナレッジベースのエントリー（直接）	FAQ ドキュメント	faq_document	Прямой вопрос	直接的な質問, ПВ
ナレッジベースのエントリー（Q&A ペア、セマンティック）	ベクトルナレッジベース	vector_knowledge_base	Векторная база знаний	VKB
ナレッジベースのエントリー（ファイル／非構造化、セマンティック）	ベクトルドキュメント	vector_document	Векторный документ	ドキュメント検索
ナレッジベースのエントリー（構造化）	テーブル	table	Таблица	—
呼び出し可能なアクション	カスタムツール	custom_tool	Кастомное действие, Действие, Воркфлоу	アクション, ワークフロー, КД
コミュニケーションの接点	チャネル	channel	Канал	—
事前構築済みコネクター	インテグレーション	integration	Интеграция	—
クライアントのチャットセッション	ダイアログ	dialog	Диалог	対話
サブエージェントのボット	従属ボット	—	Подчиненный бот	スレーブボット
マルチエージェントアーキテクチャ	マルチエージェントシステム	—	Мультиагентная система	—
スケジュールされた送信メッセージ	フォローアップ	—	Фоллоу Ап, Отложенное сообщение	Ping, スケジュール済みメッセージ
指示テンプレートエンジン	テンプレート	use_liquid	Шаблоны в инструкции	—
ダイアログ単位の名前付きフィールド	カスタム変数	custom_variable	Пользовательская переменная, Поле диалога	ダイアログフィールド
ボット定義のダイアログメモリ	メモリ	—	Память	動的変数
ナレッジベース分析用ラベル	ナレッジタグ	knowledge_tag	Тег	タグ
配信用に FAQ ドキュメントに添付されたファイル	送信用ファイル	file_to_send	Файл для отправки	—
ビジュアル検索用に FAQ ドキュメントに添付された画像	画像	image	Картинка	—

MCP ツール名と API パラメーターでは、必ずコード／MCP 用語を使用してください（例：instance_id、faq_document）。

主な概念

ボット（インスタンス）

ボットはプラットフォームの中心となるエンティティです。ボットは必ずテンプレートなしで作成してください。空の設定から始め、ゼロから構築してください。

各ボットには以下が含まれます。

• システムプロンプト（指示とも呼ばれます）。動作、口調、対話ロジックを定義します
• ナレッジベース。FAQ ドキュメント、ベクトルナレッジベース（複数可）、ベクトルドキュメント、および／またはテーブルで構成されます
• チャネル。クライアントがやり取りする場所です（メッセンジャー、チャットウィジェットなど）
• インテグレーション。プラットフォームで利用できる事前構築済みコネクターです。ボットに追加すると、外部アプリケーション（CRM、予約システムなど）と連携するためのツールが追加されます
• カスタムツール。任意で追加できる呼び出し可能なアクションです

主なボット設定

ほとんどのボット設定は update_instance_mcp で更新します。ボットのモデルと LLM パラメーター（llm_code、llm_settings.*、structured_answer、max_answer_tokens）は、update_instance_llm／set_default_instance_llm で別途更新します。設定グループ：LLM と生成、対話履歴、画像処理、メッセージフィルタリング、従業員による割り込み、応答形式、RAG／ベクトル検索、コストとパフォーマンス、チャネルとインテグレーション、組織とマルチプロファイル。一部の設定グループ（稼働時間スケジュール、セキュリティとコンプライアンス、通知とアラート、スパム対策の上限、メッセージ分割ルール）は完全なインスタンススキーマにのみ存在し、MCP では公開されていません。ダッシュボードでのみ設定できます。

update_instance_mcp でボット設定を構成する際は、references/bot-settings.md を読み込んでください。MCP で利用できるフィールドと利用できないフィールドが正確に記載されています。

関数

すべてのボットには、呼び出し可能な関数の統一リストがあります。ボットは、指示に従ってこのリスト内の任意の関数を呼び出せます。関数は次の4つのソースから提供されます。

• ナレッジベース — get_file_text（FAQ Documents）、ナレッジベースごとの名前付き関数（Vector Knowledge Base）、検索関数ごとの名前付き関数（Vector Documents）、テーブルごとの関数（Tables）
• カスタムツール — 手動で設定するアクション
• チャネル — 一部のチャネル連携では、独自の関数が公開されます
• 連携機能 — あらかじめ用意されたコネクターによって、独自の関数が追加されます（CRM、予約など）

get_instance_functions を使用すると、特定のボットで現在利用可能な、すべての呼び出し可能な関数の一覧を取得できます。指示の作成時や監査時に、参照されている関数が実際に存在することを確認するのに便利です。

ナレッジベース

Suvvy は、同じボットで同時に実行できる4種類のナレッジベースに対応しています。FAQ Documents、Vector Knowledge Base、Vector Documents、Tables です。

FAQ レベルのオプション — キーワード（強制取得）： クライアントのメッセージと一致した場合、ボットが応答する前に FAQ 検索（get_file_text）関数を呼び出すよう求めるパターンです。get_file_text_function_settings.force_choice_pattern_list で設定します — ダッシュボードでのみ設定可能で、MCP からは利用できません（references/bot-settings.md を参照）。

FAQ Documents を作成または編集する場合は、references/kb-faq-documents.md を読み込んでください。 Vector Knowledge Base（セマンティックな Q&A ペア）を操作する場合は、references/kb-vector-knowledge-base.md を読み込んでください。 Vector Documents（セマンティックなファイル検索）をインポートまたは設定する場合は、references/kb-vector-document.md を読み込んでください。 Tables または SQL クエリを操作する場合は、references/kb-tables.md を読み込んでください。 分析用の Knowledge Tags を設定する場合は、references/kb-tags.md を読み込んでください。

カスタムツール

カスタムツールは、任意のロジックでボットの機能を拡張します。それぞれ、変数を介して相互にデータを渡せる、順次実行される1つ以上のステップで構成されます。ステップの種類には、Webhook、ボット呼び出し、テーブルクエリ、CRM アクション、決済リンク、画像生成などがあります。

カスタムツールを作成または設定する場合は、references/custom-tools.md を読み込んでください。

連携機能

連携機能は、ボットに追加できる、あらかじめ用意されたコネクターです。カスタムツール（手動で設定するもの）とは異なり、連携機能は既製のものです。接続すると、ボットが外部アプリケーション（CRM、予約プラットフォーム）を操作するためのツールが追加されます。

連携機能のツールで可能になる操作の例：クライアントの予約を設定する、クライアントの記録を検索する、CRM のエントリーを作成または更新する。

ボットのシステムプロンプトを作成する際は、連携機能のツールをカスタムツールと同様に扱い、呼び出しごとに明示的なトリガー条件を定義してください。

ダイアログ

ダイアログとは、ボットとクライアント間のチャットセッションです。クライアントが接続済みのチャネルにメッセージを送信すると、ダイアログが作成されます。クライアントのメッセージはダイアログに届き、ボットが応答し（必要に応じて関数を呼び出します）、返信がチャネル経由で送信されます。

ダイアログでアクティブなボットは、会話の途中で Custom Tool ステップを使って切り替えられます。新しいボットが引き継ぎ、そのチャネルに接続されている必要はありません。

ボットの一時停止／再開 — pause_or_resume_instance_in_dialogue_by_id を使うと、特定の進行中のダイアログでボットを手動で一時停止または再開できます。

従業員として返信 — answer_in_dialogue_as_an_employee を使うと、従業員として進行中のダイアログにメッセージを送信できます。エンドクライアントには通常のメッセージとして表示されます。

ダイアログのコンテキストをクリア — clear_dialogue_context_by_id を使うと、特定のダイアログのコンテキストをリセットできます（テストチャットだけでなく、実際のダイアログに適用されます）。

ダイアログの検索 — search_dialogues_by_message_filter を使うと、メッセージのテキストやその他のフィルターで実際のダイアログを検索できます。

ダイアログデータの読み取り — get_dialogue_list はボットの実際のダイアログをすべて一覧表示します。get_dialogue_by_id は特定のダイアログを取得し、get_dialogue_messages_by_dialogue_id はメッセージ履歴全体を取得します。

ダイアログの評価 — ボットが request_dialogue_rate Custom Tool ステップを使うと、評価リンクが生成されます。get_dialogue_rate_list を使うとすべての評価を取得でき、get_dialogue_rate_list_by_dialogue_id を使うと特定のダイアログの評価を取得できます。

ダイアログ内のアクティブなフォローアップ — get_active_reminder_list_by_dialogue_id と get_scheduled_messages_for_dialogue_by_dialogue_id を使うと、保留中のフォローアップを確認できます。cancel_reminders_in_dialogue を使うと、フォローアップをキャンセルできます。

サブボット

サブボットとは、Custom Tool ステップから呼び出され、単一の関数呼び出し内で実行されるボットです。フローは次のとおりです。

1. アクティブなボットが Custom Tool を呼び出す
2. そのツール内のステップが、関連情報を渡してサブボットを呼び出す
3. サブボットがリクエストを処理する（独自の関数やインテグレーションなどを呼び出します）
4. その応答が関数の結果として呼び出し元のボットに返される

サブボットは通常のボットとまったく同じ方法で設定されますが、チャネルは接続されていません。指示には、技術的な内部エージェント向けのプロンプトを記述してください。専門的なタスクを委任し、各ボットの担当範囲を狭く保つのに役立ちます。

フォローアップ

フォローアップとは、将来の時刻にクライアントへ送信するようスケジュールされたメッセージです。種類は3つあります。フォローアップ（Custom Tool ステップまたは FAQ ドキュメントの取得によるもの — Vector Knowledge Base／Vector Document のエントリーは、取得をトリガーとするフォローアップをサポートしていません）、動的フォローアップ（クライアントごとのイベント日を基準にした時刻で実行）、および スケジュール済みイベントグループ（ボット単位で設定され、ダイアログの非アクティブ状態によってトリガーされます）。

フォローアップまたはスケジュール済みメッセージを設定する際は、references/follow-ups.md を読み込んでください。

カスタム変数（ダイアログフィールド）

カスタム変数は、ダイアログの全期間にわたって保持される名前付きフィールドです。

• ボットが直接、または Custom Tool ステップによって設定できます
• ボットの切り替え、複数ターン、Custom Tool の呼び出しを経ても保持されます
• 会話中に収集したクライアントデータ（電話番号、選択した製品、リードの段階など）の保存に役立ちます
• 変数名の定義済みリストはあらかじめ設定され、ボットはその名前に値を割り当てます
• 型付き：各変数には型があります — string、integer、number、boolean
• show_to_bot：この変数をボットのコンテキストに含めるかどうか（デフォルト：true）。false に設定すると、内部変数を LLM から隠せます。
• is_writeable_by_bot：ボットがこの変数を直接設定できるかどうか（デフォルト：true）。false に設定すると、ボットに対して読み取り専用になります。

メモリ（動的変数）

メモリはカスタム変数と同様に機能しますが、フィールド名の事前定義リストはありません。ボットはキーと値のペアを自由に設定し、キー名と値の両方を決定します。カスタム変数と同様に、メモリエントリはダイアログ全体を通じて保持されます。

• ボット設定で明示的に有効にする必要があります（memory.is_enabled = true）。デフォルトでは無効です。有効にするまでは set_memory ステップは動作しません
• フィールドのセットを事前に把握できない場合や、会話ごとに変わる場合に使用します
• オプション：clear_with_context — ダイアログのコンテキストがリセットされると、メモリエントリをクリアします

標準関数

組み込みの呼び出し可能な関数：ダイアログを停止、メッセージを無視、ダイアログタグを設定、担当者に連絡。update_instance_mcp で有効にします。ボットが各関数を呼び出すタイミングを認識できるよう、指示に明確なトリガー条件を追加してください。

標準関数を有効にする場合や、リマインダー／スケジュール設定を構成する場合は、references/standard-functions.md を読み込んでください。

よくあるボットの類型

Suvvy ボットはさまざまな役割で使用されます。プラットフォームはユースケースに制限を設けていません。一般的な例：

類型	ボットの動作
サポート担当者	製品に関する質問に回答し、問題を解決し、人間の担当者にエスカレーションします
管理者／受付担当者	予約を受け付け、空き状況を確認し、スケジュールを管理します

テキストベースでクライアントとやり取りする役割であれば、どれも有効なユースケースです。

音声エージェント

Suvvy は、電話でのやり取りに対応する音声エージェントモードをサポートしています（STT → LLM → TTS）。分単位の現在の料金は、ユーザーのアカウントマネージャーまたはダッシュボードで確認してください。記憶に基づいて固定料金を提示しないでください。

音声エージェントモードを設定する場合は、references/voice-agent.md を読み込んでください。

ブロードキャスト（Рассылки）

ブロードキャストでは、フィルターに基づいて既存のダイアログ参加者にメッセージを送信します。ボットにすでに接続されているチャネルを通じて動作します。

対象者フィルター： 最終メッセージの時間範囲、カスタム変数の値、特定のチャネル、ダイアログタグ。

送信パラメーター： 送信日時、送信間のランダムな遅延範囲（スパム検出を回避するため）、メッセージ内容（手動入力のテキストまたは LLM が生成したテキスト）。

プレビュー： 確定前に、一致するダイアログの件数がプラットフォームに表示されます。

ブロードキャストはMCP では設定できません。Suvvy ダッシュボードの「Рассылки」タブで設定してください。

ユーザーの切り替え（User Switching）

インテグレーター（インテグレーター向けサブスクリプションを利用しているユーザー）は、紹介リンクを通じて他のユーザーを接続できます。デフォルトでは、エージェントはインテグレーターのプロフィールで動作しますが、ユーザーはエージェントに、接続済みユーザーのいずれかのアカウントに切り替えて作業するよう依頼できます。

切り替え方法：

1. ユーザーが対象アカウントのメールアドレスまたは会社名を伝えます。
2. エージェントはメールアドレスまたは会社名をフィルターとして渡し、get_user_list を呼び出します。ページ番号は 0 から始まります。最初のページは page: 0 です。
3. エージェントは応答から対象ユーザーを見つけ、その _id を記憶します。
4. 以降のすべての MCP リクエストで、エージェントはこの _id をオプションのパラメーター active_user_id として渡します。
5. active_user_id を指定したいずれかのツールの呼び出しで AUTH_PARTNER_ACCESS_FORBIDDEN エラーが返された場合、インテグレーターは Suvvy の個人アカウントに手動でログインし、そのユーザーのパスワードを入力してユーザーのアカウントに切り替える必要があります。その後、エージェントに戻り、そのユーザーとして作業を続けられます。

active_user_id を渡している間は、すべての操作が指定したユーザーとして実行されます。インテグレーターのプロフィールに戻るには、このパラメーターの指定をやめてください。

ボットのシステムプロンプトを作成する

ボットのシステムプロンプト、指示変数、テンプレート（指示内の「Шаблоны」）、または FAQ ドキュメントの内容を作成または確認する場合は、references/writing-prompts.md を読み込んでください。

機能選択ガイド

計画時にこのセクションを使って、目的に合ったツールを選択してください。

ナレッジベース：どの種類を使うべきですか？

状況	使用するもの
ユーザーの意図が具体的で予測しやすく、明確な回答がある	FAQ Document
短く構造化された回答、分岐ロジック、または取得時の CRM イベント	FAQ Document
短い Q&A 形式の事実が多数あり、固定の FAQ タイトルでは対応しきれない、または種類が多すぎる	Vector Knowledge Base
マニュアル、ポリシー文書、記事などの大規模で非構造化されたコンテンツ	Vector Document
個別のインテントに分割するには、コンテンツが大きすぎる、または種類が多すぎる	Vector Document
価格表、カタログ、スケジュールなどの構造化された参照データ	Table
ボットが値を指定して特定の行を検索する必要がある	Table
回答を禁止する制限があるにもかかわらず、ボットがそのトピックについてハルシネーションを起こす	FAQ Document（おとり／подменный прямой вопрос）

迷った場合：意図を表す明確な 2～4 語のタイトルを書けるなら、FAQ Document を使います。関連性が薄い Q&A の組み合わせが大量にあるなら、Vector Knowledge Base を使います。非構造化ファイルのコンテンツなら、Vector Document を使います。

カスタムツールとインテグレーション

状況	使用するもの
外部 API 呼び出し、Webhook、またはカスタムの複数ステップからなるワークフロー	Custom Tool
決済、画像生成、キーボード、CRM への書き込み操作	Custom Tool（専用のステップタイプを使用）
プラットフォームにネイティブの事前構築済みコネクターがある（amoCRM、Bitrix、予約）	Integration
カスタムロジックなしで、単純なトリガーにより CRM に書き込む必要がある	Integration

カスタム変数とメモリ

状況	使用するもの
あらかじめ項目が決まっている（クライアント名、電話番号、選択した商品）	Custom Variables
項目名が動的、または会話ごとに異なる	Memory（ボットの設定で有効にする必要があります）

自動トリガー（trigger_settings）を使う場合

ツールをボットの判断なしに実行する必要がある場合は、自動トリガーを使います。たとえば、新しい対話をすべて CRM に記録する（new_dialogue）、またはボットの応答ごとにチェックを実行する（new_instance_response）場合です。会話のコンテキストに基づいて、ツールを呼び出すタイミングをボットに判断させる場合は、通常の（トリガーなしの）Custom Tool を使います。

指示でテンプレート（Шаблоны в инструкции）を使う場合

1 つのボットが、異なる指示内容を必要とする複数のチャネルまたはコンテキストに対応する場合は、テンプレートを使います。たとえば、マーケットプレイスごとに異なる商品コード、チャネルごとに異なるトーン、または時間やクライアントデータに応じた異なるルールがある場合です。コンテキストによる変化のない単一チャネルのボットでは、通常の指示変数（{variable}）で十分です。

サブボット／マルチエージェントシステムを使う場合

ユーザーが**「マルチエージェントシステム」**（мультиагентная система）と言う場合、サブボットおよび／またはボット切り替えで構成されたアーキテクチャを意味します。プラットフォームに独立した概念はありません。

• サブボット（bot_call step） — アクティブなボットが、1 回の関数呼び出し内で別のボットをサブエージェントとして呼び出し、その応答を受け取って会話を続けます。クライアントには切り替えが表示されません。
• ボット切り替え（change_active_bot step） — アクティブなボットが対話を別のボットに全面的に引き継ぎます。元のボットに戻るには、instance_id に null を渡します。

専用のスペシャリスト向けプロンプトが役立つほどタスクが複雑な場合は、サブボットを使います。会話全体の流れを別のボットに引き継ぐ場合は、ボット切り替えを使います。

ボット設定のワークフロー

はじめに

まずは、ボットを作成し（create_instance を使用し、テンプレートは常に使用しません）、システムプロンプトの初版を作成して、よくあるインテント向けの初期 FAQ ドキュメントを作成するとよいでしょう。これだけで最初のテストを実行できます。その後は反復的に進めます。カスタムツールやカスタム変数、メモリを追加し、ボットの設定を調整しながらテストを続けます。

ボットのコピー — from_instance（既存のボットの ID）を指定して create_instance を使用すると、指示、ナレッジベース、設定を含む完全なコピーを作成できます。

自動生成（ダッシュボードのみ）： プラットフォームでは、テキストの説明やウェブサイトの URL から、指示の草案や FAQ ドキュメントを生成できます。初期草案の作成に使用し、テストの前に必ず内容を確認して編集してください。

テストと反復のサイクル

ボットを変更したら、必ずテストしてください。基本的なサイクルは次のとおりです。

Change something → Test → Identify issues → Fix → Reset test chat → Repeat

テストセッションのチェックリスト：

• 現在のテスト会話を取得します：get_latest_test_dialogue_for_instance_by_instance_id → dialogue_id を保存します
• クリーンなセッションにリセットします：get_new_test_dialogue_for_instance_by_instance_id
• クライアントのメッセージを1件ずつ送信します：send_message_to_test_dialogue_by_id
• 応答を読み、問題がないか確認します
• 問題が見つかった場合は、設定を修正し、手順2からリセットして繰り返します
• 各シナリオを複数回実行します。LLM の応答は非決定的なため、1回成功しただけではボットが信頼できるとは限りません

新しいシナリオを始める前に、必ずテストチャットをリセットしてください。古いコンテキストが残っていると、誤解を招く結果になります。

テストメッセージの書き方

テストチャットのメッセージはクライアントの視点から送信されます（message_sender: "customer"）。実際のシナリオで本物のクライアントになったつもりで、ユーザーと同じようにメッセージを1件ずつ送信してください。

テストシーケンスの例：

→ "Привет"
→ "Хочу узнать стоимость ваших услуг"
→ "А есть скидки для новых клиентов?"
→ "Хорошо, хочу записаться на консультацию"

ヒント：

• 1つのフレーズだけを単独でテストするのではなく、想定される会話シナリオを最初から最後まで進めます
• 実行ごとに表現を変えます。ボットは自然で不完全な言葉にも対応する必要があります
• チャネル固有の動作が重要な場合は、fake_channel を使用して特定のチャネルタイプ（例：telegram_bot、whatsapp、amocrm）をシミュレートします
• 従業員による対応への切り替えをテストするには、message_sender: "employee" としてメッセージを送信し、ボットが停止することを確認します
• メッセージをデバッグ対象としてマークする — mark_message_as_debug_in_test_dialogue を使用すると、テストチャットのコンテキスト内で特定のメッセージを「無効化」できます。チャット全体をリセットせずに長いテストセッションを繰り返す場合に便利です。
• SQL クエリを手動で実行する — user_query_table を使用すると、テーブルに対して SQL クエリを直接実行できます。カスタムツールに組み込む前に、想定した行があるかを確認するのに便利です。

正確さだけでなく、応答のスタイルも確認してください。 技術的に正しい回答でも、冷淡だったり不自然だったりすれば問題です。

問題の診断

ボットが予期しない動作をしたり、テストに失敗したりした場合は、references/diagnosing-issues.md を読み込んでください。

分析

ダッシュボードの分析タブでは、設定可能な期間ごとにボットのパフォーマンスを追跡できます。

指標	説明
会話数	期間内の会話の合計数
メッセージの内訳	受信／ボット対応／従業員対応の合計数
会話あたりの平均コスト	ルーブル／クレジットでのコスト
自動化率	人間を介さずにボットが対応したメッセージの割合
タグの分布	出現したナレッジタグとその頻度
関数呼び出し数	各関数が呼び出された回数

ビューは2種類あります。会話（集計サマリー）と会話ログ（各会話のメッセージ単位の詳細）です。

分析は読み取り専用で、MCP 経由ではアクセスできません。Suvvy ダッシュボードで確認してください。

既存のシステムプロンプトのレビュー

ボットのプロンプトを監査する際は、次の点を確認します。

1. すべての指示に矛盾や重複がないことを確認します
2. 各セクションに適切な内容のみが含まれていることを確認します（対話ロジックに FAQ データが含まれていないか、制限事項に指示が含まれていないか）
3. すべての関数呼び出しにトリガー条件があり、正しい形式が使用されていることを確認します
4. プロンプト内にある事実や参照情報を FAQ ドキュメントに移します
5. 対話の手順が順番どおりで、各手順にアクションが 1 つだけ含まれ、論理的につながっていることを確認します

対話コストの削減

ボットのコストを最適化するとき、またはユーザーが対話の料金について質問したときは、references/reducing-costs.md を読み込みます。

ファイルのアップロード

MCP サーバーはファイルを直接アップロードできません。ファイルのアップロードが必要な操作（Vector Documents、Vector Knowledge Base xlsx、FAQ Documents、Tables、Files to Send、Images、テストチャットの添付ファイルのインポートなど）を行う場合は、references/uploading-files.md を読み込みます。

注意点

間違い	修正方法
システムプロンプトに事実データ（価格、住所など）を記載する	FAQ Documents に移します
トリガー条件なしで関数を呼び出す	「クライアントが X を尋ねる／行う場合は…」という前置きを追加します
短く構造化された回答に Vector Knowledge Base / Vector Document を使用する	代わりに FAQ Documents を使用します
1 つの FAQ Document に複数のインテントを含める	1 ファイルにつき 1 インテントにします
汎用的な FAQ Document のタイトルを使用する	インテントに基づく具体的なタイトル（2～4 語）を使用します
既知の特定ファイルに対して Vector Knowledge Base / Vector Document の検索関数を呼び出す	代わりに、正確な FAQ Document のタイトルを指定して get_file_text を使用します
ボットの設定でメモリーを有効にせずに set_memory 手順を使用する	先に update_instance_mcp で memory.is_enabled: true を有効にします
title と title_for_search が一致せず、ボットが誤った説明を認識する	ボットが認識できるよう、インテントに基づくフレーズを title_for_search に設定します
プラットフォームのテンプレートからボットを作成する	常にテンプレートを使用せずに作成します。create_instance に引数を渡さないか、template_code: "default" を使用します
test_llm_code のモデルが実際の対話にも影響すると期待する	test_llm_code はテストチャットでのみ適用されます
1 ターンで複数のツール呼び出しが必要なシナリオで parallel_tool_call_limit（フィールドのデフォルト値：1）に達する	update_instance_llm で値を増やすか、シナリオを簡素化するか、サブタスクを Subordinate Bots に委任します
矛盾する指示により、ボットが同じ関数を 2 回呼び出す	指示を監査して条件の競合を確認し、各トリガーが固有であることを確認します
トークンのオーバーフロー（コンテキストがモデルの上限を超える）	message_history_settings のウィンドウを小さくし、指示を短くし、大きな FAQ Documents を分割します
ページネーションを 1 から開始する	ページネーションを使用するすべてのメソッドでは、0 始まりのページ番号を使用します。最初のページは page: 1 ではなく page: 0 です