Operations
Use the `targetDocument` property to control how Agent Actions create or edit documents.
Agent Actions use the targetDocument property to establish how they write to your dataset.
Generate and Patch support initial values
The generate and patch actions also accept an initialValues property on create, createOrReplace, and createIfNotExists targets. With it, you can set initial values similar to how you would with initial values templates. See the Generate examples under the create and createOrReplace operations.
Default write behavior for Agent Actions
By default, Agent Actions never mutate a published document. Whenever you supply a published ID, the action creates a draft first before applying any changes. If a draft already exists, the action uses the existing draft as the source.
To change this behavior, you can supply forcePublishedWrite: true to the action request. For example:
await client.agent.action.transform({
schemaId: 'your-schema-id',
documentId: 'publishedId',
targetDocument: {
operation: 'edit',
_id: 'publishedId'
},
forcePublishedWrite: true,
instruction: 'Replace "Create" with "Canvas"',
})Documents that use liveEdit: true in their schema are treated as forcePublishedWrite: true by default.
For content release version documents, the operations only create version documents when a version ID is paired with an operation that creates a new document.
Check the returned document ID
Check the returned _id of the response to confirm whether the action wrote to a draft, a published document, or a version. See @sanity/id-utils for helpers that classify document IDs.
targetDocument operation types
This is targetDocument.operation, which selects how the document is written. It is separate from target.operation, which selects how a field value is written.
edit operation
Requires an _id for an existing document. This is the verbose version of omitting targetDocument and only relying on documentId. Each action accepts edit as follows:
await client.agent.action.transform({
schemaId: 'your-schema-id',
documentId: 'drafts.id',
targetDocument: {
operation: 'edit',
_id: 'drafts.id'
},
instruction: 'Replace "Create" with "Canvas"',
})await client.agent.action.generate({
schemaId: 'your-schema-id',
// In generate, `edit` is equivalent to using `documentId`
// without a targetDocument.
targetDocument: {
operation: 'edit',
_id: 'drafts.id',
},
instruction: 'Create a blog post about Sanity, the Content Operating System',
})await client.agent.action.translate({
schemaId: 'your-schema-id',
documentId: 'fromLanguageDoc.id',
targetDocument: {
operation: 'edit',
_id: 'drafts.id'
},
fromLanguage: { id: 'en-GB', title: 'English' },
toLanguage: { id: 'nb-NO', title: 'Norwegian Bokmål' },
})await client.agent.action.patch({
schemaId: 'sanity.workspace.schema.production',
targetDocument: {
operation: 'edit',
_id: 'documentId'
},
target: {path: 'title', operation: 'set', value: 'New title'}
})create operation
The _id is optional. If omitted, a draft document is created. You can provide a valid version ID as the _id to create a release version of a document. For Generate and Patch, targetDocument also requires _type, the document type to create. Transform and Translate take the type from the source document. Each action accepts create as follows:
await client.agent.action.transform({
schemaId: 'your-schema-id',
documentId: 'document-id',
targetDocument: {
operation: 'create',
_id: 'new-document-id' // optional
},
instruction: 'Replace "Create" with "Canvas"',
})await client.agent.action.generate({
schemaId: 'your-schema-id',
targetDocument: {
operation: 'create',
_type: 'post',
_id: 'DOCUMENT_ID', // optional
// Use initialValues to set fields when the document is created.
initialValues: {
author: {
_type: 'reference',
_ref: 'AUTHOR_REFERENCE_ID'
}
}
},
instruction: 'Create a blog post about Sanity, the Content Operating System',
})await client.agent.action.translate({
schemaId: 'your-schema-id',
documentId: 'fromLanguageDoc.id',
targetDocument: {
operation: 'create',
_id: 'toLanguage.id' // optional
},
fromLanguage: { id: 'en-GB', title: 'English' },
toLanguage: { id: 'nb-NO', title: 'Norwegian Bokmål' },
})await client.agent.action.patch({
schemaId: 'sanity.workspace.schema.production',
targetDocument: {
operation: 'create',
_type: 'DOCUMENT_TYPE',
_id: 'documentId'
},
target: {path: 'title', operation: 'set', value: 'New title'}
})createOrReplace operation
If you provide an existing _id, the new document overrides it. If the provided _id doesn't exist, the action creates a new document with that ID. Each action accepts createOrReplace as follows:
await client.agent.action.transform({
schemaId: 'your-schema-id',
documentId: 'document-id',
targetDocument: {
operation: 'createOrReplace',
_id: 'new-document-id'
},
instruction: 'Replace "Create" with "Canvas"',
})await client.agent.action.generate({
schemaId: 'your-schema-id',
targetDocument: {
operation: 'createOrReplace',
_type: 'post',
_id: 'DOCUMENT_ID', // Replaces the document if the ID exists; otherwise creates it.
// Optional: Use initialValues to set fields when the document is created.
initialValues: {
author: {
_type: 'reference',
_ref: 'AUTHOR_REFERENCE_ID'
}
}
},
instruction: 'Create a blog post about Sanity, the Content Operating System',
})await client.agent.action.translate({
schemaId: 'your-schema-id',
documentId: 'fromLanguageDoc.id',
targetDocument: {
operation: 'createOrReplace',
_id: 'toLanguage.id'
},
fromLanguage: { id: 'en-GB', title: 'English' },
toLanguage: { id: 'nb-NO', title: 'Norwegian Bokmål' },
})await client.agent.action.patch({
schemaId: 'sanity.workspace.schema.production',
targetDocument: {
operation: 'createOrReplace',
_type: 'DOCUMENT_TYPE',
_id: 'documentId'
},
target: {path: 'title', operation: 'set', value: 'New title'}
})createIfNotExists operation
If the provided _id does not exist, a document is created using the documentId as the source. If it does exist, the action uses the provided _id document as the source. Each action accepts createIfNotExists as follows:
await client.agent.action.transform({
schemaId: 'your-schema-id',
documentId: 'document-id',
targetDocument: {
operation: 'createIfNotExists',
_id: 'new-document-id'
},
instruction: 'Replace "Create" with "Canvas"',
})await client.agent.action.generate({
schemaId: 'your-schema-id',
targetDocument: {
operation: 'createIfNotExists',
_type: 'post',
_id: 'DOCUMENT_ID', // if the ID doesn't exist, a new document is created with the ID.
// Optional: Use initialValues to set fields when the document is created.
initialValues: {
author: {
_type: 'reference',
_ref: 'AUTHOR_REFERENCE_ID'
}
}
},
instruction: 'Create a blog post about Sanity, the Content Operating System',
})await client.agent.action.translate({
schemaId: 'your-schema-id',
documentId: 'fromLanguageDoc.id',
targetDocument: {
operation: 'createIfNotExists',
_id: 'toLanguage.id'
},
fromLanguage: { id: 'en-GB', title: 'English' },
toLanguage: { id: 'nb-NO', title: 'Norwegian Bokmål' },
})await client.agent.action.patch({
schemaId: 'sanity.workspace.schema.production',
targetDocument: {
operation: 'createIfNotExists',
_type: 'DOCUMENT_TYPE',
_id: 'documentId'
},
target: {path: 'title', operation: 'set', value: 'New title'}
})