Generate common patterns

Common patterns and best practices for using Generate

Generate offers an interface to enhance Sanity documents using large language models (LLMs). This page collects common patterns and concepts.

Prerequisites:

• Complete the Generate quick start.
• @sanity/client v7.2.0 or later and an environment to run client requests.
• API version vX or later for any requests using Generate.

Many examples in this document use @sanity/client and expect that you've installed and configured it for your project. If your client is named something other than client, update the code examples accordingly.

Here's an example of the client implementation:

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

export const client = createClient({
  projectId: '<your-project-id>',
  dataset: 'production',
  useCdn: false,
  apiVersion: 'vX',
  token: process.env.SANITY_API_TOKEN
})

Then, import client before running any example on this page.

The patterns in this guide are unique to Generate, but there are more patterns shared across all Agent Actions.

A single instruction is often fine for smaller tasks like updating an individual field. However, splitting instructions into multiple steps or stages for more significant tasks like writing complete documents with complex schemas returns better results. Each Agent Actions request consumes 1 AI credit, so splitting one task into several instructions multiplies the cost — the following example makes three requests.

One way to improve the LLM's success rate is to structure instructions the way a person would work through the task. For example:

• Make a skeleton or outline by populating simple, foundational fields like title, description, and categories or topics.
• Run instructions for more complex areas, like an article's main content field, individually by passing in the results of step 1 as field parameters.
• Run any summarization tasks at the end for content like SEO fields, social copy, or connecting related content.

This example creates a document with an instruction and then uses the generated content to influence future instructions:

const customTopic =
  "A multi-generational epic, but all the characters are cats.";

const { _id } = await client.agent.action.generate({
  schemaId: "YOUR_SCHEMA_ID",
  targetDocument: {operation: 'create', _type: 'movie'},
  instruction: `
    Come up with a movie idea.
    Use the information in $topic as the basis for the movie.`,
  instructionParams: {
    topic: { type: "constant", value: customTopic },
  },
  target: {
    include: ["title", "overview"],
  },
});

await client.agent.action.generate({
  schemaId: "YOUR_SCHEMA_ID",
  documentId: _id,
  instruction: `Create a poster for the movie based on the $document.`,
  target: { path: "poster" },
  instructionParams: {
    document: { type: "document" },
  },
});

await client.agent.action.generate({
  schemaId: "YOUR_SCHEMA_ID",
  documentId: _id,
  instruction: `Translate the $overview into Japanese.`,
  target: { path: "overviewJPN" },
  instructionParams: {
    overview: { type: "field", path: "overview" },
  },
});

You can combine Generate with Content Releases to power a safer, supervised content pipeline. Content Releases is available on certain Enterprise plans. This example:

• Reads the document's draft, falling back to the published version if no draft exists, and rewrites the title based on the instruction.
• Takes that document and uses the Actions API to create a new version document attached to an existing release, leaving the original published version unchanged. Version actions require API version v2025-02-19 or later.

const releaseId = "YOUR_RELEASE_ID";
const documentId = "YOUR_DOCUMENT_ID";

// Build the version ID by combining the release ID and the document ID.
const versionId = `versions.${releaseId}.${documentId}`;

// Create an instruction to rewrite the title
const result = await client.agent.action.generate({
  schemaId: "YOUR_SCHEMA_ID",
  documentId: documentId,
  noWrite: true, // only write the changed document to the `result` variable
  instruction: `
    Re-imagine the title so that it is more engaging and interesting.
    Use the information in $document to help you come up with a new title.
  `,
  instructionParams: {
    document: {
      type: "document",
    },
  },
  target: {
    path: "title",
  }
});

// Call the Actions API with the client to create a new version.
await client.action(
  {
    actionType: 'sanity.action.document.version.create',
    publishedId: documentId,
    document: {
      ...result,
      _id: versionId,
    }
  }
)