> ## 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.

# Agents で Sanity を使用する

Sanity アカウントを接続すると、以下のアクションが Agent のステップとして利用可能になります。各ステップでは、ドロップダウンから接続済みの **Sanity Project** を選択する必要があります。

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

    Sanity のデータセットに新しいドキュメントを作成します。

    **必須の入力**

    * **Sanity Project** — Profound で接続した Sanity プロジェクトを選択します
    * **Dataset** — データセットを選択します(例: `production`)
    * **Document Details** — ドキュメントのフィールドを含む JSON オブジェクト(`_type` を含める必要があります)

    **オプションの入力**

    * **Rich Text Content** — フィールド名を HTML 文字列に対応付けた JSON オブジェクト。Profound が HTML を Sanity の Portable Text 形式に自動的に変換します
    * **Publish Resource** — すぐに公開する場合はオンにし、下書きを作成する場合はオフのままにします

    デフォルトでは、新しいドキュメントは**下書き**として作成されます。Profound は `drafts.` で始まる下書き ID を自動的に生成します。ドキュメントをすぐに公開するには、**Publish Resource** を有効にしてください。

    <Callout icon="lightbulb" color="#376CFF">
      **ヒント:** **Publish Resource** をオフのままにすると、公開前に Sanity Studio でレビューするための下書きを作成できます。
    </Callout>
  </Tab>

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

    Sanity のデータセット内の既存のドキュメントを更新します。

    **必須の入力**

    * **Sanity Project** — Profound で接続した Sanity プロジェクトを選択します
    * **Dataset** — データセットを選択します
    * **Resource ID** — 更新する Sanity ドキュメントの ID
    * **Update Details** — 変更するフィールドを含む JSON オブジェクト

    **オプションの入力**

    * **Rich Text Content** — フィールド名を HTML 文字列に対応付けた JSON オブジェクト。Portable Text に自動変換されます

    <Callout icon="lightbulb" color="#376CFF">
      **重要:** 変更されるのは指定したフィールドのみで、その他のフィールドはすべてそのまま維持されます。ドキュメントの `_type` は作成後に変更できません。
    </Callout>
  </Tab>

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

    ID を指定して 1 つのドキュメントを取得します。

    **必須の入力**

    * **Sanity Project** — Profound で接続した Sanity プロジェクトを選択します
    * **Dataset** — データセットを選択します
    * **Resource ID** — 取得する Sanity ドキュメントの ID

    出力には、すべてのフィールドとメタデータを含むドキュメントの全内容が含まれます。公開済みのドキュメントと下書きのドキュメントの両方を取得できます(下書きには `drafts.` プレフィックスが付きます)。
  </Tab>

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

    Sanity のデータセットからドキュメントの一覧を取得します。

    **必須の入力**

    * **Sanity Project** — Profound で接続した Sanity プロジェクトを選択します
    * **Dataset** — データセットを選択します

    **オプションの入力**

    * **Document Type** — 特定の Sanity ドキュメントタイプで絞り込むか、「All Types」のままにします
    * **Include drafts?** — raw パースペクティブを使用して、公開済みと下書きの両方のドキュメントを含めます
    * **Page** — 取得するページ番号(デフォルトは 1)
    * **Per Page** — 1 ページあたりのアイテム数(デフォルトは 100)

    出力は、作成日順(新しい順)に並べられたドキュメントの構造化リストで、後続の Agent ステップで使用できます。
  </Tab>

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

    下書きのドキュメントを公開します。

    **必須の入力**

    * **Sanity Project** — Profound で接続した Sanity プロジェクトを選択します
    * **Dataset** — データセットを選択します
    * **Draft ID** — 公開する下書きドキュメントの ID(`drafts.` で始まる必要があります)

    公開すると、公開済みバージョンが下書きの内容に置き換えられ、下書きドキュメントは削除されます。これは Sanity Studio での公開動作と同じです。
  </Tab>
</Tabs>

***

## 主要な概念

### ドキュメントとタイプ

Sanity のすべてのドキュメントには、スキーマを決定する `_type` フィールドがあります。Sanity のタイプは「コンテンツモデル」や「テンプレート」に相当するもので、ドキュメントが持つことのできる構造とフィールドを定義します。

**Create Resource** ステップでドキュメントを作成する場合、データ内の `_type` フィールドによって、ドキュメントが従うスキーマが決まります。そのタイプは、Sanity プロジェクトのスキーマにすでに存在している必要があります。

ドキュメントタイプの一般的な例:

| タイプ | 使用例 |
| - | - |
| `post` | ブログ記事 |
| `page` | 静的ページ |
| `product` | e コマースの商品 |
| `author` | コンテンツ作成者 |
| `category` | タクソノミー/分類 |

<Callout icon="lightbulb" color="#376CFF">
  **ヒント:** プロジェクトに存在するタイプを確認するには、タイプフィルターなしで **List Resources** ステップを使用します。返されたドキュメントに、利用可能な `_type` の値が表示されます。
</Callout>

### データセット

Sanity プロジェクトは複数のデータセット(例: `production`、`staging`、`development`)を持つことができます。各データセットは独立したコンテンツストアです。Agent のステップを設定する際は、必ず正しいデータセットを指定してください。

### 下書きと公開済み

Sanity は、コンテンツのバージョン管理に 2 つの ID を使い分ける仕組みを採用しています。

* **公開済みドキュメント**はプレーンな ID を持ちます(例: `abc123`)
* **下書きドキュメント**は、同じ ID に `drafts.` プレフィックスが付いたものを持ちます(例: `drafts.abc123`)

**Publish Resource** を有効にせずにリソースを作成すると、Profound は自動的に下書きとして作成します。後から **Publish Resource** ステップで公開するか、Sanity Studio から直接公開できます。

***

## Portable Text(リッチテキスト)の操作

Sanity は、ネイティブのリッチテキスト形式として [Portable Text](https://www.sanity.io/docs/block-content) を使用します。Portable Text は、構造化コンテンツをブロックの配列として表現する JSON ベースの仕様です。

### リッチテキストコンテンツの指定

Sanity のフィールドにリッチテキストコンテンツを指定する方法は 2 つあります。

<Tabs>
  <Tab title="HTML 入力(推奨)">
    **Rich Text Content** フィールドを使用して HTML 文字列を渡します。Profound が自動的に Portable Text ブロックに変換します。

    フィールド名を 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>"
    }
    ```

    **サポートされている HTML 要素:**

    | 要素 | Portable Text での対応 |
    | - | - |
    | `<h1>` から `<h6>` | 見出しスタイル |
    | `<p>` | 通常の段落 |
    | `<strong>`、`<b>` | 太字マーク |
    | `<em>`、`<i>` | 斜体マーク |
    | `<u>` | 下線マーク |
    | `<code>` | コードマーク |
    | `<a href="...">` | リンクアノテーション |
    | `<ul>`、`<ol>`、`<li>` | 箇条書きリストと番号付きリスト |
    | `<blockquote>` | 引用スタイル |
    | `<br>` | 改行 |

    <Callout icon="lightbulb" color="#376CFF">
      **ヒント:** これは Sanity にリッチテキストを取り込む最も簡単な方法です。LLM ステップで HTML を生成し、そのまま Rich Text Content に渡してください。変換は Profound が処理します。
    </Callout>
  </Tab>

  <Tab title="ネイティブ Portable Text JSON">
    すでに Portable Text JSON がある場合(例: **Get Resource** ステップから取得したもの)は、**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"
            }
          ]
        }
      ]
    }
    ```

    各ブロックには以下が必要です。

    * `_type`: テキストブロックの場合は常に `"block"`
    * `_key`: 一意の文字列識別子
    * `style`: ブロックスタイル(`"normal"`、`"h1"` から `"h6"`、`"blockquote"`)
    * `markDefs`: 複雑なマーク定義の配列(例: `href` を持つリンク)
    * `children`: `_type`、`_key`、`text`、`marks` を持つ span の配列

    書式マークには `"strong"`、`"em"`、`"underline"`、`"code"` があります。

    リスト項目の場合は、以下を追加します。

    * `listItem`: `"bullet"` または `"number"`
    * `level`: ネストレベル(整数)
  </Tab>
</Tabs>

***

## Sanity スキーマを Agent ステップに対応付ける

既存の Sanity スキーマ(ドキュメントタイプ)がある場合に、それを Agent の **Create Resource** ステップに対応付ける方法を説明します。

### 例: ブログ記事のスキーマ

Sanity Studio に、次のフィールドを持つ `post` タイプがあるとします。

```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' }] }] }),
  ],
})
```

### ステップごとのセットアップ

1. Agent に **Create Resource ステップを追加**し、**Sanity Project** ドロップダウンから接続済みの Sanity プロジェクトを選択します。

2. ドロップダウンから **Dataset を選択**します(例: `production`)。

3. **Document Details** に、ドキュメントのフィールドを JSON で入力します。ここでは、タイトル、スラッグ、参照、カテゴリなどのシンプルな値を指定します。

   ```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"
       }
     ]
   }
   ```

   前のステップの動的な値を使用するには、フィールド内で `/` を入力して変数メニューを開き、変数を選択します。変数は JSON 内にピルバッジとしてインライン表示されます。たとえば、`"My Post Title"` を前の LLM ステップの変数に置き換えることができます。

4. Portable Text フィールド(ブログ本文など)には、**Rich Text Content** を入力します。フィールド名を HTML 文字列に対応付けると、Profound が自動的に Sanity の形式に変換します。

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

   ここに変数を挿入して、前のステップで生成された HTML を渡すこともできます。`/` を入力して変数メニューを開き、LLM などの前のステップの出力を値として選択します。

5. **Publish Resource をオンまたはオフにします** — すぐに公開する場合はオンにし、Sanity Studio でレビューするための下書きを作成する場合はオフのままにします。

<Callout icon="lightbulb" color="#376CFF">
  **ヒント:** ノード設定のすべてのテキストフィールドで**変数**を使用できます。`/` を入力して変数メニューを開き、前のステップの出力を挿入します。変数はインタラクティブなピルバッジとして表示され、実行時に解決されます。
</Callout>

### フィールドタイプのリファレンス

| Sanity のフィールドタイプ | データ内の JSON 形式 |
| - | - |
| `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` | 自動変換には **Rich Text Content** フィールドを使用するか、Portable Text JSON を直接渡します |
| 参照の `array` | `[{ "_type": "reference", "_ref": "id" }]` |
| `object` | `{ "fieldA": "value", "fieldB": 42 }` |

***

## 一般的なワークフロー

### ブログ記事を生成して公開する

1. **LLM ステップ** — プロンプトからタイトル、スラッグ、HTML 本文を生成します
2. **Create Resource** — 生成したコンテンツを使用して Sanity の `post` ドキュメントを作成します
3. **Publish Resource** — 下書きを公開します(またはステップ 2 で `publish_resource: true` を設定します)

### 既存のコンテンツを更新する

1. **Get Resource** — ID を指定して現在のドキュメントを取得します
2. **LLM ステップ** — 既存のドキュメントに基づいて更新後のコンテンツを生成します
3. **Update Resource** — 変更されたフィールドのみを更新します

### コンテンツの移行

1. **List Resources** — あるデータセットからドキュメントを取得します
2. **Loop** — リストを反復処理します
3. **Create Resource** — 別のデータセットに各ドキュメントを作成します

### 下書きレビューのパイプライン

1. **Create Resource** — コンテンツを下書きとして作成します(デフォルトの動作)
2. **人によるレビュー** — Sanity Studio で手動のレビューを行います
3. **Publish Resource** — 承認された下書きを Agent 経由で公開します

***

## 権限とロール

Profound は、接続時に API トークンに十分な権限があるかを検証します。サポートされている Sanity のロールは次のとおりです。

| ロール | 作成 | 更新 | 公開 | 読み取り |
| - | - | - | - | - |
| **Administrator** | 可 | 可 | 可 | 可 |
| **Editor** | 可 | 可 | 可 | 可 |
| **Developer** | 可 | 可 | 可 | 可 |
| **Viewer** | 不可 | 不可 | 不可 | 可 |

<Callout icon="warning" color="#FF6B35">
  **必要最小限のロール:** Editor。Viewer のみのアクセス権を持つトークンでは、ドキュメントの作成、更新、公開に失敗します。
</Callout>

***

## トラブルシューティング

<Accordion title="エラー: Invalid Sanity API key or token has expired">
  API トークンが無効か、有効期限が切れています。[Sanity の管理コンソール](https://www.sanity.io/manage)の **API → Tokens** で新しいトークンを生成し、再接続してください。
</Accordion>

<Accordion title="エラー: Insufficient permissions">
  API トークンに Editor レベルのアクセス権がありません。**Editor** 権限を持つ新しいトークンを作成し、再接続してください。
</Accordion>

<Accordion title="エラー: Sanity project not found">
  インテグレーション設定のプロジェクト ID が正しくありません。[Sanity の管理コンソール](https://www.sanity.io/manage)でプロジェクト ID を確認してください。プロジェクト ID は、プロジェクトページの上部と URL に表示されています。
</Accordion>

<Accordion title="エラー: Document type (_type) must be provided">
  **Create Resource** を使用する場合、Data フィールドには、Sanity スキーマで定義されたドキュメントタイプに一致する `_type` プロパティを含める必要があります。例: `{ "_type": "post", "title": "Hello" }`。
</Accordion>

<Accordion title="エラー: Resource ID is not a draft">
  **Publish Resource** ステップには、`drafts.` で始まる下書きドキュメントの ID が必要です。ドキュメントがすでに公開済みの場合は、再度公開する必要はありません。公開済みの ID ではなく、下書きの ID を渡していることを確認してください。
</Accordion>

<Accordion title="HTML がリッチテキストに正しく変換されない">
  HTML から Portable Text への変換には、(**Document Details** フィールドではなく)**Rich Text Content** フィールドを使用していることを確認してください。Rich Text Content フィールドには、フィールド名を HTML 文字列に対応付けた JSON オブジェクトを指定します: `{ "body": "<p>Hello</p>" }`。
</Accordion>

***

## その他のリソース

Sanity のコンテンツモデルと API について詳しく学ぶ:

* [Sanity Content Lake](https://www.sanity.io/docs/content-lake) — データセットとドキュメントについて
* [Portable Text](https://www.sanity.io/docs/block-content) — Sanity のリッチテキスト形式の仕様
* [GROQ Query Language](https://www.sanity.io/docs/groq) — Sanity でのコンテンツのクエリ
* [HTTP API Reference](https://www.sanity.io/docs/http-api) — Sanity API の完全なドキュメント
* [Mutations API](https://www.sanity.io/docs/http-mutations) — ドキュメントの作成、更新、削除