Создание схемы агента

Обновлено 9 июня 2026

Функции GigaLab SDK позволяют создать схему агента, которая будет определять параметры его запуска.

В этом разделе вы найдете примеры кода и описание функций SDK для создания элементов интерфейса агента, а также узнаете как настроить видимость и сгруппировать их в интерфейсе GigaLab.

В интерфейсе GigaLab созданная схема выглядит как набор полей и элементов управления, с помощью которых пользователь может задать начальное состояние агента:

Процесс создания интерфейса из схемы

В общем случае создание интерфейса параметров запуска с помощью схемы агента выглядит так:

1. В графе агента описывается Pydantic-модель состояния или конфигурации (например, AgentState, AgentConfig), которая используется как State и RunnableConfig.
2. Поля, которые отображаются в интерфейсе, аннотируются фабриками из agent_lab_sdk.schema.input_types через typing.Annotated.
3. Среда исполнения использует Agent Protocol для публикации схемы агента (AgentSchema) с полями input_schema и config_schema.
4. Фронтенд запрашивает схему у среды исполнения и строит форму параметров запуска на основе метаданных из полей (type/inputType, title, group, visibility, ограничения по файлам и других).
5. При запуске или продолжении диалога фронтенд передает введенные значения обратно в среду исполнения. Данные можно использовать в коде агента, обращаясь к State или RunnableConfig.

Пример создания схемы с помощью фабричных функций

Пример ниже демонстрирует создание схемы агента с помощью Pydantic-модели и фабричных функций SDK.

from typing import List, Annotated
from pydantic import BaseModel, Field
from agent_lab_sdk.schema import (
    MainInput, StringInput, StringArrayInput, NumberInput,
    SelectInput, CheckboxInput, FileInput, FilesInput, SelectOption, Visibility
)

class AgentState(BaseModel):
    # Основное поле ввода
    query: Annotated[str, MainInput(placeholder="Введите ваш запрос")]
    
    # Строковое поле
    title: Annotated[str, StringInput(
        default="Без названия",
        title="Заголовок",
        description="Название для вашего запроса",
        visibility=Visibility.ALWAYS  # или visibility="always"
    )]
    
    # Массив строк
    keywords: Annotated[List[str], StringArrayInput(
        placeholder="Добавьте ключевые слова...",
        title="Ключевые слова",
        description="Список ключевых слов для поиска",
        group="Параметры"
    )]
    
    # Числовое поле
    temperature: Annotated[float, NumberInput(
        default=0.7,
        title="Температура",
        description="Параметр креативности модели (0.0 - 1.0)",
        hidden=True
    )]
    
    # Выпадающий список
    mode: Annotated[str, SelectInput(
        title="Режим работы",
        items=[
            SelectOption(label="Быстрый", value="fast").model_dump(),
            SelectOption(label="Точный", value="precise").model_dump()
        ],
        default="fast",
        group="Настройки"
    )]
    
    # Чекбокс
    save_history: Annotated[bool, CheckboxInput(
        title="Сохранять историю",
        description="Сохранять диалог для последующего анализа",
        default=True,
        group="Опции"
    )]
    
    # Загрузка одного файла
    document: Annotated[str, FileInput(
        title="Документ",
        file_extensions=".pdf,.docx,.txt",
        view="button"  # или "dropzone" для drag-and-drop,
        max_size_mb=15.0 # ограничение максимального размера для одного файла
    )]

    # Загрузка нескольких файлов
    attachments: Annotated[List[str], FilesInput(
        title="Прикрепленные файлы",
        file_extensions=".pdf,.csv,.xlsx",
        group="Файлы",
        view="dropzone"  # область перетаскивания файлов,
        max_size_mb=15.0 # ограничение максимального размера для всех файлов
    )]

Функции для создания схемы

SDK предоставляет доступ к следующим функциям.

Тип	Описание	Основные параметры
MainInput	Основное поле ввода	placeholder, visibility
StringInput	Текстовое поле	default, title, description, hidden, depends, visibility
StringArrayInput	Массив строк	placeholder, title, description, group, hidden, depends, visibility
StringArrayInputInline	Массив строк в одной строке ввода	placeholder, title, description, group, hidden, depends, visibility
NumberInput	Числовое поле	default, title, description, hidden, depends, visibility
SelectInput	Выпадающий список	items, title, group, default, hidden, depends, visibility
CheckboxInput	Чекбокс	title, group, description, default, hidden, depends, visibility
SwitchInput	Переключатель	title, group, description, default, hidden, depends, visibility
FileInput	Загрузка одного файла	title, file_extensions, group, hidden, depends, view, visibility, max_size_mb
FilesInput	Загрузка нескольких файлов	title, file_extensions, group, hidden, depends, limit, view, visibility, max_size_mb

Управление видимостью полей

Используйте параметр visibility, с помощью которого можно изменять видимость поля в интерфейсе.

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

Параметр принимает значения:

from agent_lab_sdk.schema import Visibility

# Значения для управления видимостью полей в интерфейсе
Visibility.ALWAYS       # "always" - значение по умолчанию. Поле всегда доступно для ввода
Visibility.START        # "start" - поле доступно для ввода только при запуске агента
Visibility.AFTER_START  # "after_start" - поле доступно для ввода после запуска агента

Пример изменения видимости:

class AgentConfig(BaseModel):
    # Всегда доступно для ввода поле
    query: Annotated[str, MainInput(
        placeholder="Введите запрос",
        visibility=Visibility.ALWAYS
    )]

    # Поле доступно для ввода только при первом запуске
    api_key: Annotated[str, StringInput(
        title="API ключ",
        description="Ключ для доступа к внешнему API",
        visibility=Visibility.START
    )]

    # Поле появляется после первого сообщения
    session_id: Annotated[str, StringInput(
        title="ID сессии",
        description="Идентификатор текущей сессии",
        visibility=Visibility.AFTER_START,
        hidden=True
    )]

Вы можете передавать строковые значения напрямую:

title: Annotated[str, StringInput(
    title="Заголовок",
    visibility="always"  # эквивалентно Visibility.ALWAYS
)]

Группировка полей

Для логической группировки полей в интерфейсе используйте параметр group:

class TaskConfig(BaseModel):
    # Группа "Основные параметры"
    task_type: Annotated[str, SelectInput(
        title="Тип задачи",
        items=[...],
        group="Основные параметры"
    )]
    
    priority: Annotated[str, SelectInput(
        title="Приоритет",
        items=[...],
        group="Основные параметры"
    )]
    
    # Группа "Дополнительно"
    notifications: Annotated[bool, CheckboxInput(
        title="Уведомления",
        group="Дополнительно"
    )]
    
    tags: Annotated[List[str], StringArrayInput(
        placeholder="Теги...",
        group="Дополнительно"
    )]

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

Интерфей диалога

Примеры сообщений и отображение их в чате с агентом