shape-your-agent

エージェントを設計する

Sanity Context MCP サーバーを使う AI エージェント向けのシステムプロンプトを作成する、任意の対話型ワークフローです。エージェントの設定でシステムプロンプトを管理できるユーザー向けです。

**システムプロンプトにアクセスできませんか？**このスキルは丸ごとスキップしてください。Instructions フィールド（dial-your-context スキルで設定）は主な調整手段であり、単独で機能します。「あなたは役に立つエージェントです。」のような最小限のシステムプロンプトに、適切な内容の Instructions フィールドを組み合わせるだけで、評価では 80% 以上のスコアを達成できます。

始める前に

システムプロンプトの役割

システムプロンプトはエージェントの振る舞いを定義します。つまり、エージェントがどのような存在か、どのように話すか、何を拒否するかを定めます。エージェントの個性やポリシーマニュアルのようなものと考えてください。

システムプロンプトの役割ではないもの

以下は別の場所で扱うため、重複して記述しないでください。

内容	担当するもの
コンテンツのスキーマ、フィールドの意味	Instructions フィールド（Dial Your Context）
クエリのパターン、データの関係性	Instructions フィールド（Dial Your Context）
GROQ の構文とガイダンス	MCP が自動的に提供

これらをシステムプロンプトに重複して記載すると、矛盾が生じます。MCP と Instructions フィールドはデータに関する内容を扱うように設計されています。そこは任せましょう。

基本原則：少ないほど効果的

システムプロンプトの各行は、MCP が提供するコンテキストとモデルの注意を奪い合います。過剰に作り込んだプロンプトは、かえって回答の品質を下げる可能性があります。まずは最小限から始めましょう。具体的なシナリオで必要になった場合にのみ、ルールを追加してください。

---

このセッションの進め方

これはフォームではなく、会話です。質問し、回答に耳を傾け、それに応じて調整してください。手順をチェックリストのように進めず、ユーザーの回答をもとに、どの領域を深掘りする必要があるか判断してください。口調に強いこだわりがあり、境界線の設定に 5 分かかるユーザーもいれば、エッジケースの検討にはサポートが必要でも、自分の話し方はすでにわかっているユーザーもいます。相手の反応に合わせて進めましょう。

---

ステップ 1：ユースケースを把握する

まず、以下の質問に答えてください。

1. このエージェントは誰が使いますか？（顧客、社内チーム、開発者、一般の人々）
2. どのような場面で使いますか？（サポートチャット、ドキュメントサイト、社内ツール、営業アシスタント）
3. どのような問題を解決しますか？（製品に関する質問への回答、問題のトラブルシューティング、コンテンツの検索）
4. ユーザーは通常どのような状態ですか？（情報収集中、行き詰まっている、評価中、いら立っている）

これらの回答が、その後のあらゆる判断の土台になります。いら立っている顧客を対応するサポートエージェントには、開発者向けのドキュメントアシスタントとは異なるルールが必要です。

ステップ 2：振る舞いを定義する

各軸について、具体的な方針を決めます。

口調： プロフェッショナル／カジュアル／親しみやすい／技術的

• 悪い例：「親しみやすく、プロフェッショナルに」
• 良い例：「温かみのある、ファーストネームで呼びかける口調にします。企業的な専門用語は使いません。プレスリリースではなく、知識のある同僚のように書きます。」

冗長さ： デフォルトでどれくらい詳しく説明しますか？

• 悪い例：「簡潔かつ丁寧に」
• 良い例：「最初に 1～2 文で回答します。詳しい説明が必要か尋ねます。本題に入る前に 3 文を超えて書き始めることはありません。」

技術的なレベル： 対象ユーザーに合わせます。

• 悪い例：「ユーザーのレベルに合わせます」
• 良い例：「ユーザーは JavaScript と REST API を知っているものとします。API キーとは何かを説明する必要はありません。GROQ のプロジェクションなど、Sanity 固有の概念は説明します。」

書式： MCP は回答の書式をエージェントに指示しないため、これはシステムプロンプトの役割です。

• 悪い例：「回答を読みやすく整えます」
• 良い例：「短い段落を使います。3 つ以上の項目を比較する場合にのみ、箇条書きを使います。言及する製品すべてに、参照元のページへのリンクを付けます。」

ステップ 3：境界を設定する

各境界には、ルール、発動するシナリオ、望ましい応答が必要です。

拒否する内容：

• 例：「データセット内のコンテンツの作成や変更を求められた場合は、読み取り専用のアシスタントであることを説明し、コンテンツの管理者を案内します。」

別の窓口に案内する内容：

• 例：「請求やアカウントに関する質問には、『製品に関する質問にはお答えできますが、請求については [email protected] にお問い合わせください』と伝えます。」

ガードレール：

• 例：「競合製品の名前には決して言及しません。比較を求められた場合は、代替製品の名前を挙げずに、自社の機能を説明します。」
• 例：「具体的な価格は引用しません。『現在のプランについては、[url] の価格ページをご確認ください』と伝えます。」

情報が見つからない場合：

• 例：「検索結果がない場合は、そのことを正直に伝えます。対応できる関連トピックを2～3件提案します。回答を捏造してはいけません。」

カットテスト： すべてのルールについて、次のように問いかけてください。 「このルールが発動する、実際のユーザーメッセージを挙げられるだろうか？」 挙げられないなら、そのルールは削除します。発動しないルールは無駄です。

ステップ 4：プロンプトを作成する

回答をプロンプトにまとめます。次の構成を使います。

You are [role] for [company/product].

## Voice
[2-3 concrete tone/style rules]

## Boundaries
[Only rules that passed the cut test]

## When you don't know
[Specific fallback behavior]

以上です。ほとんどのエージェントに必要なのは、ここでは1,500語ではなく200～400語です。

例：Eコマースサポートエージェント

You are a customer support agent for Acme Store.

## Voice
- Warm and conversational. Use the customer's first name if provided.
- Keep answers short — lead with the answer, then explain if needed.
- No marketing language. Don't upsell or promote products unprompted.

## Boundaries
- Never process returns, refunds, or order changes. Direct customers to [email protected] for order issues.
- Don't quote exact shipping times. Say "typically 3-5 business days" and link to the shipping policy page.
- If asked about competitor products, focus on what Acme offers without comparisons.
- Don't share internal inventory numbers. Say whether something is "in stock" or "currently unavailable."

## When you don't know
- Say "I don't have that information" directly. Don't hedge or speculate.
- Suggest related topics you can help with.
- For urgent issues, direct to live support at [email protected].

これは約150語です。役割、口調、境界、フォールバックの動作を網羅しています。それ以外のすべて――製品データ、スキーマの詳細、クエリのパターン――は Instructions フィールドと MCP に記述します。

ステップ 5：確認して反復する

実際のシナリオを使ってプロンプトをテストします。

1. ユーザーが実際に尋ねそうな質問を5～10件作成します。 少なくとも2件はエッジケース（話題から外れたもの、拒否したいもの）を含めます。
2. 各境界ルールについて、 そのルールを発動させる質問を書きます。エージェントが正しく対応するか確認します。
3. ルールを1つずつ削除してみます。 ルールがなくてもエージェントが正しく動作するなら、そのルールは不要です。削除します。
4. Instructions フィールドとの競合がないか確認します。 システムプロンプトと Instructions フィールドが同じ懸念事項を扱っている場合は、システムプロンプトから削除します。データに関する内容は Instructions フィールドが優先されます。

プロンプトが長すぎる兆候

• エージェントが一部のルールを無視する（注意が分散している）
• 回答が一般的すぎる、または定型文のように感じられる（制約が多すぎる）
• エージェントがプロンプトの表現をそのまま繰り返す（鸚鵡返し）

プロンプトが短すぎる兆候

• 会話によってエージェントの口調に一貫性がない
• 拒否すべき質問に対してユーザーが回答を得てしまう
• 「わかりません」と言うべき場面でエージェントが推測する

---

クイックリファレンス

システムプロンプトのチェックリスト

• 役割が1文で定義されている
• 口調のルールが具体的である（「プロらしく振る舞う」ではない）
• すべての境界に発動するシナリオがある
• フォールバックの動作が指定されている
• Instructions フィールドの内容と重複していない
• 500語未満（200～400語を目標にする）
• 実際のユーザーの質問を5件以上使ってテスト済み

分離の原則

レイヤー	制御する内容	例
システムプロンプト	エージェントの動作	「正確な価格を引用してはいけません」
Instructions フィールド	データに関するガイダンス	「price はセント単位で保存されています。ドルにするには100で割ります」
MCP	クエリの仕組み	GROQ の構文、ツールの使い方
システムプロンプト	不確実性の伝え方	「『その情報はありません』と伝え、代替案を提案します」
Instructions フィールド	リカバリーの手法	「製品検索で結果が空の場合は、support-article タイプを試します」

各レイヤーにはそれぞれ役割があります。混同しないでください。