# 機能設計書 85-Anthropic Webサーチツール

## 概要

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

### 本機能の処理概要

**業務上の目的・背景**：AIモデルの知識には訓練データのカットオフ日が存在し、最新の情報を持たない場合がある。Anthropicが提供するWeb検索ツールを活用することで、Claudeモデルが最新の情報を参照しながら回答を生成できる。本機能は、OpenAI Webサーチツールと同様の目的を持つが、Anthropicのモデルに特化した実装を提供する。

**機能の利用シーン**：
- Claudeモデルを使用して最新のニュースや出来事について回答する場合
- 特定のドメインに限定した検索を行う場合
- 特定のドメインを除外した検索を行う場合
- 検索回数を制限して効率的な情報収集を行う場合

**主要な処理内容**：
1. ユーザーがテキスト生成ノードでAnthropic Webサーチツールを設定
2. maxUses（最大検索回数）、allowedDomains、blockedDomainsを設定
3. テキスト生成実行時にbuildToolSet関数でWebサーチツールを構築
4. AI SDKのanthropic.tools.webSearch_20250305()を初期化
5. AIモデルが必要に応じてWeb検索を実行
6. 検索結果がAIモデルに返却され、応答生成に活用される

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

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

## 関連画面

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

## 機能種別

外部API連携 / ツール実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| maxUses | number | No | 最大検索回数（1-5） | 1, 2, 3, 4, 5のいずれか |
| allowedDomains | string[] | No | 許可ドメインリスト | 有効なドメイン形式であること |
| blockedDomains | string[] | No | ブロックドメインリスト | 有効なドメイン形式であること |

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

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

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-85-01 | ツール名 | ツール名は"web_search"固定 | 常時 |
| BR-85-02 | ドメイン検証 | allowedDomains/blockedDomainsの各ドメインは有効な形式であること | ドメイン設定時 |
| BR-85-03 | ドメイン排他制御 | allowedDomainsとblockedDomainsは同時に使用不可 | ドメイン設定時 |
| BR-85-04 | 最大検索回数 | maxUsesは1-5の範囲で指定 | maxUses設定時 |
| BR-85-05 | 設定検証失敗時スキップ | 設定検証に失敗した場合はツールをスキップ | 検証失敗時 |

### 計算ロジック

特になし。

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

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

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- Anthropic Web Search ToolはwebSearch_20250305というバージョン付きAPIを使用
- allowedDomainsとblockedDomainsは排他的（同時使用不可）
- maxUsesで検索回数を制限することでコスト管理が可能

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: configurationOptionsにmaxUses、allowedDomains、blockedDomainsの3つのオプションが定義されている。maxUsesはenum型で1-5の選択肢を持つ。

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

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

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

**主要処理フロー**:
1. **36-42行目**: 設定スキーマの定義（allowedDomains、blockedDomains、maxUses）
2. **43-44行目**: safeParse()で設定検証
3. **46-51行目**: 検証失敗時の警告ログとスキップ
4. **53-57行目**: anthropic.tools.webSearch_20250305()の呼び出し

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

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

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

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

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

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

### データフロー図

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

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

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| text-generation.ts | `packages/protocol/src/node/operations/text-generation.ts` | ソース | AnthropicWebSearchTool型定義 |
| anthropic-web-search.ts | `packages/language-model-registry/src/tools/anthropic-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` | ソース | テキスト生成処理（ツール使用） |
