ヘルパー（Helpers）は、コードノード（Python ノード）でのファイル処理とデータ変換を簡素化するために設計された、組み込みのユーティリティ関数セットです。

追加の import を行わずに await helpers.function_name の構文で直接呼び出すことができます。

主に、ファイルデータを Agentria の標準形式に変換したり、ノード間でデータを受け渡ししたりするために使用します。

• ファイル → base64 に変換

• ファイル → mime-type を抽出

• ファイル → Agentria 標準形式に変換

• ファイルのメタデータを抽出

ヘルパーの使用例

file_type = await helpers.get_mime_type_from_file(file)

ファイル用ヘルパー

ファイル処理に関連する主要なヘルパー関数の一覧です。

• get_base64_str_from_file(bytes | str | list) -> str

  • ファイルデータを base64 文字列に変換して返します。

• get_mime_type_from_file(bytes | str | list) -> str

  • ファイルの mime-type（例：image/png、application/pdf）を抽出します。

• as_files(value, key, default_mime_type, immutable) -> list[str] | None

  • ファイルデータを Agentria 標準のファイル形式（data:mime;base64,...）に変換します。

• get_file_metadata(bytes | str | list) -> dict

  • ファイルのメタデータ（name, size, extension, type）を辞書として返します。

as_files

さまざまな種類のファイルデータを、Agentria で利用できる標準形式に変換します。

ワークフロー内でファイルを受け渡す場合や、Web Request ノードと連携する場合に頻繁に使用される中核関数です。

async def as_files(

value: str | bytes | list | dict | None,

key: str | None = None,

default_mime_type: str = "application/octet-stream",

immutable: bool = True

) -> list[str] | None:

対応する入力タイプ

• as_files(bytes_data) : 単一ファイルデータ

• as_files(bytes_data, key="report.png") : ファイルキー（名前）を指定した単一ファイル

• as_files([b1, b2]) : 複数ファイルデータのリスト

• as_files([("k1", b1), ("k2", b2)]) : (key, file) タプルのリスト

• as_files({"k1": b1, "k2": b2}) : key-value のファイル辞書

使用例

# 1. 単一の画像バッファを Agentria で使えるファイル形式に変換

png_image_buffer = ...

from_buffer = await helpers.as_files(png_image_buffer)

# 2. 複数の画像バッファを変換

png_image_buffer_1 = ...

png_image_buffer_2 = ...

from_buffers = await helpers.as_files([png_image_buffer_1, png_image_buffer_2])

# 3. Web Request ノードで form-data key を指定する場合

png_image_buffer = ...

from_buffer = await helpers.as_files({"file": png_image_buffer})

# Or

from_buffer = await helpers.as_files(png_image_buffer, key="file")

# 4. immutable オプションの使用

# immutable=True: 指定した key を固定

from_buffer = await helpers.as_files(png_image_buffer, key="dont_touch", immutable=True)

# immutable=False: 次ノードで key 名の変更を許可

from_buffer = await helpers.as_files(png_image_buffer, key="can_be_renamed", immutable=False)

オプション説明

• key : form-data で使用するファイルキー名

• default_mime_type : mime-type を判定できない場合のデフォルト値

• immutable : key を固定するかどうか（True: 固定、False: 変更可能）

get_file_metadata

詳細なファイル情報（メタデータ）を抽出します。ファイルの検証、ログ出力、デバッグなど、さまざまな用途で利用できます。

返却フィールド