create-agent-with-sanity-context

使用 Sanity Context 构建 Agent

为 AI Agent 提供智能访问 Sanity 内容的能力。与仅依赖嵌入的方法不同，Sanity Context 能理解架构，因此 Agent 可以分析内容结构、使用实际字段值进行查询、跟踪引用，并将结构化筛选与语义搜索结合起来。

Sanity Context 会为 Agent 提供架构并教它们使用 GROQ，但它不了解你的领域知识。你可以通过 Instructions 字段（特定数据集的查询指南）来弥补这一点，也可以选择使用 system prompt（Agent 的行为和语气）。

此工作流中的三个参与者：

• 你 — 执行此技能并帮助用户完成设置的 Agent
• 用户 — 与你协作、了解其领域和数据的人
• 生产 Agent — 正在构建、将为最终用户提供服务的 Agent

所需内容

Agent 代码只需要三个值：

值	获取方式
MCP endpoint URL (SANITY_CONTEXT_MCP_URL)	创建端点后，可在 Context 应用中查看（步骤 1）
Organization API token (SANITY_ORGANIZATION_TOKEN)	前往 Manage → 组织 → API → Tokens → Add API token，然后在 Organization permissions 下勾选 Context。如果 Agent 只读取数据，请选择 Viewer；如果它还会记录 Insights（步骤 3），请选择 Editor。项目令牌无法使用。
LLM API key	从你的大模型提供商获取（Anthropic、OpenAI 等）——任何提供商均可

设置还涉及：

要求	适用场景	获取方式
Context 已启用	始终需要	由组织管理员在 Manage 中的组织实验室页面启用。此操作也会启用知识库
Sanity 项目和数据集	GROQ 模式	创建端点时选择；架构也从此处部署（sanity.config.ts）
Organization ID	Insights	前往 Manage → 组织设置，或查看组织 URL

组织令牌是服务器端密钥，绝不能发送到浏览器。

Sanity Context 的工作原理

Sanity Context MCP 服务为 AI Agent 提供对 Sanity 内容的结构化只读访问。核心集成模式如下：

1. 初始上下文：通过 /initial-context HTTP 端点获取初始上下文（GROQ 模式下的架构，知识库模式下的知识库大纲），并将其注入系统提示词
2. MCP 连接：通过 HTTP 传输连接到 MCP 端点 URL
3. 身份验证：使用组织 API 令牌进行 Bearer 身份验证
4. 工具发现：从 MCP 客户端获取可用工具，并传递给大模型
5. 系统提示词：告知生产 Agent 其角色、语气和边界

两种检索模式。 端点的内容源决定它提供哪种模式：

• GROQ 模式（数据集源）：Agent 使用 GROQ 查询实时数据集，并根据架构进行检索。适用于结构化、内容一致且架构能告诉 Agent 去哪里查找的内容，例如目录、文章和常见问题解答。对于介于两者之间的内容（目录中包含有用的散文类字段），请启用数据集嵌入，并继续使用 GROQ 模式。
• 知识库模式（知识库源，测试版）：Agent 读取预先构建的索引，该索引由数据集、网站和文件提前构建。适用于答案分散在多个来源的散文内容中，且找到答案本身就是难点的情况。请参阅上下文检索模式。

一个端点只能提供一种模式。如果端点同时配置了数据集源和知识库源，则以数据集为准，知识库会被忽略，且不会报错。请询问用户哪种模式更合适；对于存放在 Sanity 数据集中的内容，默认使用 GROQ 模式。

MCP 端点是在 Sanity Dashboard 中的 Context app 内创建的。每个端点都包含以下字段：

字段	用途
标题	便于阅读的标签。Agent 还会将其显示为初始上下文的标题
名称	URL 标识符（小写字母、数字、连字符）。在组织内唯一，且创建后不可更改
内容源	端点提供的内容：数据集（GROQ 模式）或一个或多个知识库（知识库模式）
说明	针对特定领域的 Agent 指引，会注入初始上下文
GROQ 过滤器	用于限定 Agent 可读取文档范围的 GROQ 过滤表达式。仅适用于 GROQ 模式

MCP URL：

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

创建端点后，Context app 会显示其 URL。在 Context app 中更改说明或过滤器后，无需重新部署 Agent 即可生效。如果 Agent 缓存了 /initial-context（建议如下），说明的更改会在缓存刷新时显示。

URL 查询参数按请求生效（适用于测试和开发）：

• ?instructions=<content> — 覆盖端点的说明（空的 ?instructions= 会提供空白上下文）
• ?groqFilter=<expression> — 缩小端点的过滤范围。已保存的过滤器始终生效；两者会通过 && 组合
• ?perspective=drafts|raw|<releaseId> — 内容视角。默认为 published

初始上下文：

始终通过 /initial-context HTTP 端点获取初始上下文，并将其注入系统提示词。这能显著降低首条消息的延迟——Agent 无需调用工具，就已了解架构和可用工具。它还能改善提示词缓存效果，因为架构前缀在不同对话间保持稳定。

在 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 工具获取。绝不能两者都没有：缺少初始上下文时，Agent 没有架构或大纲，只能猜测。

• 获取成功并已内嵌 → 移除 initial_context 工具，避免模型再次获取。
• 获取失败，或你无法控制系统提示词（例如使用第三方 MCP 客户端）→ 保留 initial_context 工具；Agent 会在第一条消息时调用它。

只有在载荷确实已纳入系统提示词时，才能移除该工具。

可用的 MCP 工具

端点的模式决定其提供哪些工具：

• GROQ 模式： 提供读取架构、运行 GROQ 查询（可选语义搜索）以及读取大型数组字段的工具。查询始终受端点的 GROQ 筛选条件约束。
• 知识库模式： 提供搜索和读取知识库条目的工具。

两种模式都提供 initial_context：GROQ 模式下是架构概览，知识库模式下是知识库大纲，此外还包含端点的 Instructions。载荷与 /initial-context HTTP 端点返回的相同。

不要将工具列表硬编码。工具集会不断扩展，因此请从 MCP 客户端获取（mcpClient.tools() 或 tools/list）。有关各工具的功能，请参阅 Context MCP 工具。

用于开发和调试： 通用 Sanity MCP 可更广泛地访问你的 Sanity 项目（架构部署、文档管理等）。它适用于开发期间，但不面向客户应用。

开始之前：了解用户的情况

完整集成包含 四个不同的组件，它们可能位于不同的位置：

组件	说明	示例
1. MCP 端点	已部署的 schema（GROQ 模式）或已构建的知识库，以及在 Context 应用中创建的端点	使用 Studio（v5.1.0+）部署 schema，在 Sanity Dashboard 中使用 Context 应用构建知识库并创建端点
2. Agent 实现	连接到 Sanity Context 并处理 LLM 交互的代码	Next.js API 路由、Express 服务、Python 服务，或任何兼容 MCP 的客户端
3. 前端	供用户与 Agent 交互的 UI	聊天小组件、搜索界面、CLI，或后端服务（无需前端）
4. Functions	通过 Sanity Blueprints 定时分类（仅 Insights 的 Step 3 需要）	sanity.blueprint.ts + functions/ 目录——有其自身的放置限制（参见 Insights：项目结构）

始终需要 MCP 端点，并由已部署的 schema（GROQ 模式，Studio v5.1.0+）或已构建的知识库提供支持：没有它们，Agent 就无从连接。是否需要前端取决于具体用例（许多 Agent 以后端服务的形式运行，或集成到现有 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. 领域：Agent 将提供什么帮助？（购物、文档、支持、搜索等）
5. 需要哪些组件的帮助：用户可能只需要其中一两个组件。

• 组件位于不同仓库（最常见）：你可能只能访问其中一个组件。完成能做的部分，然后告知用户其他仓库还需要完成哪些步骤。
• 组件位于同一处：所有组件都在同一个项目中——根据用户希望优先处理的内容逐步推进。
• 代码库中没有 Studio？ 对于 GROQ 模式，询问用户 schema 是否已从其他位置的 Studio 部署。如果尚未部署，则必须先部署，端点才能提供服务。知识库模式不需要已部署的 schema。

工作流

始终介绍完整的工作流。 即使用户的请求看起来范围很窄，也要告知他们全部四个步骤——你不必全部实施，但他们应该了解有哪些选项。第 3 步是可选的，第 4 步则建议在 Agent 可用后进行；确保用户知道这两步的存在，再由他们决定。引导用户逐步完成，并说明每一步能带来什么：

1. 创建 MCP 端点 — 部署 schema 或构建知识库，然后在 Context 应用中创建端点
2. 构建 Agent — 创建一个可用且已连接到其内容的聊天机器人
3. 对话洞察（可选）— 跟踪并分类对话，以了解 Agent 擅长和不擅长之处
4. 调整 Agent — 使用调优技能完善指令和系统提示词

完成每一步后，介绍下一步。用户获得所需内容或明确表示暂缓后，即可停止。

第 1 步：创建 MCP 端点

先与用户确认检索模式（参见两种检索模式），然后准备内容来源。

GROQ 模式：部署 schema。 MCP 服务从 Sanity 读取 schema，而不是从本地计算机读取；如果 Studio v5.1.0+ 中的 schema 尚未部署，使用数据集作为来源的端点将无法提供服务。先检查 Studio 的 sanity 版本。然后从 Studio 目录运行：

• 任何 Studio： npx sanity schema deploy
• Sanity 托管的 Studio： 也可以运行 npx sanity deploy，但之后用户必须在浏览器中打开已部署的 Studio 一次，以触发 schema 部署
• 外部托管的 Studio（Sanity CLI v5.8.0+）：npx sanity deploy --external --schema-required 会注册外部 URL，并在 schema 部署失败时立即报错

知识库模式：创建并构建知识库。 用户在 Context 应用中完成此操作（需要组织管理员或开发者角色）。大致步骤如下：

1. 选择 New knowledge base，并填写 Title 和 Purpose：用一两句话说明服务对象以及它能提供的帮助。明确具体的用途有助于获得更好的构建结果
2. Add source：添加数据集、网站或文件。先从一组范围明确且内容最新的材料开始
3. 选择 Build entries 并等待显示 Entries up to date，然后浏览 Entries 和 Issues

有关来源、问题和保持内容更新的详情，请引导用户参阅创建知识库。

在 Context 应用中创建端点。 用户在 Sanity Dashboard 中完成此操作；需要组织管理员或开发者角色。关联数据集还需要用户在该数据集所属项目中拥有管理员或开发者角色，并且对该数据集拥有不受限制的读取权限。告知用户需要填写以下内容：

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 与 Agent 的其他机密信息一并存储。

验证端点：

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 步：构建 Agent（适配用户的技术栈）

用户已经有 Agent 或 MCP 客户端？ 他们只需使用组织令牌作为 Bearer 令牌，连接到 MCP 端点 URL。工具会自动显示。

从头开始构建？ 帮助用户设置 MCP 连接和大模型集成。无论使用哪种技术栈，都必须向模型提供初始上下文：将其内联到系统提示词中，或通过 initial_context 工具提供（参见 初始上下文）。代码片段和参考实现使用搭配 Anthropic 的 Vercel AI SDK v7，但这一模式适用于任何大模型提供商（OpenAI、本地模型等）。先从基础功能开始，再按需添加高级模式。

遵循 references/connecting-an-agent.md：安装、获取初始上下文、适用于 CLI 和 API 的请求／响应模式、用于聊天 UI 的流式路由及其在各框架中的位置、框架注意事项，以及完整 Next.js 参考实现的结构图。

端到端检查： 询问 Agent：“你可以访问哪些内容？”如果已内联初始上下文，Agent 会直接回答，无需调用 initial_context 工具。

系统提示词： 保持简短，并聚焦于行为；shape-your-agent 技能会介绍其中应包含的内容。

第 3 步：对话洞察（可选）

提供洞察功能，由用户决定。 如果不进行跟踪，就很难知道 Agent 是否在帮助用户，或是否在悄无声息地出错。洞察功能会展示用户提出的问题、Agent 遇到困难的地方，以及缺失的内容。它需要一个 Context Editor 令牌和一个定时函数；如果用户暂时不需要，可以跳过。

如果用户需要，请完成以下两部分设置——缺一不可：

1. 遥测 — 在现有的 streamText 调用中添加一个集成（将对话记录存储在组织的 Context 存储中）。记录对话需要 Context Editor 令牌；一个 Editor 令牌即可同时用于 MCP 和洞察功能。
2. 分类 — 部署一个定时函数，使用用户自己的 AI SDK 模型分析对话，并通过 Context API 将判定结果记录回来。

仅设置遥测只会存储原始对话。分类才会提取成功评分、情绪和内容缺口——也就是实际的洞察。请同时完成两项设置。

按照 references/conversation-classification.md 完成设置。 该指南涵盖了从头到尾的两部分设置。对话完成分类后，洞察会显示在 Sanity Dashboard 的 Context 应用中。

第 4 步：调整 Agent（推荐）

生产环境中的 Agent 正常运行后：

1. 使用 dial-your-context 技能调整 Instructions 字段——通过交互式会话共同探索用户的数据集、验证发现，并生成简洁的 Instructions，帮助生产环境中的 Agent 了解仅凭架构不易看出的信息：反直觉的字段名称、二级引用链、数据质量问题、必需的筛选条件和查询模式。该技能还可以帮助配置端点的 GROQ 筛选条件，以限定生产环境中的 Agent 可见的内容。用户将结果粘贴到 Context 应用中的端点 Instructions 和 GROQ 筛选条件字段。

   知识库模式： dial-your-context 面向 GROQ 模式。对于知识库，可在 Context 应用中通过解决问题和修复来源来改进答案；参见 解决知识库问题。

2. 调整系统提示词（可选）：使用 shape-your-agent 技能——如果用户可以控制生产环境中 Agent 的系统提示词，此技能可帮助定义语气、边界和防护措施。如果用户无法控制系统提示词，则跳过此项。

最佳实践

• 内容筛选器：使用端点的 GROQ 筛选器限定生产环境 Agent 可见的内容范围——先从宽泛的范围开始，再根据实际需求缩小范围。筛选器是 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 的 Agent 无需安装该软件包。使用时，请使用最新版本——运行 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，Agent 代码能够读取该令牌，令牌通过 Authorization: Bearer <token> 发送，并且 URL 中的组织 ID 正确。

“404”：找不到 MCP 端点

HTTP 404，伴随 JSON-RPC -32001 和消息“MCP endpoint not found: ”。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 模式，请检查端点是否至少选择了一个知识库。

“No documents found” / 空结果

请在 Context 应用中检查端点的 GROQ 过滤器：

• GROQ 过滤器是否正确？
• 文档类型的拼写是否正确？
• 是否有与过滤器匹配的已发布文档？默认情况下，端点读取 published 视图

过滤器未匹配到任何内容，看起来就像连接已损坏，因此请先检查过滤器，再排查连接。如果有多个 Studio 工作区指向同一个数据集，端点会使用第一个工作区，除非设置了 ?workspace=<name>；否则可能会使用错误的架构。

工具未显示

1. 检查 mcpClient.tools() 是否返回工具（记录其结果）
2. 确保 MCP URL 正确：组织 ID 和端点名称
3. 如果 URL 包含 tools 参数，该参数会缩小工具列表范围；移除它即可查看所有工具