Transform quick start

Get started with Transform by writing your first instructions to modify documents.

Transform is part of Agent Actions and lets you programmatically run schema-aware AI transformations on Sanity documents. You can run instructions from anywhere you can execute code, such as Sanity Functions, custom components, webhook listeners, CI/CD pipelines, migration scripts, and more.

In this guide, you'll use Transform to run a find/replace style instruction on content across multiple fields in a document. You'll use @sanity/client to create the instructions (you can also make requests using the HTTP API directly).

Prerequisites:

• @sanity/client v7.1.0 or later and an environment to run client requests.
• API version vX is required for any requests to the Agent Actions APIs.
• Optional: In Node.js v23.6 and above, you can run the TypeScript examples in this guide without additional servers or build processes. Alternatively, you can use earlier versions with an experimental flag. You can also convert the examples to JavaScript.
• sanity CLI v3.88.0 or later.
• A Sanity project for testing. The examples in this guide use details from the sample "Movies" studio schema that you can select when initializing a new project.
  • A read/write API token to authenticate requests.
  • A valid projectId and dataset name.

Transform requires an uploaded schema. If you've deployed recently, you can check for a list of uploaded schemas by running the schemas list command. If you don't see a schema or want to deploy the latest version, deploy the schema:

npx sanity@latest schemas list

npx sanity@latest deploy

npx sanity@latest schemas deploy

Copy the schema ID, which you'll need for making Agent Action requests.

Learn more about schema deployment.

Import and configure @sanity/client with the projectId, dataset, API token, and an apiVersion of vX:

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

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

If you're already using the client elsewhere in an application, you can reuse its base configuration. To adjust the token, the API version, or both, use the withConfig method to create a new client based on your existing one. For example:

// ...
const transformClient = client.withConfig({
  token: process.env.SANITY_API_TOKEN,
})

Transform uses the concept of an instruction. This is where you tell Transform what to do with the content in a document. In the simplest form, transform takes the following settings:

• schemaId: The ID of your schema.
• documentId: The documentId defines both the source and the target document. This lets you run the transformation in-place. You can provide a published ID, draft ID, or a version ID.
• instruction: The instruction is where you tell the system how to act.

In this example, you create an instruction that changes the term "Alien" or "Aliens" in a movie document to "lifeform from outer space" and "lifeforms from outer space".

Update the code to include the following instruction, and change the document ID to a valid ID in your project, and the instruction to one that matches your content:

await client.agent.action.transform({
  // Replace with your schema ID
  schemaId: "YOUR_SCHEMA_ID",

  // Tell the client the ID of the document to transform.
  documentId: "YOUR_DOCUMENT_ID",

  // Provide an instruction, or prompt.
  instruction: "Change all instances of 'Alien' to 'lifeform from outer space'. Match the case of the existing text.",
});

This code reads each field in the document and runs the instruction against them.

Run the code to see Transform edit the document and update the content. In this example, it updates the movie's title and parts of the description.

By default, Transform never writes to a published document. If you pass a published document ID, it edits the existing draft, or creates one from the published document if no draft exists. To write to the published document, add forcePublishedWrite: true.

Transform can also create new documents based on the content in the source. If you want to create new documents from scratch, use Generate instead.

In this step, modify the transform call in instruction.ts so it creates a new document from the original as its source. This version also passes instruction parameters.

• Add targetDocument: This takes an operation type, create, and optionally an ID.
• Add instructionParams: The parameters can have any $key name you like. This example uses the field and constant parameter types. The field type targets a specific field in the source document, which, in this example, is the title field. The constant type has a shorthand: assign a plain string.
• Update the instruction: Include the newly defined parameters, and prefix them with $. In the example, these are $title and $new.
• Add target paths (optional): This example also adds explicit targets. Instead of affecting the whole document, only the paths set in target change.

const docId = "YOUR_DOCUMENT_ID";
await client.agent.action.transform({
  schemaId: "YOUR_SCHEMA_ID",
  // documentId is equivalent to targetDocument: {operation: 'edit', _id: docId }
  documentId: docId,
  targetDocument: {
    operation: 'create'
  },
  instruction: "Replace every instance of $title with $new. Match the case of the existing text.",
  instructionParams: {
    title: {
      type: "field",
      path: "title",
    },
    new: "lifeforms from outer space"
  },
  target: [
    { path: ['title'] },
    { path: ['overview'] },
  ]
});

Field-type instruction parameters expect a path leading to fields in the document. In this case, it uses the title field to read the title.

Another approach is to use a GROQ-type query and capture the whole or parts of other documents as context:

await client.agent.action.transform({
  // ...
  instructionParams: {
    title: {
      type: "groq",
      query: '*[_id == $id].title',
      params: { id: 'SOURCE_DOCUMENT_ID' },
    },
  },
  // ...
});

GROQ-type instruction parameters take a GROQ query and pass the result to the parameter. In this case, it passes the title of another movie document in your dataset.

target lets you explicitly tell the instruction which fields to write to, and it can take field-level instruction requests. For more target examples, see the Transform common patterns guide.

Run the example to see a new draft populate for your document.

These examples run once, but you can loop over multiple documents, build multi-step workflows, custom components, and much more. These resources provide additional examples and details.