create-agent-with-sanity-context

Sanity Context でエージェントを構築する

AI エージェントが Sanity のコンテンツにインテリジェントにアクセスできるようにします。埋め込みのみのアプローチとは異なり、Sanity Context はスキーマを認識するため、エージェントはコンテンツ構造を推論し、実際のフィールド値を使ってクエリを実行し、参照をたどり、構造的なフィルターとセマンティック検索を組み合わせることができます。

Sanity Context はエージェントにスキーマを提供し、GROQ の使い方を教えますが、ドメインの知識までは持っていません。この不足は、Instructions フィールド（データセット固有のクエリガイダンス）と、任意で system prompt（エージェントの動作とトーン）を使って補います。

このワークフローに関わる 3 つの役割：

• あなた — このスキルを実行し、ユーザーのセットアップを支援するエージェント
• ユーザー — 作業相手となる人間で、ドメインとデータを把握しています
• 本番エージェント — 構築中のエージェントで、エンドユーザーにサービスを提供します

必要なもの

エージェントのコードに必要なのは、次の 3 つの値だけです。

値	入手先
MCP エンドポイント URL (SANITY_CONTEXT_MCP_URL)	Context アプリでエンドポイントを作成すると、そのエンドポイント上に表示されます（ステップ 1）
組織 API トークン (SANITY_ORGANIZATION_TOKEN)	管理 → 組織 → API → Tokens → Add API token を選び、Organization permissions で Context にチェックを入れます。読み取りのみを行うエージェントには Viewer を、Insights も記録する場合は Editor を選びます（ステップ 3）。プロジェクトトークンは使用できません。
LLM API キー	LLM プロバイダー（Anthropic、OpenAI など）から取得します。どのプロバイダーでも使用できます

セットアップには、次のものも必要です。

要件	必要な場合	入手先
Context が有効であること	常時	組織の管理者が Manage の組織の Labs ページで有効にします。これにより Knowledge Bases も有効になります
Sanity プロジェクトとデータセット	GROQ モード	エンドポイントの作成時に選択します。スキーマのデプロイ元でもあります（sanity.config.ts）
組織 ID	Insights	管理 → 組織の設定、または組織の URL

組織トークンはサーバー側のシークレットです。ブラウザーに渡してはなりません。

Sanity Context の仕組み

Sanity Context MCP サーバーは、AI エージェントに Sanity コンテンツへの構造化された読み取り専用アクセスを提供します。基本的な統合パターンは次のとおりです。

1. 初期コンテキスト：/initial-context HTTP エンドポイント経由で初期コンテキスト（GROQ モードではスキーマ、Knowledge Base モードでは Knowledge Base の概要）を取得し、システムプロンプトに挿入します
2. MCP 接続：MCP エンドポイント URL への HTTP トランスポート
3. 認証：組織の API トークンを使用したベアラートークン
4. ツールの検出：MCP クライアントから利用可能なツールを取得し、LLM に渡します
5. システムプロンプト：本番環境のエージェントに、役割、トーン、境界を伝えます

2 つの検索モード。 エンドポイントのコンテンツソースによって、提供されるモードが決まります。

• GROQ モード（データセットソース）：エージェントはスキーマを参考に、GROQ でライブデータセットをクエリします。スキーマから参照先を判断できる、構造化された一貫性のあるコンテンツ（カタログ、記事、FAQ など）に適しています。文章フィールドに有用な詳細を含むカタログなど、中間的なコンテンツの場合は、データセットの埋め込みを有効にして GROQ モードを使用します。
• Knowledge Base モード（Knowledge Base ソース、ベータ版）：エージェントは、データセット、ウェブサイト、ファイルから事前に構築されたインデックスを読み取ります。複数の場所にある文章に回答が分散しており、回答を見つけること自体が難しい場合に適しています。コンテキスト検索モードを参照してください。

エンドポイントが提供するモードは 1 つです。データセットソースと Knowledge Base ソースの両方がある場合は、データセットが優先され、Knowledge Base はエラーなしで無視されます。どちらが適しているかユーザーに確認してください。Sanity データセットに含まれるコンテンツには、GROQ モードがデフォルトで適しています。

MCP エンドポイントは、Sanity Dashboard の Context app で作成します。各エンドポイントには次のフィールドがあります。

フィールド	目的
タイトル	人が読めるラベルです。エージェントには初期コンテキストの見出しとしても表示されます
名前	URL 識別子（小文字、数字、ハイフン）。組織内で一意で、作成後は変更できません
コンテンツソース	エンドポイントが提供するもの：データセット（GROQ モード）または 1 つ以上の Knowledge Base（Knowledge Base モード）
指示	エージェントに挿入される、ドメイン固有のガイダンスです
GROQ フィルター	エージェントが読み取れるドキュメントを絞り込む GROQ フィルター式です。GROQ モードのみ

MCP URL：

https://api.sanity.io/v1/context/organizations/:organizationId/mcp/:endpointName

エンドポイントの作成後、Context app に URL が表示されます。Context app で指示やフィルターを変更すると、エージェントを再デプロイしなくても反映されます。エージェントが /initial-context をキャッシュする場合（以下を推奨）、指示の変更はキャッシュが更新されたときに反映されます。

URL クエリパラメーターはリクエストごとに適用されます（テストや開発に便利です）。

• ?instructions=<content> — エンドポイントの指示を上書きします（空の ?instructions= を指定すると、白紙の状態になります）
• ?groqFilter=<expression> — エンドポイントのフィルターをさらに絞り込みます。保存済みのフィルターは常に適用され、両者は && で結合されます
• ?perspective=drafts|raw|<releaseId> — コンテンツの視点です。デフォルトは published です

初期コンテキスト：

初期コンテキストは必ず /initial-context HTTP エンドポイント経由で取得し、システムプロンプトに挿入してください。これにより、最初のメッセージのレイテンシーが大幅に改善されます。エージェントはツール呼び出しを行わなくても、スキーマと利用可能なツールを把握できます。また、スキーマのプレフィックスが会話間で安定するため、プロンプトキャッシュの精度も向上します。

MCP URL のパスの末尾に /initial-context を追加し（クエリパラメーターより前）、同じ認証ヘッダーを使用します。

# SANITY_CONTEXT_MCP_URL=https://api.sanity.io/v1/context/organizations/:organizationId/mcp/:endpointName
curl "$SANITY_CONTEXT_MCP_URL/initial-context" \
  -H "Authorization: Bearer $SANITY_ORGANIZATION_TOKEN"

長時間稼働するサーバーでは、結果を短い TTL（参照実装では 5 分）でキャッシュし、システムプロンプトに含めてください。TTL を短くすることで、スキーマ、Instructions、ナレッジベースの再構築を再デプロイなしで反映できます。

重要：モデルには必ず初期コンテキストを渡す必要があります。 システムプロンプトに直接含めるか、initial_context ツールから取得できるようにしてください。どちらもない状態にしてはいけません。初期コンテキストがなければ、エージェントはスキーマも概要も把握できず、推測することになります。

• 取得に成功してシステムプロンプトに含めた場合 → モデルが再取得しないよう、initial_context ツールを削除します。
• 取得に失敗した場合、またはシステムプロンプトを制御できない場合（サードパーティ製の MCP クライアントなど）→ initial_context ツールを残します。エージェントは最初のメッセージでこのツールを呼び出します。

ペイロードが実際にシステムプロンプトに含まれていない限り、このツールを削除しないでください。

利用可能な MCP ツール

エンドポイントのモードによって、提供されるツールが決まります。

• GROQ モード： スキーマの読み取り、GROQ クエリの実行（セマンティック検索は任意）、大きな配列フィールドの読み取りを行うツールです。クエリには常にエンドポイントの GROQ フィルターが適用されます。
• ナレッジベースモード： ナレッジベースのエントリーを検索して読み取るツールです。

どちらのモードでも、initial_context（GROQ モードではスキーマの概要、ナレッジベースモードではナレッジベースの概要と、エンドポイントの Instructions）を提供します。これは /initial-context HTTP エンドポイントと同じペイロードです。

ツールの一覧をハードコードしないでください。ツールのセットは今後増えるため、MCP クライアント（mcpClient.tools() または tools/list）から取得してください。各ツールの機能については、Context MCP ツールを参照してください。

開発とデバッグ向け： 汎用の Sanity MCP は、Sanity プロジェクトへのより広範なアクセスを提供します（スキーマのデプロイ、ドキュメント管理など）。開発中には便利ですが、顧客向けアプリケーションでの使用は想定していません。

始める前に：ユーザーの状況を把握する

完全な統合には、4 つの独立したコンポーネントがあり、それぞれ別の場所に存在する場合があります。

コンポーネント	内容	例
1. MCP エンドポイント	デプロイ済みのスキーマ（GROQ モード）または構築済みのナレッジベースに加え、Context アプリで作成したエンドポイント	スキーマのデプロイには Studio（v5.1.0 以降）、ナレッジベースとエンドポイントには Sanity Dashboard の Context アプリ
2. エージェントの実装	Sanity Context に接続し、LLM とのやり取りを処理するコード	Next.js API ルート、Express サーバー、Python サービス、または MCP 互換クライアント
3. フロントエンド	ユーザーがエージェントを操作するための UI	チャットウィジェット、検索インターフェース、CLI、またはバックエンドサービスの場合はなし
4. 関数	Sanity Blueprints によるスケジュール済みの分類（Insights の Step 3 の場合のみ）	sanity.blueprint.ts + functions/ ディレクトリ — 独自の配置要件があります（Insights: プロジェクト構成を参照）

MCP エンドポイントは常に必要であり、デプロイ済みのスキーマ（GROQ モード、Studio v5.1.0 以降）または構築済みのナレッジベースがその基盤となります。これらがなければ、エージェントは接続先を持てません。フロントエンドが必要かどうかはユースケースによって異なります（多くのエージェントはバックエンドサービスとして実行されるか、既存の UI に統合されます）。

コードを書く前に、プロジェクトを調べて次の点を把握してください。

1. プロジェクトの構成：トップレベルの package.json を読み（workspaces または pnpm-workspace.yaml を確認）、ロックファイルを見つけて、独立したアプリやパッケージを整理します。これにより sanity.blueprint.ts と functions/ の配置場所が決まります。Insights: プロジェクト構成を参照してください。
2. 使用している技術スタック：どのフレームワークやランタイムを使っていますか？（Next.js、Remix、Node サーバー、Python など）
3. 使用している AI ライブラリ：Vercel AI SDK、LangChain、直接の API 呼び出しなど
4. 対象ドメイン：エージェントは何を支援しますか？（ショッピング、ドキュメント、サポート、検索など）
5. 支援が必要なコンポーネント：必要なのは 1 つまたは 2 つだけの場合もあります。

• コンポーネントが別々のリポジトリにある場合（最も一般的）：アクセスできるコンポーネントは 1 つだけかもしれません。可能な範囲で作業を完了し、他のリポジトリで残っている手順をユーザーに伝えてください。
• コンポーネントが同じ場所にある場合：すべて同じプロジェクト内にあります。ユーザーが最初に取り組みたい内容に沿って作業を進めてください。
• コードベースに Studio がない場合：GROQ モードでは、別の場所にある Studio からスキーマがすでにデプロイされているか、ユーザーに確認してください。デプロイされていない場合、エンドポイントが応答するには事前にデプロイする必要があります。ナレッジベースモードでは、デプロイ済みのスキーマは不要です。

ワークフロー

必ずワークフロー全体を提示してください。 ユーザーの依頼が限定的に見える場合でも、4つのステップすべてを伝えてください。すべてを実装する必要はありませんが、利用できる選択肢を把握してもらう必要があります。ステップ3は任意で、エージェントが動作するようになったらステップ4を推奨します。どちらも選択肢としてあることを伝えたうえで、ユーザーに決めてもらってください。各ステップで実現できることを説明しながら、順を追って案内してください。

1. MCP エンドポイントを作成する — スキーマをデプロイするかナレッジベースを構築してから、Context アプリでエンドポイントを作成します
2. エージェントを構築する — コンテンツに接続された、動作するチャットボットを用意します
3. 会話インサイト（任意） — 会話を追跡・分類し、エージェントがうまく対応できる点と苦手な点を確認します
4. エージェントを調整する — 調整スキルを使って指示とシステムプロンプトを改善します

各ステップを完了したら、次のステップを提示してください。ユーザーが必要なものを得たとき、または明確に後回しにしたときは終了します。

ステップ 1：MCP エンドポイントを作成する

まずユーザーに検索モードを確認してから（2 つの検索モードを参照）、コンテンツソースを準備します。

GROQ モード：スキーマをデプロイする。 MCP サーバーはローカルマシンではなく Sanity からスキーマを読み込むため、Studio v5.1.0+ からデプロイされたスキーマがない場合、データセットソースを指定したエンドポイントは機能しません。最初に Studio の sanity バージョンを確認してください。その後、Studio のディレクトリから次を実行します。

• すべての Studio： npx sanity schema deploy
• Sanity ホストの Studio： npx sanity deploy も使用できますが、その場合はスキーマのデプロイを開始するため、ユーザーがブラウザーでデプロイ済みの Studio を一度開く必要があります
• 外部ホストの Studio（Sanity CLI v5.8.0+）：npx sanity deploy --external --schema-required は外部 URL を登録し、スキーマのデプロイに失敗した場合はすぐにエラーになります

ナレッジベースモード：ナレッジベースを作成して構築する。 ユーザーは Context アプリでこれを行います（組織の Administrator または Developer ロールが必要です）。大まかな手順は次のとおりです。

1. New knowledge base を選択し、Title と Purpose を入力します。誰に役立つものか、何を支援するものかを 1、2 文で説明してください。目的を具体的にすると、より良い構築結果が得られます
2. Add source：データセット、ウェブサイト、またはファイルを追加します。まずは、最新の資料を絞り込んで追加してください
3. Build entries を選択し、Entries up to date と表示されるまで待ってから、Entries と Issues に目を通します

ソース、問題、最新状態の維持について詳しくは、ナレッジベースを作成するを案内してください。

Context アプリでエンドポイントを作成する。 ユーザーは Sanity Dashboard で作成します。組織の Administrator または Developer ロールが必要です。データセットを関連付けるには、そのプロジェクトでも Administrator または Developer ロールが必要で、データセットへの読み取りアクセスが制限なく許可されている必要があります。次の内容を入力するよう伝えてください。

1. Sanity Dashboard で Context アプリを開き、New MCP endpoint を選択します
2. Title：例：「Product Assistant」のような、わかりやすい名前を入力します
3. Name：例：product-assistant のような、短く安定した名前を入力します。この名前は URL の一部となり、後から変更できません
4. Content source：
   • GROQ モード：Dataset タブを選択し、プロジェクトとデータセットを選びます。ユーザーが必要なロールを持っていないプロジェクトは無効になります
   • ナレッジベースモード：Knowledge bases タブを選択し、提供するナレッジベースにチェックを入れます
5. GROQ filter（GROQ モード、任意）：_type in ["product", "category"] のようなフィルター式を指定します。まずは広めに設定し、dial-your-context スキルを使って絞り込んでください
6. Instructions：ここでは空のままにします。ステップ 4 で説明します
7. Create endpoint を選択し、詳細ページからエンドポイント URL をコピーします

ユーザーがまだ組織トークンを持っていない場合は取得します（必要なものを参照）。エージェントの他のシークレットと一緒に SANITY_ORGANIZATION_TOKEN として保存します。

エンドポイントを検証する：

curl -X POST "$SANITY_CONTEXT_MCP_URL" \
  -H "Authorization: Bearer $SANITY_ORGANIZATION_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

応答には、initial_context を含む result.tools 配列が返されます。エラーまたは空のリストが返される場合は、トラブルシューティングを参照してください。

ステップ 2：エージェントを構築する（ユーザーの技術スタックに合わせる）

ユーザーはすでにエージェントまたは MCP クライアントを持っていますか？ MCP エンドポイント URL に、組織のトークンを Bearer トークンとして指定して接続するだけです。ツールは自動的に表示されます。

ゼロから構築しますか？ MCP 接続と LLM 統合のセットアップを支援します。どの技術スタックでも、モデルには初期コンテキストを渡す必要があります。システムプロンプトにインラインで含めるか、initial_context ツールとして渡します（初期コンテキストを参照）。スニペットとリファレンス実装では、Anthropic と Vercel AI SDK v7 を使用していますが、このパターンはあらゆる LLM プロバイダー（OpenAI、ローカルモデルなど）で機能します。基本から始め、必要に応じて高度なパターンを追加してください。

references/connecting-an-agent.mdに従ってください：インストール、初期コンテキストの取得、CLI と API 向けのリクエスト／レスポンスパターン、各フレームワークでの配置場所を含むチャット UI 向けのストリーミングルート、フレームワークの注意点、Next.js リファレンス実装全体の構成を説明しています。

最初から最後まで動作を確認します： エージェントに「どのコンテンツにアクセスできますか？」と尋ねます。初期コンテキストをインラインで渡していれば、initial_context ツールを呼び出さずにすぐ回答します。

システムプロンプト： 簡潔に保ち、振る舞いに焦点を当ててください。何を記述すべきかは shape-your-agent スキルで確認できます。

ステップ 3：会話インサイト（任意）

インサイトを提案し、利用するかどうかはユーザーに委ねます。 トラッキングがなければ、エージェントがユーザーを支援できているのか、何も気づかれないまま失敗しているのかを把握するのは困難です。インサイトでは、ユーザーからの質問、エージェントが苦戦している箇所、不足しているコンテンツを確認できます。Context Editor トークンとスケジュール済み関数が追加されるため、ユーザーがまだ希望していない場合は省略してください。

ユーザーが希望する場合、セットアップは 2 つの部分で構成されます。両方とも実施してください：

1. テレメトリ — 既存の streamText 呼び出しに統合を 1 つ追加します（会話の文字起こしを組織の Context ストアに保存します）。会話の記録には Context Editor トークンが必要です。1 つの Editor トークンで MCP とインサイトの両方に使用できます。
2. 分類 — ユーザー自身の AI SDK モデルで会話を分析し、判定結果を Context API 経由で記録するスケジュール済み関数をデプロイします。

分類を行わないテレメトリは、生の会話を保存するだけです。成功スコア、センチメント、コンテンツの不足箇所を抽出するのは分類です。これらが実際のインサイトになります。両方をまとめてセットアップしてください。

references/conversation-classification.mdに従ってセットアップしてください。 ガイドでは両方の手順を最初から最後まで説明しています。会話が分類されると、Sanity Dashboard の Context アプリにインサイトが表示されます。

ステップ 4：エージェントを調整する（推奨）

本番環境のエージェントが動作したら：

1. dial-your-context スキルを使って Instructions フィールドを調整します。ユーザーのデータセットを一緒に調査し、調査結果を検証しながら、本番環境のエージェントにスキーマだけでは明らかでない点を教える簡潔な Instructions を作成する対話型セッションです。対象には、直感に反するフィールド名、間接的な参照チェーン、データ品質の問題、必須フィルター、クエリパターンが含まれます。このスキルでは、エンドポイントの GROQ フィルターを設定して、本番環境のエージェントが参照するコンテンツの範囲を限定することもできます。ユーザーは結果を Context アプリのエンドポイントの Instructions フィールドと GROQ フィールドに貼り付けます。

   ナレッジベースモード： dial-your-context は GROQ モードを対象としています。ナレッジベースの場合、問題を解決しソースを修正することで、Context アプリの回答を改善できます。詳しくはナレッジベースの問題を解決するを参照してください。

2. shape-your-agent スキルを使って システムプロンプトを整えます（任意）。ユーザーが本番環境のエージェントのシステムプロンプトを管理している場合、口調、境界、ガードレールの定義に役立ちます。システムプロンプトを管理していない場合は省略してください。

ベストプラクティス

• コンテンツフィルター：エンドポイントの GROQ フィルターを使って、本番環境のエージェントに表示する内容を絞り込みます。まずは広めに設定し、実際に必要な内容に応じて絞り込んでください。フィルターには GROQ のフィルター式を指定します。完全なクエリやプロジェクションではなく、*[...] の内側の部分です。例：_type in ["product", "article"]、_type == "article" && language == "en"、_type == "product" && references(*[_type == "category" && slug.current == "electronics"]._id)
• Instructions フィールド：簡潔に保ち、自動生成されたスキーマから明らかでない情報だけを含めてください。スキーマの情報を重複して記載しないでください。dial-your-context スキルを参照してください。
• システムプロンプト：禁止する動作と書式ルールを明確に指定してください。シンプルにすることが大切です。過度に作り込んだプロンプトは、Instructions の内容を妨げる可能性があります。shape-your-agent スキルを参照してください。
• パッケージのバージョン：@sanity/context が必要なのは Insights（ステップ 3）の場合のみです。Insights を使わないエージェントにはインストールしません。使用する場合は、最新バージョンを使ってください。npm info @sanity/context version を実行すると確認できます。その他のパッケージについては、最新リリースを確認するために npm info <package> version を使います。ただし、リファレンスの package.json で使用されているメジャーバージョンを使ってください（スニペットは AI SDK v7 など、それらのメジャーバージョンを前提に記述されています）。AI SDK と Sanity のパッケージは頻繁に更新されるため、古いバージョンを使うと、デバッグが難しいエラーが発生します。

トラブルシューティング

MCP から「401 Unauthorized」が返る

• **「Missing Sanity session」：**トークンがないか、Bearer ヘッダーがありません。
• **「Not a member of this organization」：**無効なトークンか、URL に指定された組織に属していないトークンです。

MCP ルートでは、どちらもそのメッセージとともに JSON-RPC -32001 として返されます。/initial-context のエラーには、missingCredential または organizationAccessDenied というコードも含まれます。SANITY_ORGANIZATION_TOKEN が設定され、エージェントのコードで読み込まれ、Authorization: Bearer <token> として送信されていること、また URL の組織 ID が正しいことを確認してください。

「404」：MCP エンドポイントが見つからない

JSON-RPC -32001 と「MCP endpoint not found: 」というメッセージを伴う HTTP 404 が返されます。URL のエンドポイント名か組織 ID が間違っています。Context アプリでエンドポイントの URL をコピーしてください。名前は小文字で、変更できません。（-32001 は上記の 401 にも使われるため、HTTP ステータスを確認してください。）

「403 Forbidden」：JSON-RPC -32007（contextGrantRequired）または -32006（knowledgeBaseAccessDenied）

トークンが Context へのアクセス権を持つ組織 API トークンではありません。-32007 はデータセットをソースとするエンドポイントのチェックで返されます。-32006（「No access to knowledge base 'kb…'」）は、エンドポイントが提供する各ナレッジベースのチェックで返されます。初回実行時に最もよくある失敗はプロジェクトトークンです。権限がどれほど広くても拒否されます。必要なものの説明に従って、組織トークンを作成してください。

-32007 のメッセージは「This requires an organization API token with Context access ('sanity.knowledge-base.read')…」です。/initial-context では、同じエラーに contextGrantRequired というコードが表示されます。

-32004：「Only datasets with deployed Studio applications are supported」

エンドポイントのプロジェクトとデータセットにスキーマがデプロイされていません。v5.1.0 以降の Studio からデプロイして（ステップ 1を参照）、再接続してください。

-32005：「Mode is set to "knowledge_base" but no knowledge bases are configured」

エンドポイントにデータセットソースがなく、提供可能なナレッジベースもありません。GROQ モードの場合は、Context アプリでエンドポイントを編集し、コンテンツソースとして Dataset タブを選択してください。Knowledge Base モードの場合は、エンドポイントで少なくとも 1 つのナレッジベースが選択されていることを確認してください。

「ドキュメントが見つかりません」／結果が空

Context アプリでエンドポイントの GROQ フィルターを確認してください。

• GROQ フィルターは正しいですか？
• ドキュメントの種類のスペルは正しいですか？
• フィルターに一致する公開済みドキュメントはありますか？　エンドポイントはデフォルトで published パースペクティブを読み込みます

何も一致しないフィルターは接続が壊れているように見えるため、接続をデバッグする前に確認してください。複数の Studio ワークスペースが同じデータセットを参照している場合、?workspace=<name> が設定されていない限り、エンドポイントは最初のワークスペースを使用するため、誤ったスキーマが使われる可能性があります。

ツールが表示されない

1. mcpClient.tools() がツールを返すことを確認してください（ログに出力します）
2. MCP URL が正しいことを確認してください。組織 ID とエンドポイント名を確認します
3. URL に tools パラメーターがある場合、ツール一覧が絞り込まれます。すべて表示するには、そのパラメーターを削除してください