# New Agent Actions, updates to mutation defaults, and enhanced image generation and transformation features

**Version:** v7.4.0

**Published:** May 28, 2025

## Highlights

### Agent Actions no longer mutate published documents by default

> [!WARNING]
> 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](https://www.sanity.io/docs/agent-actions/patch-quickstart).

```
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](https://www.sanity.io/docs/agent-actions/prompt-quickstart).

```
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](https://www.sanity.io/docs/agent-actions/agent-actions-image-generation) for more details.

## Bugfixes

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