Enable references in Generate

Use references in Generate to populate fields and connect documents based on your instructions.

Agent Actions can populate reference fields with the help of the AI Assist Studio plugin and the Embeddings Index API. This guide shows you how to enable related content references for instructions.

• Complete the Generate quick start.
• An embeddings index connected to your project and dataset. Follow the setup process if you haven't done so already. You can also use the Studio plugin.
• Access to your studio codebase.
• For the optional AI Assist plugin: a project on the Growth plan or higher, and Sanity Studio v5 or later.

If you've already installed the AI Assist plugin in your studio, you can skip the plugin installation step.

While Agent Actions don't require the AI Assist plugin, the plugin provides type completion and enables presence in your studio when Agent Actions are actively mutating a document or field.

npm install sanity@latest @sanity/assist@latest

pnpm add sanity@latest @sanity/assist@latest

yarn add sanity@latest @sanity/assist@latest

bun add sanity@latest @sanity/assist@latest

Next, import and add the plugin to your studio config's plugins array.

import { defineConfig } from 'sanity'
import { assist } from '@sanity/assist'
/* other imports */

export default defineConfig({
  /* other config */
  plugins: [
    /* other plugins */
    assist(),
  ]
})

Generate needs to know which index to use when making connections. Add the options.aiAssist.embeddingsIndex option to any references that use the index. In our movie schema example, we've created an index called "people" that targets all documents of _type == "person".

defineField({
  name: 'person',
  title: 'Person',
  type: 'reference',
  to: [{type: 'person'}],
  options: {
    aiAssist: {
      embeddingsIndex: 'people',
    }
  }
}),

This configuration tells AI Assist and Generate to use the people index for this person reference.

Agent Actions read the schema you've deployed, not the schema files in your studio codebase. After you add the embeddingsIndex option, deploy your schema again so Generate can use the index. If you host your studio on Sanity, run npx sanity@latest deploy. Otherwise, deploy the schema on its own:

npx sanity@latest schemas deploy

pnpm dlx sanity@latest schemas deploy

yarn dlx sanity@latest schemas deploy

bunx sanity@latest schemas deploy

With the updated schema deployed, you're set to use references with Generate.

Agent Actions can often intuit the needs of your instruction based on your schema, but it's also helpful to be explicit. These examples use Generate, but other actions support the same concept. First, set up your client if you haven't already.

import { createClient } from "@sanity/client";

export const client = createClient({
  projectId: "YOUR_PROJECT_ID",
  dataset: "production",
  apiVersion: "vX",
  token: process.env.SANITY_API_TOKEN,
});

Next, create an instruction.

// ...client setup

await client.agent.action.generate({
  schemaId: "YOUR_SCHEMA_ID",
  targetDocument: {operation: 'create', _type: 'movie'},
  instruction: `
    Come up with an idea for a movie. 
    Give it a title and overview.
    Select cast members to be involved in the movie as the cast. Give their characters names that fit the theme.
    Assign crew members to work on the movie.
  `,
});

This example creates a detailed instruction that explicitly lists the steps you want Generate to take. Notice that it doesn't use a GROQ query to inject information about the person type. Because Generate knows about your schema and has access to the index, it understands there are references for cast and crew.

If you wanted to be more explicit, perhaps to limit which people it chooses, you could combine this with a GROQ query or other instruction parameters to provide more context.

Give the code, or your modified version, a try. Generate will do its best to match related references based on your instructions. Sometimes, you may need to be more explicit to help it make the best decisions.

If a reference field is still empty after the request finishes, Generate didn't find a close enough match in the index. Generate only references published documents, and it leaves the field empty instead of returning an error. Check that your index includes published documents of the referenced type, then make your instruction more specific.