Agent Actions

Generate cheat sheet

Common patterns and best practices for using Generate

Generate offers an interface to enhance Sanity documents with the use of large language models (LLMs). This document showcases a collection of common patterns and concepts.

Prerequisites:

  • Complete the Generate quick start.
  • @sanity/client v7.1.0 or higher 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:

// client.ts
import { createClient } from "@sanity/client";
export const client = createClient({
  projectId: '<project-id>',
  dataset: '<dataset-name>',
  useCdn: 'true',
  apiVersion: 'vX',
  token: '<read-write-token>'
})

Then, import client before using the examples below.

Common patterns

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

Agent Actions patterns

Explore common patterns across all Agent Actions

Create multi-stage instructions

You can receive better results from the LLM by running multiple passes, or stages, of instructions. This is useful when you have large amounts of context or reference data.

This approach is also valuable for using generated content as the basis for new instructions. Generate only knows about the instruction you provide and a snapshot of any document content you pass in as instructionParams. It does not reliably know what it placed in adjacent fields during the same instruction.

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: "sanity.workspace.schema.default",
  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: "sanity.workspace.schema.default",
  documentId: _id,
  instruction: `Create a poster for the movie based on the $document.`,
  path: "poster",
  instructionParams: {
    document: { type: "document" },
  },
});

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

Create release versions for AI changes

You can combine Generate with Content Releases to power a safer, supervised content pipeline. This example will:

  • Read details about a published document and rewrite the title based on the instructions.
  • Take that document and use the Actions API to create a new version document attached to an existing release, leaving the original published version unchanged.
const releaseId = "<release-id>";
const documentId = "<published-document-id>";

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

// Create an instruction to rewrite the title
const result = await client.agent.action.generate({
  schemaId: "sanity.workspace.schema.default", // replace with 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 to create a new version.
await client.request({
  method: "POST",
  uri: `/data/actions/${client.config().dataset}/`,
  body: {
    actions: [
      {
        actionType: "sanity.action.document.version.create",
        publishedId: documentId,
        document: {
          ...result,
          _id: versionId,
        },
      },
    ],
  },
});

Protip

You can use this same approach to create a draft document. The sanity.action.document.version.create action works the same for drafts, with one minor modification.

Instead of versions.releaseId.documentId, set a draft Id with drafts.documentId. For example, drafts.movie12345.

Previous

Quick start

Next

Quick start

Was this page helpful?