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. Without localeSettings, Agent Actions ignore date and datetime fields — the request succeeds and those fields are left unchanged. This guide explains how to configure a request so an instruction can write natural language dates and times to those fields.

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 later.
• Each Agent Actions request consumes 1 AI credit.

To support natural language and relative time, the instruction needs the locale you're writing in and the time zone to use as a baseline. Without both, a phrase like "tomorrow" or "three hours from now" has no fixed reference point.

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 localeSettings apply to Transform and Translate. Patch sets values you supply directly, and Prompt doesn't write to documents, so neither accepts localeSettings:

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

const client = createClient({
  projectId: "YOUR_PROJECT_ID",
  dataset: "production",
  apiVersion: "vX",
  token: process.env.SANITY_API_TOKEN,
});

await client.agent.action.generate({
  schemaId: "YOUR_SCHEMA_ID",
  documentId: "YOUR_DOCUMENT_ID",
  instruction: `
    Set the publishedAt date to tomorrow at 9am.
  `,
  target: { path: "publishedAt" },
  localeSettings: {
    locale: "en-US",
    timeZone: "America/Los_Angeles",
  },
});

The localeSettings object requires two properties:

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

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