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 wh

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](https://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](https://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: 1. Initial Context : Fetch schema context via the /initial context HTTP endpoint and inject it into the system prompt 2. MCP Connection : HTTP transport to the Sanity Context URL 3. Authentication : Bearer token using Sanity API read token 4. Tool Discovery : Get available tools from MCP client, pass to LLM 5. 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: 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) 2. Agent Implementation Code that connects to Sanity Context and handles LLM interactions Next.js API route, Express server, Python service, or any MCP compatible client 3. Frontend UI for users to interact with the agent Chat widget, search interface, CLI—or none for backend services 4. Functions Scheduled classification via Sanity Blueprints sanity.blueprint.ts + functions/ directory — has its own placement constraints (see [Sanity Blueprints & Functions]( sanity blueprints functions)) A deployed Studio (v5.1.0+) is always required. Not every integration needs the Sanity Context plugin or document—the base MCP URL works without them, so users can start with just agent implementation and add document configuration later—or vice versa. Frontend depends on the use case (many agents run as backend services or integrate into existing UIs). Before writing any code, inspect the project to understand: 1. Project layout : Read the top level package.json (check for workspaces or a pnpm workspace.yaml ), locate the lockfile, and map out the distinct apps/packages. This determines where sanity.blueprint.ts and functions/ will go — see [Sanity Blueprints & Functions]( sanity blueprints functions). 2. Their stack : What framework/runtime? (Next.js, Remix, Node server, Python, etc.) 3. Their AI library : Vercel AI SDK, LangChain, direct API calls, etc. 4. Their domain : What will the agent help with? (Shopping, docs, support, search, etc.) 5. Which components they need help with : They may only need one or two. Components in different repos (most common): You may only have access to one component. Complete what you can, then tell the user what steps remain for the other repos. Co located components : All in the same project—work through them based on what the user wants to tackle first. No Studio in the codebase? Ask the user if Studio setup is done elsewhere, or if they want to skip the Sanity Context plugin and document for now—the base URL works without them. The reference patterns use Next.js + Vercel AI SDK, but adapt to whatever the user is working with. Workflow Always present the full workflow. Even if the user's request seems narrow, inform them of all four steps — you don't have to implement everything, but they should know what's available. A working chatbot without Insights is only half the value. Walk the user through all four steps, explaining what each unlocks: 1. Build the Agent — Get a working chatbot connected to their content 2. Studio Setup — Configure the plugin and create a Sanity Context document 3. Conversation Insights — Track and classify conversations (this is what makes the data useful) 4. Tune the Agent — Refine instructions and system prompt using the tuning skills After completing each step, proactively present the next one. Only stop when all steps are done or the user explicitly defers. Quick Validation (Optional) Before building the production agent, validate that the MCP endpoint is reachable. If the user doesn't have a read token yet, offer to create one from the terminal — detect the projectId from sanity.config.ts or sanity.cli.ts if available: This outputs JSON with the token value. If not inside a Sanity project directory, pass project id=<id explicitly. Then test the endpoint: This confirms the token works and the endpoint is reachable. The base URL (no slug) works without a Sanity Context document—add a slug to apply a document's configuration. Step 1: Build the Agent (Adapt to user's stack) The user already has an agent or MCP client? They just need to connect it to their Sanity Context URL with a Bearer token. The tools will appear automatically. Building from scratch? Help the user set up the MCP connection and LLM integration. The reference implementations use Vercel AI SDK with Anthropic, but the pattern works with any LLM provider (OpenAI, local models, etc.). Start with the basics and add advanced patterns as needed. Framework specific guides: Next.js : See [references/nextjs agent.md](references/nextjs agent.md) SvelteKit : See [references/sveltekit agent.md](references/sveltekit agent.md) Other stacks (Express, Remix, Python, LangChain): See [references/adapting to stacks.md](references/adapting to stacks.md) System prompts (applies to all frameworks): See [references/system prompts.md](references/system prompts.md) for structure and domain specific examples (e commerce, docs, support, content curation). The framework guides cover: Core setup (required): MCP connection, authentication, basic chat route Frontend (optional): Chat component for the framework, including markdown rendering (LLM responses are markdown — a renderer like react markdown or marked is needed to display

create-agent-with-sanity-context