Enable dates and datetimes in Agent Actions

Configure instructions to write to date and datetime fields.

Agent Actions can interact with date and datetime field types by adding time and location details to each request.

Prerequisites:

• Complete any of the Agent Actions quick start guides, or be familiar with making requests through the actions.
• API version vX and @sanity/client version 7.1.0 or higher.

To support natural language and relative time, the instruction needs to know the localized language you're using and the timezone it should use as a baseline for phrases like "tomorrow" or "three hours from now."

The following code:

• Sets up a client.
• Creates an instruction to change a datetime field at the path publishedAt and configures the locale settings.

This example uses Generate, but the same localSettings apply to all Agent Actions.

import { createClient } from "@sanity/client";

const client = createClient({
  projectId: "<project-id>",
  dataset: "<dataset-name>", // such as 'production'
  apiVersion: "vX",
  token: "<editor-token>",
});

await client.agent.action.generate({
  schemaId: "<schema-id>",
  documentId: "<document-id>",
  instruction: `
    Set the publishedAt date to the thirty first of October, 2025 at midnight.
  `,
  target: { path: "publishedAt" },
  localeSettings: {
    locale: "en-US",
    timeZone: "America/Los_Angeles",
  },
});

The localeSettings requires:

• locale: A BCP 47 locale identifier, such as en-US or no-NO. Learn more about the specification.
• timeZone: A IANA time zone identifier, such as America/New_York or Europe/Berlin. Learn more about the supported values.

These settings enable the Agent Actions to understand the intended meaning behind natural language times and dates, and then apply them to date and datetime fields in a predictable way.