@sanity/assist

This is a Sanity Studio v3 plugin.

Table of contents

• About Sanity AI Assist
• Installation
• Usage
• Schema configuration
• Notes on writing instructions

About Sanity AI Assist

Attach reusable AI instructions to fields and documents to supercharge your editorial workflow.

You create the instructions, Sanity AI Assist does the rest.

Installation

npm install @sanity/assist

Usage

Note: Before using the plugin, your project must have Sanity AI Assist enabled at the API level.

Contact your Sanity enterprise representative to get started.

Add the plugin

In sanity.config.ts add assist :

import { assist } from '@sanity/assist'

export default defineConfig({
  /* other config */
  plugins: [
    /* other plugins */
    assist()
  ]
})

Enable the API

After adding the plugin, the API needs to be enabled for the project. Your Sanity user needs token creation permissions to do this.

• Start the studio, and visit any document in the Studio.
• You should see a sparkle icon in the document header, near the close document X-button.
• Click the button, then click "Manage instructions"

• "Manage instructions" will open an inspector panel.
• Click “Enable AI assistance” button. This will enable it for the project.

After the previous step succeed, you will find a new API token for your project named “Sanity AI”.

The plugin will now work for any dataset in your project.

Note: You can revoke this token at any time to disable Sanity AI Assist service, at which point a new token has to be generated via the plugin UI for it to work again.

Schema configuration

By default, most* object, array and string types and fields will have AI writing assistance enabled. That means that the assistant is aware that the field exist, and can write to it.

For arrays, an item type is eligible to be created when the assistant adds content to arrays or portable text fields.

Types and fields can be explicitly disable this by setting option.aiWritingAssistance.exclude to true in the schema:

Disable for a type

// this will omit from AI assistance wherever it is used, 
// ie: as field, document, array types
defineType({
	name: 'myType',
  type: 'string',
  options: {
	   aiWritingAssistance: {exclude: true}
	}	
})

Disable for a field

// this omits AI assistance only for the spesific field
defineType({
	name: 'myObject',
  type: 'object',
  fields: [
    defineField({
	     name: 'stringField',
	     type: 'string',
	     options: {
		      aiWritingAssistance: {exclude: true}
		   }	
		})
  ]
})

Disable for an array type

// this omits AI assistance for the spesific array member
// if all types in the of array are excluded, the array type is also considered excluded
defineType({
	name: 'myArray',
  type: 'array',
  of: [
    defineArrayMember({
	     type: 'someType',
	     options: {
		      aiWritingAssistance: {exclude: true}
		   }	
		})
  ]
})

Always disabled / unsupported types

Number fields are not supported, and will not be changed by the assistant.

Objects defined inline in a schema are also not supported. Inline objects are objects with type: 'object''. To add assistance to these, you will have to hoist the type to the top level.

For more on how to hoist a type, see Strict schemas, as done for GraphQL types.

Troubleshooting

For very large schemas, it will be necessary to exclude types from arrays to limit how much of the context window is used for the schema itself, and to ensure that the AI does not get overwhelmed with possibilities.

We recommend excluding any and all types which rarely would benefit from automated workflows. It can also be a good idea to exclude most non-block types from portable-text arrays.

This will ensure that the Sanity Assist output mostly formatted text.

Notes on writing instructions

The assistant knows about the schema. When running instructions at the document level, for instance, you can use field names or titles to nudge to only change certain fields, or create certain types.

For example, the document instruction “Create a description based on title, then add a relevant factbox to body. Do not add anything to any other fields.”, should result in the assistant only changing the description and adding a factbox block to the body portable text field (given that body allows factboxes).

Using firm terms like “Important: ” might sometimes be necessary to force the assistant in a certain direction.

It might be a good idea to tell the assistant to “make a lot of entries” or “describe in detail” or similar, to get more content generated by a single instruction.

For best results in schemas with arrays with a lot of different types, please see troubleshooting above for how best to narrow the scope of what Sanity Assist knows about.

License

MIT © Sanity

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.