Using Sanity in Agents

​

Key Concepts

​

Documents and Types

​

Datasets

​

Drafts vs. Published

• Published documents have a plain ID (e.g., abc123)
• Draft documents have the same ID prefixed with drafts. (e.g., drafts.abc123)

​

Working with Portable Text (Rich Text)

​

Providing Rich Text Content

{
  "body": "<h1>Welcome</h1><p>This is a <strong>blog post</strong> with <em>formatting</em>.</p><ul><li>First item</li><li>Second item</li></ul>"
}

{
  "_type": "post",
  "title": "My Post",
  "body": [
    {
      "_type": "block",
      "_key": "abc123",
      "style": "normal",
      "markDefs": [],
      "children": [
        {
          "_type": "span",
          "_key": "def456",
          "marks": [],
          "text": "Hello world"
        }
      ]
    }
  ]
}

​

Mapping Sanity Schemas to Agent Steps

​

Example: Blog Post Schema

// In your Sanity Studio schema
defineType({
  name: 'post',
  title: 'Post',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'slug', type: 'slug' }),
    defineField({ name: 'author', type: 'reference', to: [{ type: 'author' }] }),
    defineField({ name: 'body', type: 'blockContent' }),
    defineField({ name: 'publishedAt', type: 'datetime' }),
    defineField({ name: 'categories', type: 'array', of: [{ type: 'reference', to: [{ type: 'category' }] }] }),
  ],
})

​

Step-by-Step Setup

1. Add a Create Resource step to your Agent and select your connected Sanity project from the Sanity Project dropdown.
2. Select the Dataset from the dropdown (e.g., production).
3. Fill in Document Details with your document fields as JSON. This is where you provide simple values like titles, slugs, references, and categories:
   Copy

   Ask AI

   {
     "_type": "post",
     "title": "My Post Title",
     "slug": {
       "_type": "slug",
       "current": "my-post-title"
     },
     "author": {
       "_type": "reference",
       "_ref": "author-id-123"
     },
     "publishedAt": "2025-01-15T10:30:00Z",
     "categories": [
       {
         "_type": "reference",
         "_ref": "category-id-456"
       }
     ]
   }
   
   To use dynamic values from upstream steps, type / inside the field to open the variable menu and select a variable. It will appear as a pill badge inline with your JSON — for example, you could replace "My Post Title" with a variable from a previous LLM step.
4. Fill in Rich Text Content for any Portable Text fields (like a blog body). Map the field name to an HTML string — Profound converts it to Sanity’s format automatically:
   Copy

   Ask AI

   {
     "body": "<h1>Welcome</h1><p>This is my post content.</p>"
   }
   
   You can also insert a variable here to pass in HTML generated by a previous step. Type / to open the variable menu and select the output from an LLM or other upstream step as the value.
5. Check or uncheck Publish Resource — check it to publish immediately, or leave it unchecked to create a draft for review in Sanity Studio.

​

Field Type Reference

​

Common Workflows

​

Generate and Publish a Blog Post

1. LLM Step — Generate a title, slug, and HTML body from a prompt
2. Create Resource — Create a Sanity post document using the generated content
3. Publish Resource — Publish the draft (or set publish_resource: true in step 2)

​

Update Existing Content

1. Get Resource — Fetch the current document by ID
2. LLM Step — Generate updated content based on the existing document
3. Update Resource — Patch only the fields that changed

​

Content Migration

1. List Resources — Fetch documents from one dataset
2. Loop — Iterate over the list
3. Create Resource — Create each document in a different dataset

​

Draft Review Pipeline

1. Create Resource — Create content as a draft (default behavior)
2. Human Review — Manual review step in Sanity Studio
3. Publish Resource — Publish approved drafts via the Agent

​

Permissions and Roles

​

Troubleshooting

​

Additional Resources

• Sanity Content Lake — Understanding datasets and documents
• Portable Text — Sanity’s rich text format specification
• GROQ Query Language — Querying content in Sanity
• HTTP API Reference — Full Sanity API documentation
• Mutations API — Creating, updating, and deleting documents