> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uso de Sanity en Agents

Después de conectar tu cuenta de Sanity, las siguientes acciones quedan disponibles como pasos de Agent. Cada paso requiere que selecciones un **Sanity Project** conectado en un menú desplegable.

<Tabs>
  <Tab title="Crear recurso" icon="file-plus">
    #### **Create Resource**

    Crea un nuevo documento en tu dataset de Sanity.

    **Entradas obligatorias**

    * **Sanity Project** — Selecciona el proyecto de Sanity que conectaste en Profound
    * **Dataset** — Selecciona el dataset (por ejemplo, `production`)
    * **Document Details** — Un objeto JSON con los campos de tu documento (debe incluir `_type`)

    **Entradas opcionales**

    * **Rich Text Content** — Un objeto JSON que asigna nombres de campo a cadenas HTML. Profound convierte automáticamente el HTML al formato Portable Text de Sanity
    * **Publish Resource** — Márcalo para publicar de inmediato, o déjalo sin marcar para crear un borrador

    De forma predeterminada, los nuevos documentos se crean como **borradores**. Profound genera automáticamente por ti un ID de borrador con el prefijo `drafts.`. Activa **Publish Resource** para que el documento se publique de inmediato.

    <Callout icon="lightbulb" color="#376CFF">
      **Consejo:** Deja **Publish Resource** sin marcar para crear borradores y revisarlos en Sanity Studio antes de publicarlos.
    </Callout>
  </Tab>

  <Tab title="Actualizar recurso" icon="pencil">
    #### **Update Resource**

    Actualiza un documento existente en tu dataset de Sanity.

    **Entradas obligatorias**

    * **Sanity Project** — Selecciona el proyecto de Sanity que conectaste en Profound
    * **Dataset** — Selecciona el dataset
    * **Resource ID** — El ID del documento de Sanity que quieres actualizar
    * **Update Details** — Un objeto JSON con los campos que quieres cambiar

    **Entradas opcionales**

    * **Rich Text Content** — Un objeto JSON que asigna nombres de campo a cadenas HTML, convertidas automáticamente a Portable Text

    <Callout icon="lightbulb" color="#376CFF">
      **Importante:** Solo se modificarán los campos que proporciones; todos los demás campos permanecen sin cambios. El `_type` del documento no se puede cambiar después de su creación.
    </Callout>
  </Tab>

  <Tab title="Obtener recurso" icon="file">
    #### **Get Resource**

    Recupera un único documento por su ID.

    **Entradas obligatorias**

    * **Sanity Project** — Selecciona el proyecto de Sanity que conectaste en Profound
    * **Dataset** — Selecciona el dataset
    * **Resource ID** — El ID del documento de Sanity que quieres obtener

    La salida incluye el contenido completo del documento con todos sus campos y metadatos. Se pueden recuperar tanto documentos publicados como borradores (los borradores usan el prefijo `drafts.`).
  </Tab>

  <Tab title="Listar recursos" icon="list">
    #### **List Resources**

    Recupera una lista de documentos de tu dataset de Sanity.

    **Entradas obligatorias**

    * **Sanity Project** — Selecciona el proyecto de Sanity que conectaste en Profound
    * **Dataset** — Selecciona el dataset

    **Entradas opcionales**

    * **Document Type** — Filtra por un tipo de documento específico de Sanity, o déjalo como "All Types"
    * **Include drafts?** — Usa la perspectiva raw para incluir tanto documentos publicados como borradores
    * **Page** — Número de página que quieres recuperar (el valor predeterminado es 1)
    * **Per Page** — Número de elementos por página (el valor predeterminado es 100)

    La salida es una lista estructurada de documentos ordenados por fecha de creación (los más recientes primero) que se puede usar en pasos posteriores del Agent.
  </Tab>

  <Tab title="Publicar recurso" icon="globe">
    #### **Publish Resource**

    Publica un documento en borrador para que quede disponible públicamente.

    **Entradas obligatorias**

    * **Sanity Project** — Selecciona el proyecto de Sanity que conectaste en Profound
    * **Dataset** — Selecciona el dataset
    * **Draft ID** — El ID del documento en borrador que quieres publicar (debe empezar con `drafts.`)

    Al publicar, la versión publicada se reemplaza con el contenido del borrador y se elimina el documento en borrador. Esto replica el comportamiento de publicación de Sanity Studio.
  </Tab>
</Tabs>

***

## Conceptos clave

### Documentos y tipos

Todo documento en Sanity tiene un campo `_type` que determina su esquema. Los tipos de Sanity son el equivalente a "modelos de contenido" o "plantillas": definen la estructura y los campos que puede tener un documento.

Al crear un documento con el paso **Create Resource**, el campo `_type` de tus datos determina qué esquema sigue el documento. El tipo ya debe existir en el esquema de tu proyecto de Sanity.

Ejemplos comunes de tipos de documento:

| Tipo | Ejemplo de uso |
| - | - |
| `post` | Artículos de blog |
| `page` | Páginas estáticas |
| `product` | Productos de comercio electrónico |
| `author` | Creadores de contenido |
| `category` | Taxonomía/clasificación |

<Callout icon="lightbulb" color="#376CFF">
  **Consejo:** Para ver qué tipos existen en tu proyecto, usa el paso **List Resources** sin filtro de tipo: los documentos devueltos mostrarán los valores de `_type` disponibles.
</Callout>

### Datasets

Los proyectos de Sanity pueden tener varios datasets (por ejemplo, `production`, `staging`, `development`). Cada dataset es un almacén de contenido independiente. Especifica siempre el dataset correcto al configurar los pasos de tu Agent.

### Borradores frente a publicados

Sanity usa un sistema de doble ID para el control de versiones del contenido:

* **Los documentos publicados** tienen un ID simple (por ejemplo, `abc123`)
* **Los documentos en borrador** tienen el mismo ID con el prefijo `drafts.` (por ejemplo, `drafts.abc123`)

Cuando creas un recurso sin activar **Publish Resource**, Profound lo crea automáticamente como borrador. Más adelante puedes publicarlo con el paso **Publish Resource**, o publicarlo directamente desde Sanity Studio.

***

## Trabajar con Portable Text (texto enriquecido)

Sanity usa [Portable Text](https://www.sanity.io/docs/block-content) como su formato nativo de texto enriquecido. Portable Text es una especificación basada en JSON que representa contenido estructurado como un array de bloques.

### Proporcionar contenido de texto enriquecido

Tienes dos opciones para proporcionar contenido de texto enriquecido a los campos de Sanity:

<Tabs>
  <Tab title="Entrada HTML (recomendado)">
    Usa el campo **Rich Text Content** para pasar cadenas HTML. Profound las convierte automáticamente en bloques de Portable Text.

    Asigna nombres de campo a cadenas HTML:

    ```json theme={null}
    {
      "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>"
    }
    ```

    **Elementos HTML compatibles:**

    | Elemento | Equivalente en Portable Text |
    | - | - |
    | `<h1>` a `<h6>` | Estilos de encabezado |
    | `<p>` | Párrafo normal |
    | `<strong>`, `<b>` | Marca de negrita |
    | `<em>`, `<i>` | Marca de cursiva |
    | `<u>` | Marca de subrayado |
    | `<code>` | Marca de código |
    | `<a href="...">` | Anotación de enlace |
    | `<ul>`, `<ol>`, `<li>` | Listas con viñetas y numeradas |
    | `<blockquote>` | Estilo de cita en bloque |
    | `<br>` | Salto de línea |

    <Callout icon="lightbulb" color="#376CFF">
      **Consejo:** Esta es la forma más sencilla de incorporar texto enriquecido en Sanity. Genera HTML desde un paso de LLM y pásalo directamente a Rich Text Content. Profound se encarga de la conversión.
    </Callout>
  </Tab>

  <Tab title="JSON nativo de Portable Text">
    Si ya tienes JSON de Portable Text (por ejemplo, de un paso **Get Resource**), puedes pasarlo directamente en el campo **Document Details**:

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

    Cada bloque requiere:

    * `_type`: Siempre `"block"` para bloques de texto
    * `_key`: Un identificador de cadena único
    * `style`: Estilo del bloque (`"normal"`, `"h1"` a `"h6"`, `"blockquote"`)
    * `markDefs`: Array de definiciones de marcas complejas (por ejemplo, enlaces con `href`)
    * `children`: Array de spans con `_type`, `_key`, `text` y `marks`

    Las marcas de formato incluyen: `"strong"`, `"em"`, `"underline"`, `"code"`.

    Para los elementos de lista, agrega:

    * `listItem`: `"bullet"` o `"number"`
    * `level`: Nivel de anidamiento (entero)
  </Tab>
</Tabs>

***

## Asignar esquemas de Sanity a pasos de Agent

Si tienes un esquema de Sanity existente (tipo de documento), así es como puedes asignarlo a un paso **Create Resource** en tu Agent.

### Ejemplo: esquema de entrada de blog

Supón que tu Sanity Studio tiene un tipo `post` con estos campos:

```js theme={null}
// 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' }] }] }),
  ],
})
```

### Configuración paso a paso

1. **Agrega un paso Create Resource** a tu Agent y selecciona tu proyecto de Sanity conectado en el menú desplegable **Sanity Project**.

2. **Selecciona el Dataset** en el menú desplegable (por ejemplo, `production`).

3. **Completa Document Details** con los campos de tu documento en formato JSON. Aquí es donde proporcionas valores simples como títulos, slugs, referencias y categorías:

   ```json theme={null}
   {
     "_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"
       }
     ]
   }
   ```

   Para usar valores dinámicos de pasos anteriores, escribe `/` dentro del campo para abrir el menú de variables y selecciona una variable. Aparecerá como una insignia en línea con tu JSON. Por ejemplo, podrías reemplazar `"My Post Title"` con una variable de un paso de LLM anterior.

4. **Completa Rich Text Content** para cualquier campo de Portable Text (como el cuerpo de un blog). Asigna el nombre del campo a una cadena HTML. Profound la convierte automáticamente al formato de Sanity:

   ```json theme={null}
   {
     "body": "<h1>Welcome</h1><p>This is my post content.</p>"
   }
   ```

   También puedes insertar aquí una variable para pasar HTML generado por un paso anterior. Escribe `/` para abrir el menú de variables y selecciona como valor la salida de un LLM u otro paso anterior.

5. **Marca o desmarca Publish Resource** — márcalo para publicar de inmediato, o déjalo sin marcar para crear un borrador y revisarlo en Sanity Studio.

<Callout icon="lightbulb" color="#376CFF">
  **Consejo:** Cualquier campo de texto en la configuración del nodo admite **variables**: escribe `/` para abrir el menú de variables e insertar salidas de pasos anteriores. Las variables aparecen como insignias interactivas y se resuelven en tiempo de ejecución.
</Callout>

### Referencia de tipos de campo

| Tipo de campo de Sanity | Formato JSON en los datos |
| - | - |
| `string` | `"value"` |
| `text` | `"multi-line value"` |
| `number` | `42` |
| `boolean` | `true` / `false` |
| `datetime` | `"2025-01-15T10:30:00Z"` |
| `date` | `"2025-01-15"` |
| `url` | `"https://example.com"` |
| `slug` | `{ "_type": "slug", "current": "my-slug" }` |
| `reference` | `{ "_type": "reference", "_ref": "document-id" }` |
| `image` | `{ "_type": "image", "asset": { "_type": "reference", "_ref": "image-asset-id" } }` |
| `blockContent` | Usa el campo **Rich Text Content** para la conversión automática, o pasa directamente JSON de Portable Text |
| `array` de referencias | `[{ "_type": "reference", "_ref": "id" }]` |
| `object` | `{ "fieldA": "value", "fieldB": 42 }` |

***

## Flujos de trabajo comunes

### Generar y publicar una entrada de blog

1. **Paso de LLM** — Genera un título, un slug y un cuerpo HTML a partir de un prompt
2. **Create Resource** — Crea un documento `post` de Sanity con el contenido generado
3. **Publish Resource** — Publica el borrador (o establece `publish_resource: true` en el paso 2)

### Actualizar contenido existente

1. **Get Resource** — Obtén el documento actual por su ID
2. **Paso de LLM** — Genera contenido actualizado basado en el documento existente
3. **Update Resource** — Modifica solo los campos que cambiaron

### Migración de contenido

1. **List Resources** — Obtén documentos de un dataset
2. **Loop** — Itera sobre la lista
3. **Create Resource** — Crea cada documento en un dataset diferente

### Flujo de revisión de borradores

1. **Create Resource** — Crea contenido como borrador (comportamiento predeterminado)
2. **Revisión humana** — Paso de revisión manual en Sanity Studio
3. **Publish Resource** — Publica los borradores aprobados mediante el Agent

***

## Permisos y roles

Profound valida que tu token de API tenga permisos suficientes al conectarse. Se admiten los siguientes roles de Sanity:

| Rol | Puede crear | Puede actualizar | Puede publicar | Puede leer |
| - | - | - | - | - |
| **Administrator** | Sí | Sí | Sí | Sí |
| **Editor** | Sí | Sí | Sí | Sí |
| **Developer** | Sí | Sí | Sí | Sí |
| **Viewer** | No | No | No | Sí |

<Callout icon="warning" color="#FF6B35">
  **Rol mínimo requerido:** Editor. Los tokens con acceso solo de Viewer fallarán al intentar crear, actualizar o publicar documentos.
</Callout>

***

## Solución de problemas

<Accordion title="Error: Invalid Sanity API key or token has expired">
  Tu token de API no es válido o ha caducado. Genera un nuevo token en tu [consola de administración de Sanity](https://www.sanity.io/manage) en **API → Tokens** y vuelve a conectarte.
</Accordion>

<Accordion title="Error: Insufficient permissions">
  Tu token de API no tiene acceso de nivel Editor. Crea un nuevo token con permisos de **Editor** y vuelve a conectarte.
</Accordion>

<Accordion title="Error: Sanity project not found">
  El Project ID en la configuración de tu integración es incorrecto. Verifica el Project ID en tu [consola de administración de Sanity](https://www.sanity.io/manage). Se muestra en la parte superior de la página de tu proyecto y en la URL.
</Accordion>

<Accordion title="Error: Document type (_type) must be provided">
  Al usar **Create Resource**, tu campo Data debe incluir una propiedad `_type` que coincida con un tipo de documento definido en tu esquema de Sanity. Por ejemplo: `{ "_type": "post", "title": "Hello" }`.
</Accordion>

<Accordion title="Error: Resource ID is not a draft">
  El paso **Publish Resource** requiere un ID de documento en borrador que empiece con `drafts.`. Si el documento ya está publicado, no es necesario volver a publicarlo. Comprueba que estás pasando el ID del borrador, no el ID publicado.
</Accordion>

<Accordion title="El HTML no se convierte correctamente en texto enriquecido">
  Asegúrate de usar el campo **Rich Text Content** (no el campo **Document Details**) para la conversión de HTML a Portable Text. El campo Rich Text Content espera un objeto JSON que asigne nombres de campo a cadenas HTML: `{ "body": "<p>Hello</p>" }`.
</Accordion>

***

## Recursos adicionales

Obtén más información sobre el modelo de contenido y la API de Sanity:

* [Sanity Content Lake](https://www.sanity.io/docs/content-lake) — Comprender los datasets y los documentos
* [Portable Text](https://www.sanity.io/docs/block-content) — Especificación del formato de texto enriquecido de Sanity
* [GROQ Query Language](https://www.sanity.io/docs/groq) — Consultar contenido en Sanity
* [HTTP API Reference](https://www.sanity.io/docs/http-api) — Documentación completa de la API de Sanity
* [Mutations API](https://www.sanity.io/docs/http-mutations) — Crear, actualizar y eliminar documentos