Affan Raza

Posted on Oct 3

DevDocs Intelligence: A Gemini Agent for Version-Aware Next.js Documentation

#sanitychallenge #ai #agents #webdev

Sanity Challenge Path One Submission

DevDocs Intelligence: A Gemini Agent for Version-Aware Next.js Documentation

A developer documentation intelligence agent powered by Gemini, Sanity Knowledge Base, and Sanity Context MCP.

What I Built

I built DevDocs Intelligence, a Gemini-powered agent designed to answer complex, version-aware questions about Next.js documentation.

The core idea is simple: developer documentation shouldn't always be treated as a flat collection of text.

A question such as:

“Explain the major routing changes between Next.js 15 and Next.js 16, including params, Route Handlers, and the transition from middleware.ts to proxy.ts.”

can require information from multiple documentation types and versions.

So instead of storing everything as unstructured text, I modeled the knowledge as structured, interconnected content in Sanity and exposed it to the agent through Sanity Context MCP.

The resulting architecture is:

User Question
      ↓
Next.js Frontend
      ↓
Application API
      ↓
Gemini Agent
      ↓
Sanity Context MCP
      ↓
Sanity Knowledge Base
      ↓
Structured Sanity Content
      ↓
Grounded Answer + Sources

Why I Built It

Framework documentation changes quickly.

A developer asking a version-specific question may need to understand:

what changed between versions
whether an API behavior changed
whether a feature was deprecated
how to migrate
which APIs or features are affected
how different pieces of documentation relate to each other

A simple keyword search can find matching text, but it doesn't necessarily preserve these relationships.

For DevDocs Intelligence, I wanted to explore a different approach:

Model the documentation itself as structured knowledge and let an AI agent retrieve that knowledge through Sanity Context MCP.

The Structured Content Model

I created four custom Sanity document types:

Content Type	Purpose
Documentation	General Next.js concepts, guides, and feature documentation
API Reference	APIs, parameters, examples, limitations, and related documentation
Migration Guide	Version-to-version changes, breaking changes, migration steps, and affected APIs
Release Note	Version-specific changes, breaking changes, deprecations, and affected features

These documents aren't isolated.

They contain explicit references to related documentation, APIs, migrations, and release notes.

The current corpus contains:

30 structured documents
4 custom content types
128 cross-document relationships

This gives the retrieval layer more context than simply searching a collection of independent text chunks.

Why Sanity?

Sanity is the structured content foundation of the project.

Instead of treating a documentation page as one large piece of text, I can represent different types of knowledge using different schemas and connect them through references.

For example:

Migration Guide
      │
      ├──→ API Reference
      │
      ├──→ Documentation
      │
      └──→ Release Note

This becomes particularly useful for version-aware questions where the answer may span multiple sources.

Sanity's structured content model therefore becomes part of the agent's reasoning context rather than simply acting as a place to store documents.

Sanity Knowledge Base

The structured Sanity corpus is connected to a Sanity Knowledge Base designed specifically for answering complex Next.js documentation questions.

The Knowledge Base contains:

30 source documents
18 Knowledge Base entries
100% source span coverage in the successful build

The goal is to make the structured documentation available as navigable contextual knowledge for the agent.

How Sanity Context MCP Fits In

MCP (Model Context Protocol) provides the interface between the Gemini agent and Sanity's contextual knowledge.

The agent does not directly contain the documentation.

Instead:

Gemini Agent
     │
     │ MCP tool calls
     ▼
Sanity Context MCP
     │
     ▼
Knowledge Base
     │
     ▼
Structured Sanity Content

During testing, the agent used Sanity Context MCP operations including:

initial_context
knowledge_base_search
knowledge_base_read

This allows the agent to retrieve relevant information when it needs additional context instead of placing the entire documentation corpus into the model prompt.

How the Agent Works

When a developer submits a question:

1. The user asks a question

For example:

Explain the major routing changes between Next.js 15 and Next.js 16, including params, Route Handlers, and the transition from middleware.ts to proxy.ts.

2. The Next.js frontend sends the request

The frontend communicates with the application's chat API.

3. The backend initializes the agent

The backend handles the request, validates the input, and connects the agent to the configured Sanity Context MCP endpoint.

4. Gemini determines what context is needed

Gemini acts as the reasoning and generation layer.

It can use the MCP-exposed tools to retrieve relevant contextual information.

5. Sanity Context retrieves the knowledge

The MCP layer accesses the Sanity Knowledge Base and retrieves relevant structured content.

The retrieved information can span multiple document types.

6. Gemini synthesizes the answer

Gemini uses the retrieved content to produce a coherent, grounded response.

7. The response is streamed to the frontend

The backend streams the response progressively to the UI.

8. Sources are displayed

The frontend shows the Sanity sources used to ground the response.

Architecture

                         ┌──────────────────┐
                         │       User       │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ Next.js Frontend │
                         │  TypeScript/UI   │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ Application API  │
                         │ Agent Orchestration
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │   Gemini Agent   │
                         │ Reasoning +      │
                         │ Generation       │
                         └────────┬─────────┘
                                  │
                             MCP Tool Calls
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ Sanity Context  │
                         │       MCP       │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ Sanity Knowledge │
                         │      Base       │
                         └────────┬─────────┘
                                  │
                                  ▼
                   ┌────────────────────────────┐
                   │ Structured Sanity Content │
                   │                            │
                   │ Documentation              │
                   │ API References             │
                   │ Migration Guides           │
                   │ Release Notes              │
                   └────────────────────────────┘

A Real Example

One of the main queries I use to demonstrate the system is:

Explain the major routing changes between Next.js 15 and Next.js 16, including params, Route Handlers, and the transition from middleware.ts to proxy.ts.

This is useful because the answer requires more than retrieving one isolated paragraph.

The agent can retrieve information across:

Documentation
API Reference
Migration Guide
Release Note

The resulting response is grounded in Sanity sources and displayed alongside the answer in the application.

Other Example Queries

Next.js 15 caching

What is the default dynamic staleTime in Next.js 15 and how did it change from previous versions?

Route Handlers

How did Route Handler caching behavior change in Next.js 15?

Version migration

What are the major changes developers should know when migrating from Next.js 14 to Next.js 15?

These queries test whether the agent can connect version-specific information rather than simply return a matching keyword.

Key Features

Gemini-powered documentation agent
Sanity structured content
Sanity Knowledge Base
Sanity Context MCP integration
Four domain-specific content types
Cross-document relationships
Version-aware retrieval
Grounded responses
Sanity source display
Progressive response streaming
Server-side secret management
Error handling and validation
Production deployment on Vercel

Tech Stack

Frontend

Next.js
TypeScript
Tailwind CSS

AI

Gemini
AI SDK

Content & Retrieval

Sanity
Sanity Knowledge Base
Sanity Context MCP

Deployment

Vercel

Technical Implementation

The application is divided into a few major layers:

frontend/
    ↓
Next.js application
    ↓
Chat API
    ↓
Agent layer
    ↓
Gemini + MCP
    ↓
Sanity Context
    ↓
Knowledge Base

The backend keeps sensitive credentials server-side, including:

GEMINI_API_KEY
SANITY_API_READ_TOKEN
SANITY_CONTEXT_MCP_URL

These are not exposed as public frontend environment variables.

Streaming

The application supports progressive responses rather than waiting for the entire answer to finish.

The flow is:

Gemini
   ↓
Agent Backend
   ↓
Streaming/SSE
   ↓
Next.js Frontend
   ↓
Progressive UI Response

This makes the interaction feel more like an active agent session rather than a request that remains blocked until the complete response is generated.

Testing & Validation

I tested the complete workflow with real questions against the hosted Sanity Context MCP endpoint.

The validation covered:

Sanity Context MCP tool invocation
Knowledge Base retrieval
Multi-document retrieval
Grounded Sanity sources
Streaming responses
Empty/malformed request handling
Server-side secret handling
TypeScript validation
Production build

The agent was tested with both focused documentation questions and higher-value cross-document questions involving version changes and related APIs.

Sanity Project Details

Sanity Project ID: 0ovd9f2s

Dataset: production

Content Types:

documentation
apiReference
migrationGuide
releaseNote

Structured Documents: 30

Cross-document Relationships: 128

Knowledge Base Entries: 18

What I Learned

One of the biggest takeaways from this project was that the structure of the knowledge matters as much as the model used to reason over it.

A documentation agent becomes much more useful when the underlying information contains explicit relationships between:

versions
APIs
migrations
release changes
documentation

Sanity made it possible to model those relationships explicitly and expose the resulting knowledge to an agent through Context MCP.

This also changed how I think about RAG systems: retrieval doesn't always have to mean searching a flat collection of chunks. The underlying content model can itself provide useful context.

Future Improvements

Some areas I would explore next:

Expand the corpus beyond Next.js
Add more framework versions
Add evaluation datasets for retrieval quality
Measure grounded-answer accuracy systematically
Add richer source-level explanations
Explore more complex multi-hop documentation queries

Built for the Sanity Challenge

This project was built for the Sanity Challenge 2026 — Path One: Ship an agent that queries real content.

The core implementation focuses on using:

Structured Sanity Content → Knowledge Base → Sanity Context MCP → Gemini Agent

rather than treating Sanity as only a storage layer.

Links

Live Demo:

https://devdocs-intelligence.vercel.app

Source Code:

https://github.com/affanraza84/devdocs-intelligence

Final Note

DevDocs Intelligence is an exploration of what happens when developer documentation is treated as structured, connected knowledge instead of just a collection of searchable pages.

The goal is not simply to make an LLM answer documentation questions, but to give the agent a structured knowledge layer it can actually reason over.