Helpers는 코드 노드(Python Node)에서 파일 처리와 데이터 변환을 쉽게 하기 위한 내장 유틸리티 함수 모음입니다.

별도의 import 없이 await helpers.함수명 형태로 바로 사용할 수 있으며,

파일 데이터를 agentria 표준 포맷으로 변환하거나 노드 간 전달할 때 사용됩니다.

• 파일 → base64 변환

• 파일 → mime-type 추출

• 파일 → agentria 표준 포맷 변환

• 파일 메타데이터 추출

Helpers 사용 예시

file_type = await helpers.get_mime_type_from_file(file)

File Helpers

파일 처리와 관련된 주요 헬퍼 함수 목록입니다.

• 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

  • 파일의 메타데이터(이름, 크기, 확장자, 타입)를 딕셔너리 형태로 반환합니다.

as_files

다양한 형태의 파일 데이터를 agentria에서 사용할 수 있는 표준 파일 포맷으로 변환합니다.

워크플로 내에서 파일을 전달하거나, Web Request Node와 연동할 때 많이 사용되는 핵심 함수입니다.

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 Node 사용 시 form-data key 지정

png_image_buffer = ...

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

# 또는

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

파일의 상세 정보(메타데이터)를 추출합니다. 파일 검증, 로깅, 디버깅 등 다양한 용도로 활용할 수 있습니다.

반환 항목