Function useAgentPatch

useAgentPatch(
    resourceHandle?: ResourceHandle<string, string>,
): (
    options: PatchDocument,
) => Promise<
    { [key: string]: any } & { _id: string } & { [key: string]: any } & {
        _type: string;
    } & Record<string, any>,
>

Alpha

Schema-aware patching with Sanity Agent Actions.

Parameters

OptionalresourceHandle: ResourceHandle<string, string>

Returns (
    options: PatchDocument,
) => Promise<
    { [key: string]: any } & { _id: string } & { [key: string]: any } & {
        _type: string;
    } & Record<string, any>,
>

A stable callback that triggers the action and resolves a Promise with the patch result.

Remarks

This hook provides a stable callback to apply schema-validated patches to documents. Unlike useEditDocument, this uses the Agent Actions API which provides additional schema validation and safe merging capabilities.

Features:

Validates provided paths/values against the document schema and merges object values safely.
Prevents duplicate keys and supports array appends (including after a specific keyed item).
Accepts documentId or targetDocument (mutually exclusive).
Requires schemaId (e.g., '_.schemas.default') and target to specify patch operations.
Optional async, noWrite, conditionalPaths.

Each entry in target specifies a path, an operation ('set', 'append', 'mixed', or 'unset'), and a value (required for all operations except 'unset').

Example: Basic field update

import {useAgentPatch} from '@sanity/sdk-react'

function UpdateTitle({documentId}: {documentId: string}) {
  const patch = useAgentPatch()

  const handleUpdate = async () => {
    const result = await patch({
      documentId,
      schemaId: '_.schemas.default',
      target: [
        {
          path: 'title',
          operation: 'set',
          value: 'Updated Title',
        },
        {
          path: 'lastModified',
          operation: 'set',
          value: new Date().toISOString(),
        },
      ],
    })
    console.log('Patch result:', result)
  }

  return <button onClick={handleUpdate}>Update Title</button>
}

Example: Append items to an array

import {useAgentPatch} from '@sanity/sdk-react'

function AddTag({documentId}: {documentId: string}) {
  const patch = useAgentPatch()

  const handleAddTag = async (newTag: string) => {
    await patch({
      documentId,
      schemaId: '_.schemas.default',
      target: {
        path: 'tags',
        operation: 'append',
        value: [newTag],
      },
    })
  }

  return (
    <button onClick={() => handleAddTag('featured')}>
      Add Featured Tag
    </button>
  )
}

Example: Insert array item after a specific key

import {useAgentPatch} from '@sanity/sdk-react'

function InsertContentBlock({
  documentId,
  afterKey,
}: {
  documentId: string
  afterKey: string
}) {
  const patch = useAgentPatch()

  const handleInsert = async () => {
    await patch({
      documentId,
      schemaId: '_.schemas.default',
      target: {
        path: ['content', {_key: afterKey}],
        operation: 'append',
        value: [{_type: 'block', text: 'New paragraph inserted here.'}],
      },
    })
  }

  return <button onClick={handleInsert}>Insert Block</button>
}

Example: Create a new document with targetDocument

import {useAgentPatch} from '@sanity/sdk-react'

function CreateProduct() {
  const patch = useAgentPatch()

  const handleCreate = async () => {
    const result = await patch({
      targetDocument: {
        operation: 'create',
        _type: 'product',
      },
      schemaId: '_.schemas.default',
      target: [
        {
          path: 'title',
          operation: 'set',
          value: 'New Product',
        },
        {
          path: 'price',
          operation: 'set',
          value: 29.99,
        },
        {
          path: 'inStock',
          operation: 'set',
          value: true,
        },
      ],
    })
    console.log('Created document:', result.documentId)
  }

  return <button onClick={handleCreate}>Create Product</button>
}