Agent Actions introduction

Get to know Agent Actions and how to start using them.

Agent Actions let you programmatically run schema-aware AI instructions to create and modify Sanity documents. You can run instructions from anywhere you can execute code, such as Sanity Functions, custom components, webhook listeners, CI/CD pipelines, and migration scripts.

With Agent Actions, you can:

• Add AI-assisted content suggestions.
• Generate draft documents with new content.
• Generate images based on fields within your document.
• Translate documents automatically or on demand.
• See live AI presence so your editors know when an Agent Action is working on a document.

You can create powerful AI-driven workflows by combining Agent Actions with Functions, Content Releases, the Actions API, and the rest of Content Lake's APIs. Each request with an Agent Action uses AI credits. Learn more about Sanity's AI pricing.

• You need a place to execute code, such as a custom component, cloud functions, a webhook listener, or any service that can run the JavaScript client or initiate HTTP requests.
• Sanity client (@sanity/client) version 7.4.0 or later and API version vX. Generate, Transform, and Translate are available from 7.1.0; Prompt and Patch require 7.4.0.

Install and enable the AI Assist plugin for Sanity Studio to enable presence support. AI Assist is available to projects on the Growth plan and up, and requires Sanity Studio v3.26.0 or later.

Some Agent Actions, like Generate, can create images and connect references. To enable automation for image and reference fields, further setup is required.

Agent Actions all share the same core but are specialized for different uses.

When you want to create brand new content, you want Generate. It excels at creating new content based on the information you pull in from your existing Sanity documents.

Generate runs in mixed operation mode by default: it sets non-array fields, overwriting any existing value, and appends new items to arrays. Set operation on a target to change this — set replaces a field value entirely, append adds to it. When working with arrays, Generate adds new items but will not replace existing items in the array.

• Create full, structured documents in a single command.
• Reference multiple documents to use as the source for new documents.
• Generate images and make reference connections to existing documents.

When you need to modify existing documents, Transform can walk through your document fields and make changes. It keeps the formatting and style, while only making the changes you tell it to make.

Transform only edits existing content—it does not create new fields or add new items to arrays. It modifies what is already present in the document.

• Change a document's tone.
• Rename a product across your entire site.

A specialized version of Transform, Translate is designed with internationalization in mind. It supports both document-level translation and field-level translation. It's a fast way to translate documents into multiple languages.

Need to make prompts to a large language model (LLM) without reaching for another service? Prompt lets you use your content in Sanity to make requests, then process that information however you like.

Agent Actions are schema-aware, which lets them validate and safely modify your documents. Patch uses this same approach with no LLM involved.

Should an action create a new document? Should it edit an existing one? Operations tell each Agent Action how to act on your data.

Agent Actions use the concept of instructions to describe what tasks you want them to perform. These are combined with each action's configuration.

Agent Actions know about your content model, which lets them map content accurately to your documents and fields. However, you must deploy an up-to-date schema version to make this work.

If you're already hosting your studio at Sanity, you're all set. Run sanity deploy from your project to ensure the latest schema is uploaded. If you're hosting your studio elsewhere, you can manually deploy the schema.

Refer to any of the quick start guides for instructions on deploying your schema.

AI Assist is a plugin for Sanity Studio. It lets content editors create AI commands directly in the studio.

Agent Actions let you trigger, or invoke, AI workflows from anywhere you can make an API call or run the Sanity client. They also let you supply additional contextual information beyond what lives in a single Sanity document or field.

You can combine the two by creating custom field actions that invoke Agent Action workflows.

Agent Actions usage is shared across the organization. For details on your plan's limits, see the pricing page.

You can set spending limits and view your remaining budget in your organization's settings in Manage.

• Navigate to Manage, or run sanity manage from the CLI.
• Select your organization.
• Go to Settings > Spending limits.

Agent Actions don't support the File field type.

The following field types are supported, but with limitations:

• Slug: Agent Actions don't perform uniqueness validation to check if the slug conflicts with others.
• URL: Agent Actions only write to this field type if the instruction includes links.

The following types require additional setup:

• Image (See the configuration guide).
• Reference (See the configuration guide. Requires the Embeddings Index API). The Embeddings Index API is deprecated and will be sunset in a future release. There is currently no replacement for using references with Agent Actions.
• Date and Datetime: To enable these fields, use the localeSettings in the request. Learn more in the configuration guide.

Agent Actions don't write to explicitly hidden or readOnly fields. Fields with conditional hidden or readOnly functions are also skipped by default. Opt back in per request with the conditionalPaths parameter. See the common patterns guide for more details.

Agent Actions Generate and Transform can create images, but don't save new images to Media Library.

Agent Actions Generate cannot create annotations, custom marks, or inline blocks in Portable Text fields. It can generate content into existing elements if provided with the full path, but cannot create these elements otherwise.

For a list of third-party sub-processors and the terms of use for Sanity's AI products, see AI terms of use.

Agent Actions requests fail with a status code that tells you which layer rejected them. For the errors you're most likely to hit, including what does and doesn't cause a 401, see Troubleshoot Agent Actions requests.