Transform common patterns

Common patterns and techniques for using Agent Actions Transform.

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

Prerequisites:

• A completed Transform quick start.
• @sanity/client v7.5.0 or later and an environment to run client requests.
• API version vX or later for any requests using Transform.

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 using the examples on this page.

Perform in-place edits on a document. This does not create a new document. By default, Transform never writes to a published document. If you provide a published documentId, the action edits the existing draft, or creates one from the published document if no draft exists. To write directly to the published document, add forcePublishedWrite: true.

await client.agent.action.transform({
  schemaId: 'YOUR_SCHEMA_ID',
  documentId: 'YOUR_DOCUMENT_ID',
  instruction: 'Replace "Create" with "Canvas"',
})

Perform an in-place edit on only part of a document.

await client.agent.action.transform({
  schemaId: 'YOUR_SCHEMA_ID',
  documentId: 'YOUR_DOCUMENT_ID',
  instruction: 'Replace "Create" with "Canvas"',
  target: {path: ['body']} // only transforms body (and any sub-fields/items)
})

This instruction pulls one parameter from a GROQ query, and another from a field, year, in the source document and creates a new draft with the changes.

await client.agent.action.transform({
  schemaId: 'YOUR_SCHEMA_ID',
  documentId: 'YOUR_DOCUMENT_ID',
  targetDocument: {
    operation: 'create',
  },
  instruction: 'Add $fieldValue to every instance of $groqTitle',
  instructionParams: {
    groqTitle: {
      type: 'groq',
      query: '*[_id==$id].title',
      params: {
        id: 'abc123'
      }
    },
    fieldValue: {
      type: 'field',
      path: 'year'
    }
  }
})

This transformation has a top-level instruction, but sets an individual instruction for the title field using target.

await client.agent.action.transform({
  schemaId: 'YOUR_SCHEMA_ID',
  documentId: 'YOUR_DOCUMENT_ID',
  targetDocument: {
    operation: 'create',
  },
  instruction: 'Replace "$old" with "$new"',
  instructionParams: {
    new: 'lifeform from another planet',
    old: 'alien'
  },
  target: [
    {
      path: ['title'],
      instruction: 'Replace "$old" with "$new". Use title-case.'
    },
    { path: 'body' } // anything in or below 'body' uses the default instruction.
  ]
})

Learn more about targeting individual fields in the Targets and paths documentation.

Transform's image-description operation type describes the contents of an image asset in the field you target.

This example creates a draft of the document defined in documentId, then describes the image asset adjacent to the ['image', 'alt'] field.

await client.agent.action.transform({
  schemaId: 'YOUR_SCHEMA_ID',
  documentId: 'YOUR_DOCUMENT_ID',
  instruction: 'Describe the image in one to two sentences.',
  target: [{
    path: ['image', 'alt'],
    operation: {
      type: 'image-description'
    }
  }]
});

Learn more about Transform's image-description operation in the Targets and paths documentation.

Transform can change images. Describe the instruction and target the asset itself. For example:

await client.agent.action.transform({
  schemaId: 'YOUR_SCHEMA_ID',
  documentId: 'YOUR_DOCUMENT_ID',
  instruction: 'Add cats to this image.',
  target: {
    path: ['mainImage', 'asset'],
  }
});

Learn more about target in the common Agent Actions patterns guide.