File Helpers Toolkit
File Helpers ツールキットはエージェントにファイルユーティリティを与えます：base64 ペイロードをストレージに保存し、インテリジェントなテキスト抽出でファイルを読み、テキストエンコーディングを変更し、MIME タイプを検出します。接続も API キーも不要です。
エージェントの Toolkits タブで追加し、エージェントがファイルを処理すべきときはペルソナプロンプト内で @ を使ってツールを参照します。
前提条件
- 編集できるエージェント
- Read File、Change File Encoding、Check File Type には、以前の保存ステップ（またはローカルファイルパスを書き出す別のツール）が返したファイルシステムパス
利用可能なツール
| ツール | 説明 |
|---|---|
| Save Base64 File | base64 コンテンツ（data:…;base64, プレフィックスを含む）をデコードして保存。MIME タイプとファイル名は任意。ファイル id、パス、名前、サイズ、MIME タイプ、ダウンロード URL を返す。 |
| Read File | ローカルパスのファイルを読み、一般的な形式（PDF、DOCX、PPTX、XLSX、CSV、JSON、TXT、メール形式など）からテキストを抽出。 |
| Change File Encoding | テキストファイルを再エンコード（例：utf-8 ↔ latin-1）し、新しいファイルを書き出す。 |
| Check File Type | 拡張子とファイルコンテンツから MIME タイプを検出。任意で許容 MIME タイプ一覧に対して検証。 |
ツールの連携
典型的なフロー：
- Save Base64 File — 例：メール添付や統合ペイロードから
- 返されたファイルパスを Read File、Check File Type、Change File Encoding で使用
Read File はサーバーのファイルシステムパスを必要とします。それ自体では公開 URL や Knowledge Base の名前は受け付けません — まずパスを保存または取得してください。
ユースケース
- メールや Webhook ステップからの base64 添付ファイルを永続化し、テキストとして読む
- ファイルを別のツールキットにルーティングする前に MIME タイプを検査する
- 分析の前に CSV やログファイルのエンコーディングを正規化する
- PDF 固有のページ画像や PDF 生成が必要な場合は PDF ツールキットと組み合わせる（File Helpers の Read File は多数の形式の一つとして PDF テキストを抽出できます）
ヒント
- 保存時はわかりやすいファイル名を選び、後続ステップでファイルを識別できるようにする。
- 特定の形式のみ受け付ける下流のツールの前に Check File Type を使用する。
- このツールキットで保存したファイルは Python サンドボックス内で自動的に利用可能になりません。Python Code Execution で分析する場合は、フローが必要とするときに別途サンドボックスへアップロードしてください。
- チャット内 markdown ドキュメント（作成/編集/一覧）には Document Manager を使用してください。
トラブルシューティング
| 症状 | 確認すること |
|---|---|
| Read File が失敗 | Save Base64 File（または別のライター）から渡した file_path か、URL や KB の表示名ではないかを確認 |
| 読み取り後に文字化け | 正しいソースとターゲットのエンコーディングで Change File Encoding を使用 |
| Check File Type がファイルを拒否 | 許容 MIME リストを調整するか、ファイルが期待どおりの型か確認 |
| PDF ツールキットと混同 | File Helpers は汎用の保存/読取/エンコード/検査；PDF ツールキットは全ページ抽出、ページ画像化、PDF 生成を追加 |