Работа с файлами

Обновлено 12 мая 2026

Агенты Gigalab могут работать с файлами, которые пользователи добавляют в интерфейсе, или загруженными в хранилище самостоятельно.

Добавление файлов в интерфейсе

Чтобы пользователь мог прикрепить файл к сообщению, нужно правильно описать схему агента с помощью фабричных функций SDK. Так, для прикрепления файлов доступны две pydantic-схемы:

• FileInput — позволяет прикрепить один файл;
• FilesInput — позволяет прикрепить несколько файлов одновременно.

Файлы, прикрепленные в интерфейсе, сохраняются в облачном хранилище и передаются в агент в виде https-ссылок. Агент скачивает файл по ссылке и использует его в своей работе.

На форматы и размер файлов действуют ограничения.

Подробнее о создании схемы агента — в разделе Создание интерфейса параметров запуска.

Загрузка файлов

Для добавления элементов интерфейса с помощью которых пользователь может прикрепить файл используйте функции SDK FileInput и FilesInput:

Добавление одного файла:

from agent_lab_sdk.schema import FileInput, FilesInput, Visibility

class FileAgentState(BaseModel):
    """
    Состояние агента.

    Функция FileInput сообщает веб-интерфейсу, как должен выглядеть элемент интерфейса для загрузки файлов.
    """

    messages: Annotated[Sequence[BaseMessage], add_messages]

    # Один файл — отображается как кнопка «Прикрепить документ»
    # visibility=START означает, что поле отображается только перед запуском агента
    document: Annotated[Optional[str], FileInput(
        title="Прикрепить документ",
        file_extensions=".txt,.md,.csv,.json,.pdf",
        view="dropzone",
        visibility=Visibility.AFTER_START,
        max_size_mb=10.0,
    )] = None

Добавление нескольких файлов:

from agent_lab_sdk.schema import FileInput, FilesInput, Visibility

class FileAgentState(BaseModel):
    """
    Состояние агента.

    Функция FilesInput, сообщает веб-интерфейсу, как должен выглядеть элемент интерфейса для загрузки файлов.
    """

    messages: Annotated[Sequence[BaseMessage], add_messages]

    # Несколько файлов — отображается как drag-and-drop зона
    # visibility=ALWAYS означает, что поле отображается как перед запуском, так и в процессе диалога
    attachments: Annotated[Optional[List[str]], FilesInput(
        title="Прикрепить файлы",
        file_extensions=".txt,.md,.csv,.json,.pdf",
        view="button",
        limit=5,
        visibility=Visibility.ALWAYS,
        max_size_mb=10.0,
    )] = None

Функции FileInput и FilesInput принимают параметры:

Параметр	Описание
title	Название элемента в интерфейсе
file_extensions	Допустимые расширения через запятую, например .pdf,.txt
view	Вид поля: "button" — кнопка, "dropzone" — область для перетаскивания
max_size_mb	Максимальный размер файла в Мб
group	Название группы полей в интерфейсе
hidden	Скрывает поле в интерфейсе
depends	Зависимость от другого поля
visibility	Условие отображения поля. Подробнее — Управление видимостью
limit	Максимальное количество файлов. Актуально только при работе с несколькими файлами с помощью FilesInput

Чтение файла

GigaLab возвращает файл в состояние агента в виде ссылки на хранилище.

Пример обработки файла по ссылке:

import httpx


def read_file(file_url: str) -> bytes:
    response = httpx.get(file_url, timeout=30.0, follow_redirects=True)
    response.raise_for_status()
    return response.content

Форматы и ограничения

Максимальный суммарных размер файлов в одном сообщении — 150 Мб.

Для ограничения размера одного файла используйте параметр max_size_mb. Для ограничения количества файлов, прикрепляемых с помощью FilesInput используйте параметр limit.

При превышении количества или размера файлов GigaLab вернет ошибку.

Формат	MIME-тип
csv, md, txt, xml, html, json	text/*, application/*
doc	application/msword
docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
ppt	application/vnd.ms-powerpoint
pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation
pdf	application/pdf
xlsx	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
xls	application/vnd.ms-excel

Формат	MIME-тип
gif	image/gif
jpg, jpeg, jpe	image/jpeg
png	image/png
bmp	image/bmp, image/x-ms-bmp
webp	image/webp
heic	image/heic
heif	image/heif

Загрузка файлов в хранилище

Для загрузки файлов в хранилище напрямую используйте upload_file:

from agent_lab_sdk.storage import upload_file, FileUploadResponse

# Загрузка из байтов
with open("document.pdf", "rb") as f:
    file_bytes = f.read()
result: FileUploadResponse = upload_file("document.pdf", file_bytes)

# Результат - Pydantic модель с информацией о файле
print(f"File ID: {result.id}")
print(f"Absolute Path: {result.absolute_path}")
print(f"Storage: {result.storage}")

Смотрите также

Параметры запуска

Все доступные фабричные функции для создания интерфейса агента