Create Agent With Sanity Context
Build AI agents with structured access to Sanity content via Sanity Context. Use when setting up a Sanity-powered chatbot, connecting an AI assistant to Sanity content, or adding client-side tools to an agent. Covers Studio setup, agent implementation, and advanced patterns. Always use this skill when users mention building a chatbot with Sanity, creating an AI assistant for their content, setting up the Sanity Context MCP server, integrating Sanity with Claude/GPT/any LLM, making content searchable by AI, implementing semantic search over Sanity data, or connecting their CMS to an AI agent.
- Skill ID
- sanity-io/context/create-agent-with-sanity-context
- Publisher
- sanity-io
- Repository
- context
- Installs
- 0
- Files
- 84
- Synced
- Sep 23, 2026
Open any RiverX project, open the Skills panel in the chat, and search for this identifier. The files are fetched from the source repository at install time.
sanity-io/context/create-agent-with-sanity-contextInstalls these files- SKILL.md
- references/adapting-to-stacks.md
- references/conversation-classification.md
- references/ecommerce/.env.example
- references/ecommerce/.gitignore
- references/ecommerce/_index.md
- references/ecommerce/app/.gitignore
- references/ecommerce/app/components.json
- references/ecommerce/app/eslint.config.mjs
- references/ecommerce/app/next.config.ts
- references/ecommerce/app/package.json
- references/ecommerce/app/postcss.config.mjs
- references/ecommerce/app/public/file.svg
- references/ecommerce/app/public/globe.svg
- references/ecommerce/app/public/next.svg
- references/ecommerce/app/public/vercel.svg
- references/ecommerce/app/public/window.svg
- references/ecommerce/app/sanity-typegen.json
- references/ecommerce/app/sanity.cli.ts
- references/ecommerce/app/sanity.types.ts
- references/ecommerce/app/src/app/api/chat/route.ts
- references/ecommerce/app/src/app/favicon.ico
- references/ecommerce/app/src/app/globals.css
- references/ecommerce/app/src/app/layout.tsx
- references/ecommerce/app/src/app/page.tsx
- references/ecommerce/app/src/app/products/[slug]/page.tsx
- references/ecommerce/app/src/app/products/loading.tsx
- references/ecommerce/app/src/app/products/page.tsx
- references/ecommerce/app/src/components/add-to-cart-button.tsx
- references/ecommerce/app/src/components/chat/chat-button.tsx
- references/ecommerce/app/src/components/chat/chat-input.tsx
- references/ecommerce/app/src/components/chat/chat.tsx
- references/ecommerce/app/src/components/chat/loader.tsx
- references/ecommerce/app/src/components/chat/message/document.tsx
- references/ecommerce/app/src/components/chat/message/message.tsx
- references/ecommerce/app/src/components/chat/message/product.tsx
- references/ecommerce/app/src/components/chat/message/text-part.tsx
- references/ecommerce/app/src/components/filter-bar.tsx
- references/ecommerce/app/src/components/header.tsx
- references/ecommerce/app/src/components/product-card.tsx
- references/ecommerce/app/src/components/product-details.tsx
- references/ecommerce/app/src/components/product-grid.tsx
- references/ecommerce/app/src/components/product-pagination.tsx
- references/ecommerce/app/src/components/ui/badge.tsx
- references/ecommerce/app/src/components/ui/button.tsx
- references/ecommerce/app/src/components/ui/pagination.tsx
- references/ecommerce/app/src/components/ui/select.tsx
- references/ecommerce/app/src/lib/capture-context.ts
- references/ecommerce/app/src/lib/client-tools.ts
- references/ecommerce/app/src/lib/utils.ts
- references/ecommerce/app/src/sanity/lib/client.ts
- references/ecommerce/app/src/sanity/lib/image.ts
- references/ecommerce/app/src/sanity/lib/insights-client.ts
- references/ecommerce/app/src/sanity/queries/categories.ts
- references/ecommerce/app/src/sanity/queries/filters.ts
- references/ecommerce/app/src/sanity/queries/fragments.ts
- references/ecommerce/app/src/sanity/queries/index.ts
- references/ecommerce/app/src/sanity/queries/products.ts
- references/ecommerce/app/tsconfig.json
- references/ecommerce/functions/classify-conversations/index.ts
- references/ecommerce/package.json
- references/ecommerce/sanity.blueprint.ts
- references/ecommerce/studio/.gitignore
- references/ecommerce/studio/eslint.config.mjs
- references/ecommerce/studio/package.json
- references/ecommerce/studio/sanity.cli.ts
- references/ecommerce/studio/sanity.config.ts
- references/ecommerce/studio/schemaTypes/documents/agentConfig.ts
- references/ecommerce/studio/schemaTypes/documents/brand.ts
- references/ecommerce/studio/schemaTypes/documents/category.ts
- references/ecommerce/studio/schemaTypes/documents/color.ts
- references/ecommerce/studio/schemaTypes/documents/material.ts
- references/ecommerce/studio/schemaTypes/documents/product.ts
- references/ecommerce/studio/schemaTypes/documents/size.ts
- references/ecommerce/studio/schemaTypes/index.ts
- references/ecommerce/studio/schemaTypes/objects/price.ts
- references/ecommerce/studio/schemaTypes/objects/productVariant.ts
- references/ecommerce/studio/schemaTypes/objects/seo.ts
- references/ecommerce/studio/static/.gitkeep
- references/ecommerce/studio/tsconfig.json
- references/nextjs-agent.md
- references/studio-setup.md
- references/sveltekit-agent.md
- references/system-prompts.md
What this skill tells the agent
Build an Agent with Sanity Context
Give AI agents intelligent access to your Sanity content. Unlike embedding-only approaches, Sanity Context is schema-aware—agents can reason over your content structure, query with real field values, follow references, and combine structural filters with semantic search.
What this enables:
- Agents understand the relationships between your content types
- Queries use actual schema fields, not just text similarity
- Results respect your content model (categories, tags, references)
- Semantic search is available when needed, layered on structure
Sanity Context gives agents your schema and teaches them GROQ, but it can't know your domain. You close that gap through the Instructions field (dataset-specific query guidance) and optionally the system prompt (agent behavior and tone).
Three actors in this workflow:
- You — the agent executing this skill, helping the user set things up
- The user — the human you're working with, who knows their domain and data
- The production agent — the agent being built, which will serve end users
What You'll Need
Before starting, gather these credentials:
| Credential | Where to get it |
|---|---|
| Sanity Project ID | Your sanity.config.ts or sanity.io/manage |
| Dataset name | Usually production — check your sanity.config.ts |
| Sanity API read token | Run npx sanity tokens add "Sanity Context" --role=viewer --yes --json from the project directory (or pass --project-id=<id>). Alternatively, create at sanity.io/manage → Project → API → Tokens with Viewer role. |
| LLM API key | From your LLM provider (Anthropic, OpenAI, etc.) — any provider works |
How Sanity Context Works
The Sanity Context MCP server gives AI agents structured access to Sanity content. The core integration pattern:
- Initial Context: Fetch schema context via the
/initial-contextHTTP endpoint and inject it into the system prompt - MCP Connection: HTTP transport to the Sanity Context URL
- Authentication: Bearer token using Sanity API read token
- Tool Discovery: Get available tools from MCP client, pass to LLM
- System Prompt: Tell the production agent its role, tone, and boundaries
MCP URL formats:
https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset— Base URL. No document needed, configure via query params or use as-is.https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset/:slug— Document URL. Applies the configuration from a Sanity Context document.
Sanity Context documents (type sanity.agentContext) are created in Sanity Studio and configure the MCP endpoint. They have three fields:
| Field | Schema field | Purpose |
|---|---|---|
| Slug | slug | Unique URL identifier — becomes the :slug in the MCP URL |
| Instructions | instructions | Domain-specific guidance for the agent, injected into tool descriptions |
| Content Filter | groqFilter | A GROQ expression scoping which documents the agent can access |
This means Studio users can manage agent behavior without touching code — updating instructions or narrowing the content filter takes effect immediately.
URL query params override the document's configuration (useful for testing and development):
?instructions=<content>— Override instructions (use?instructions=""for a blank slate)?groqFilter=<expression>— Override the content filter
The integration is simple: Connect to the MCP URL, get tools, use them. The reference implementation shows one way to do this—adapt to your stack and LLM provider.
Initial context (recommended):
Always fetch the schema context via the /initial-context HTTP endpoint and inject it into the system prompt. This gives a significant latency improvement on the first message—the agent already knows the schema and available tools without needing a tool call. It also enables better prompt caching since the schema prefix is stable across conversations.
Append /initial-context to the MCP URL path (before any query params), using the same auth header:
curl https://api.sanity.io/v2026-03-03/context/mcp/:projectId/:dataset/:slug/initial-context \
-H "Authorization: Bearer $SANITY_API_TOKEN"Fetch once, cache the result, and include it in your system prompt. When using this, exclude the initial_context tool from the tools passed to the LLM to avoid redundant calls.
If you don't control the system prompt (e.g. using a third-party MCP client), the initial_context MCP tool still works — the agent will call it on the first message instead.
Available MCP Tools
| Tool | Purpose |
|---|---|
initial_context | Get compressed schema overview (types, fields, document counts). Also available via the /initial-context HTTP endpoint. |
groq_query | Execute GROQ queries with optional semantic search |
schema_explorer | Get detailed schema for a specific document type |
For development and debugging: The general Sanity MCP provides broader access to your Sanity project (schema deployment, document management, etc.). Useful during development but not intended for customer-facing applications.
Before You Start: Understand the User's Situation
A complete integration has four distinct components that may live in different places:
| Component | What it is | Examples |
|---|---|---|
| 1. Studio Setup | Configure the context plugin and create Sanity Context documents | Sanity Studio (separate repo or embedded) |
More from sanity-io
Use this skill in a project
Open any RiverX project, search the Skills panel for sanity-io/context/create-agent-with-sanity-context, and install it in one click.