JavaScript Client v7.4.0: New Agent Actions, updates to mutation defaults, and enhanced image generation and transformation features

Highlights

Agent Actions no longer mutate published documents by default

Breaking change

As of this release, Agent Actions will never write to published documents by default. Use forcePublishedWrite: true in the request to write to published documents.

Agent Actions require apiVersion: 'vX'. Therefore, this is new behavior will apply to all users of agent actions, regardless of client version. Using this release (or later) will be required to opt out of the new behavior using forcePublishedWrite: true.

As of this going out, by default:

Agent Actions will not mutate a published document. It will use a drafts id if a published id is provided

Operations on drafts will get initial state from published doc if no draft exists.

Callers should check the _id in the response as needed; when a publishedId is provided a drafts.publishedId will be returned.

To opt out of the default behavior, pass forcePublishedWrite: true

Exceptions:

Documents with liveEdit: true in the schema definition will behave as if forcePublishedWrite: true, and also will not accept drafts IDs in requests.

Versioned Ids on the form "versions.release-id.document-id" will always behave as if forcePublishedWrite: true, and will not consider draft nor published state; only the version itself.

New Agent Actions

Patch: a schema aware patch API

The client.patch and client.transaction API are not schema aware. These allows patching documents any way you want, but the operations will not fail if they deviate from the document schema.

To ensure schema-compliant operation, client.agent.action.patch is available. It will ensure that provided paths and values adhere to the document schema, ensure no duplicate keys are inserted, and merge object values so set operations don't accidentally remove existing values. Learn more in the quick start.

await client.agent.action.patch({
schemaId: 'sanity.workspace.schema.production',
documentId: 'documentId',
target: {
path: ['metadata', 'title'], // path to metadata.title
operation: 'set',
value: 'New title'
}
});

Prompt: Make LLM requests without mutating documents

agent.action.prompt is an API for sending instructions to the LLM and receiving text or json back. Useful if you want to use the same Sanity client and feed in your content, but don't want to incorporate a third-party library or API key. Learn more in the quick start.

await client.agent.action.prompt({
instruction: `Give me some ideas for a blog post
about using AI with structured content.`
});

Generate and Transform for images

Generating images

Generate can generate images the same way as AI Assist, for images that have been configured using AI Assist schema options.

To generate images without changing the schema, you can now directly target an image asset path.

For example, all the following will generate an image into the provided asset:

target: {path: ['image', 'asset'] }

target: {path: 'image', include: ['asset'] }

Image generation can be combined with regular content targets:

target: [{path: ['image', 'asset'] }, {include: ['title', 'description']}]

As Generate happens in a single LLM pass, the image will be contextually related to other generated content.

Transforming images

To transform an existing image, directly target an image asset path with Transform.

For example, all the following will transform the image into the provided asset:

target: {path: ['image', 'asset'] }

target: {path: 'image', include: ['asset'] }

Image transform can be combined with regular content targets:

target: [{path: ['image', 'asset'] }, {include: ['title', 'description']}]

Image transform can have per-path instructions, just like any other target paths:

target: [{path: ['image', 'asset'], instruction: 'Make the sky blue' }

See the updated image generation documentation for more details.

Bugfixes

GROQ errors will now provide more context when queries fail due to syntax problems.