# 機能設計書 84-OpenAI Webサーチツール

## 概要

本ドキュメントは、Giselleプラットフォームにおけるテキスト生成時のOpenAI Web検索ツール連携機能の設計を定義する。この機能は、AIモデルがテキスト生成中にOpenAIのWeb検索機能を利用してリアルタイムの情報を取得し、より正確で最新の情報に基づいた応答を生成できるようにする。

### 本機能の処理概要

**業務上の目的・背景**：AIモデルの知識には訓練データのカットオフ日が存在し、最新の情報を持たない場合がある。ニュース、技術ドキュメント、製品情報など、リアルタイムの情報が必要なユースケースにおいて、Web検索機能を統合することで、AIモデルが最新かつ正確な情報に基づいた回答を生成できる。本機能は、OpenAI APIのWebサーチツールを活用し、テキスト生成ノードからWeb検索を可能にする。

**機能の利用シーン**：
- 最新のニュースや出来事について質問に回答する場合
- 特定の製品やサービスの最新情報を調査する場合
- 技術ドキュメントや仕様の最新版を参照する場合
- 特定のドメインに限定した検索を行う場合

**主要な処理内容**：
1. ユーザーがテキスト生成ノードでOpenAI Webサーチツールを設定
2. 許可ドメインリスト（オプション）を設定
3. テキスト生成実行時にbuildToolSet関数でWebサーチツールを構築
4. AI SDKのopenai.tools.webSearch()を初期化
5. AIモデルが必要に応じてWeb検索を実行
6. 検索結果がAIモデルに返却され、応答生成に活用される

**関連システム・外部連携**：
- OpenAI Web Search API
- Vercel AI SDK（@ai-sdk/openai）

**権限による制御**：OpenAI APIキーの有効性に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 補助機能 | テキスト生成ノードでのOpenAI Webサーチツール設定 |

## 機能種別

外部API連携 / ツール実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| allowedDomains | string[] | No | 許可ドメインリスト | 有効なドメイン形式であること |

### 入力データソース

- ノード設定: TextGenerationContent.tools.openaiWebSearch

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| toolSet.web_search | Tool | AI SDKで使用可能なWeb検索ツール |

### 出力先

- テキスト生成処理: generateContent関数内でツールとして使用

## 処理フロー

### 処理シーケンス

```
1. テキスト生成リクエスト受信
   └─ TextGenerationContentにOpenAI Webサーチツール設定を含む
2. ツールセット構築（buildToolSet）
   └─ ツール設定からOpenAI Webサーチツールを識別
3. 設定検証
   └─ allowedDomainsのスキーマ検証
4. Webサーチツール初期化
   └─ openai.tools.webSearch()を呼び出し
5. AI生成処理
   └─ AIモデルが必要に応じてツールを呼び出し
6. Web検索実行
   └─ OpenAI APIを通じてWeb検索を実行
7. 結果統合
   └─ 検索結果がAIモデルに返却される
```

### フローチャート

```mermaid
flowchart TD
    A[テキスト生成リクエスト] --> B{OpenAI Webサーチ設定あり?}
    B -->|No| Z[通常の生成処理]
    B -->|Yes| C[設定オプション取得]
    C --> D{設定検証成功?}
    D -->|No| E[警告ログ出力]
    E --> Z
    D -->|Yes| F{allowedDomains設定あり?}
    F -->|Yes| G[フィルター付きwebSearch初期化]
    F -->|No| H[デフォルトwebSearch初期化]
    G --> I[ToolSetに追加]
    H --> I
    I --> J[AI生成処理]
    J --> K{Web検索呼び出し?}
    K -->|No| L[生成完了]
    K -->|Yes| M[OpenAI Web Search API実行]
    M --> N[検索結果返却]
    N --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-84-01 | ツール名 | ツール名は"web_search"固定 | 常時 |
| BR-84-02 | ドメイン検証 | allowedDomainsの各ドメインは有効な形式であること | allowedDomains設定時 |
| BR-84-03 | ドメインフィルタ | allowedDomainsが設定されている場合、指定ドメインのみを検索対象とする | allowedDomains設定時 |
| BR-84-04 | 設定検証失敗時スキップ | 設定検証に失敗した場合はツールをスキップ | 検証失敗時 |

### 計算ロジック

特になし。

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | データベースアクセスなし |

### テーブル別操作詳細

データベースアクセスは発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | 設定スキーマ検証失敗 | ツールをスキップしてログ出力 |

### リトライ仕様

OpenAI API呼び出しに対するリトライは、AI SDKのデフォルト動作に従う。

## トランザクション仕様

トランザクション管理は不要（外部API呼び出しのため）。

## パフォーマンス要件

- ツールセット構築時間: < 10ms
- Web検索レスポンス: OpenAI APIのレスポンス時間に依存

## セキュリティ考慮事項

- OpenAI APIキーは環境変数で管理
- 許可ドメインによる検索範囲の制限が可能
- 検索クエリはOpenAI APIに送信される

## 備考

- OpenAI Web Search Toolは@ai-sdk/openaiパッケージのtools.webSearch()を使用
- allowedDomainsを設定することで、特定のドメインのみを検索対象にできる
- ドメイン検証には正規表現ベースのバリデーションが使用される

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

OpenAI Webサーチツールの型定義と設定オプションを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | text-generation.ts | `packages/protocol/src/node/operations/text-generation.ts` | OpenAIWebSearchTool型定義（91-102行目） |
| 1-2 | openai-web-search.ts | `packages/language-model-registry/src/tools/openai-web-search.ts` | ツール定義と設定オプション |

**読解のコツ**: configurationOptionsにallowedDomainsオプションが定義されている。validateにドメイン検証関数が設定されている。

#### Step 2: エントリーポイントを理解する

ツールセット構築の処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | build-tool-set.ts | `packages/giselle/src/generations/v2/tools/build-tool-set.ts` | openai-web-searchケース（118-136行目） |

**主要処理フロー**:
1. **119-122行目**: 設定スキーマの定義
2. **123行目**: safeParse()で設定検証
3. **124-129行目**: 検証失敗時の警告ログとスキップ
4. **130-134行目**: openai.tools.webSearch()の呼び出し

#### Step 3: ドメイン検証を理解する

ドメイン検証ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | openai-web-search.ts | `packages/language-model-registry/src/tools/openai-web-search.ts` | isValidDomain関数（4-13行目） |

**主要処理フロー**:
- **5-7行目**: 空文字チェック
- **8-11行目**: 正規表現によるドメイン形式検証

### プログラム呼び出し階層図

```
generateContent (generate-content.ts)
    │
    ├─ buildToolSet (build-tool-set.ts)
    │      │
    │      ├─ getLanguageModelTool("openai-web-search")
    │      │
    │      └─ openai.tools.webSearch({filters?})
    │             │
    │             └─ AI SDK / OpenAI API
    │
    └─ streamText / generateText (AI SDK)
           │
           └─ ツール呼び出し → Web Search実行
```

### データフロー図

```
[入力]                    [処理]                         [出力]

TextGenerationContent ───▶ buildToolSet ───▶ ToolSet
        │                       │
        ▼                       ▼
tools.openaiWebSearch    設定スキーマ検証
        │                       │
        ▼                       ▼
    allowedDomains        openai.tools.webSearch()
        │                       │
        └───────────────────────┘
                                │
                                ▼
                    [AI生成中のツール呼び出し]
                                │
                                ▼
                    OpenAI Web Search API
                                │
                                ▼
                          Search Results
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| text-generation.ts | `packages/protocol/src/node/operations/text-generation.ts` | ソース | OpenAIWebSearchTool型定義 |
| openai-web-search.ts | `packages/language-model-registry/src/tools/openai-web-search.ts` | ソース | ツール定義と設定オプション |
| build-tool-set.ts | `packages/giselle/src/generations/v2/tools/build-tool-set.ts` | ソース | ツールセット構築のエントリーポイント |
| generate-content.ts | `packages/giselle/src/generations/generate-content.ts` | ソース | テキスト生成処理（ツール使用） |
