Основные понятия

Действия и MCP

Действия

Действия (в бэкенде их также называют инструментами) — это функции, которые ваши агенты могут выполнять для взаимодействия с внешними системами и сервисами. Они расширяют возможности ваших агентов за пределы языковой модели.Встроенные действия:

Название	Описание	Требует настройки	Варианты поставщиков
Внутренний поиск	Поиск по проиндексированным документам и базе знаний вашей организации	Да	Встроен, компоненты можно заменять
Веб-поиск	Поиск информации в интернете в реальном времени и по текущим событиям	Да	Srezai, Exa, Serper, Brave, Google PSE, SearXNG, Tavily, Firecrawl
Выполнение кода	Выполнение кода на Python, анализ данных и построение визуализаций	Нет	Встроено
Генерация изображений	Создание изображений по текстовому описанию с помощью ИИ-моделей	Да	OpenAI, Azure OpenAI, Google Vertex AI, RouterAI, Polza.AI
Агент по коду ^Beta	Исследует публичный репозиторий GitHub и отвечает на вопросы о нём	Да (по умолчанию отключён)	Встроен

Пользовательские действия:

Интеграции API: подключение к внешним REST API
Операции с базами данных: запросы и обновление баз данных
Автоматизация рабочих процессов: запуск бизнес-процессов
Операции с файлами: чтение, запись и обработка файлов

Собственные пользовательские действия можно определить в панели администратора с помощью спецификации OpenAPI.

MCP

Model Context Protocol (MCP) — открытый стандарт, который позволяет ИИ-ассистентам безопасно получать доступ к внешним источникам данных и инструментам. Yahont можно настроить как клиент MCP, чтобы управляемо взаимодействовать с внешними системами, базами данных и API.Ключевые возможности MCP:

Доступ к внешним данным: подключение к базам данных, API и файловым системам
Аутентификация: сквозная передача OAuth для безопасного доступа к вашему MCP-серверу.

(Расширенное) Пользовательские встроенные действия

Иногда нужно больше контроля над действием, чем позволяет пользовательское действие. Поскольку Yahont — проект с открытым исходным кодом, вы можете расширить встроенные действия по своему усмотрению!Шаблоны встроенных действий находятся в backend/onyx/tools/tool_implementations в репозитории Yahont.

Расширение кодовой базы не рекомендуется большинству пользователей. Прежде чем начать, обратитесь к нам за поддержкой в Telegram!

Агенты

Агенты — это ИИ-ассистенты с пользовательскими инструкциями, действиями и доступом к данным, расширяющие возможности базовой LLM.

Термины ассистент (Assistant) и агент (Agent) в Yahont используются как взаимозаменяемые и обозначают одно и то же понятие.

Встроенные агенты:

id: 0 Search Agent — использует инструмент поиска, чтобы отвечать на вопросы по вашей базе знаний
id: -1 General Agent — базовый чат без инструментов (обычный чат с LLM)
id: -2 Paraphrase Agent — использует инструмент поиска и цитирует точные фрагменты из источников
id: -3 Art Agent — создаёт изображения и визуальный контент

Вы можете создавать собственных агентов в панели администратора или через API.Для большинства конечных точек чата нужен ID агентаЧтобы найти ID агента, можно:

Использовать конечную точку API GET /persona для вывода списка всех агентов
В панели администратора: открыть агента и посмотреть первое число в URL

Чат

Потоковые ответы чата

Система ответов чата использует пакетную архитектуру для доставки ответов пользователям в реальном времени. Вместо ожидания полного ответа система разбивает взаимодействие в чате на отдельные пакеты, которые передаются постепенно.Каждый пакет имеет единую структуру, определённую классом Packet:

class Packet(BaseModel):
  ind: int        # Sequential index for ordering
  obj: PacketObj  # The actual content including type of packet

Поток передачи:

Запрос чата запускает процесс потоковой передачи
В зависимости от нужных операций создаются пакеты разных типов (рассуждения, вызовы инструментов, ответ ИИ, документы, цитаты и т. д.)
Пакеты отправляются с последовательными индексами, чтобы сохранить порядок
Фронтенд обрабатывает пакеты в реальном времени и обновляет интерфейс
Пакет OverallStop сигнализирует о завершении

Базовые пакеты сообщений

MessageStart и MessageDeltaЭти пакеты составляют основу системы потоковых ответов:

MessageStart: начинает новое сообщение с начальным содержимым и итоговыми найденными документами (если они есть)
MessageDelta: доставляет текст по мере его создания

Управляющие пакеты

Управление сессией и разделамиУправляющие пакеты определяют ход и жизненный цикл потоковой передачи:

OverallStop: сигнализирует о конце всей сессии потоковой передачи
SectionEnd: отмечает завершение типа пакетов (рассуждения, сообщение, цитаты и т. д.)

Пакеты инструментов

Ответы инструментов передаются так же, как основной ответ сообщения.Инструменты поиска

SearchToolStart и SearchToolDelta обрабатывают операции поиска документов

Генерация изображений

ImageGenerationToolStart, ImageGenerationToolDelta и ImageGenerationToolHeartbeat управляют созданием изображений ИИ

Пользовательские инструменты

CustomToolStart и CustomToolDelta используются для MCP и пользовательских действий

Пакет start сигнализирует о начале ответа инструмента. Пакеты delta передают результаты по мере их появления.

Пакеты рассуждений

Все шаги рассуждений передаются потоком, чтобы фронтенд мог отображать их по мере обработки. Пакеты рассуждений, как правило, отправляются первыми.

ReasoningStart: начинает раздел рассуждений
ReasoningDelta: передаёт процесс рассуждений ИИ

Пакеты цитат

Пакеты цитат связывают ID цитат с ID документов.

CitationStart: начинает результаты цитирования
CitationDelta: доставляет цитаты и ссылки на источники

Коннекторы

Когда вы видите термин коннектор в Yahont или в другом месте этой документации, обычно имеются в виду ConnectorCredentialPairs

Коннекторы

Connectors в Yahont определяют данные, которые вы хотите индексировать

name: на самом деле не отображается в интерфейсе, если задано ConnectorCredentialPairMetadata:name
source: к какой системе подключаться (см. раскрывающийся блок DocumentSource ниже)
input_type: как Connector получает данные (см. раскрывающийся блок InputType ниже)
connector_specific_config: настройки конкретного источника, например пути к папкам или каналы. Ожидаемые настройки конкретного коннектора смотрите в /backend/onyx/connectors.
refresh_freq: как часто проверять новое или обновлённое содержимое, в секундах
prune_freq: как часто удалять устаревшее содержимое из Yahont, в секундах
indexing_start: необязательная дата и время начала индексации

Python

class ConnectorBase(BaseModel):
  name: str
  source: DocumentSource
  input_type: InputType
  connector_specific_config: dict[str, Any]
  refresh_freq: int | None = None
  prune_freq: int | None = None
  indexing_start: datetime | None = None

Учётные данные

Credentials содержат сведения для аутентификации, необходимые для доступа к источникам данных. Это ключи API, токены OAuth, персональные токены доступа (PAT) или учётные данные сервисных аккаунтов, которые позволяют Yahont безопасно подключаться к вашим внешним системам.Типы Credentials:

Ключи API: простая аутентификация по токену
Токены OAuth: делегированная авторизация с возможностью обновления
Сервисные аккаунты: аутентификация между машинами
Персональные токены доступа: учётные данные доступа конкретного пользователя

ConnectorCredentialPairs

За кулисами Connectors и Credentials объединяются в ConnectorCredentialPair (CC-pair, пара «коннектор — учётные данные»). CC-pair — это активное подключение, которое может синхронизировать данные из ваших внешних источников в Yahont. Именно CC-pair вы видите и обслуживаете на странице администратора Connectors.Возможности CC-pair:

Активные подключения: синхронизация данных между источником и Yahont в реальном времени
Мониторинг состояния: отслеживание работоспособности и производительности синхронизации
Управление доступом: определение, кто может видеть данные из этого подключения
Управление конфигурацией: изменение настроек синхронизации и учётных данных

Если вы создаёте Connectors через API, их нужно связать с Credential (CC-pair), чтобы они стали активными!

ConnectorCredentialPairMetadata

ConnectorCredentialPairMetadata определяет настройки конфигурации и доступа для CC-pair.Параметры конфигурации:

name: необязательное отображаемое имя CC-pair (переопределяет имя Connector)
access_type: кто может получать доступ к данным этого CC-pair (см. раскрывающийся блок AccessType ниже)
auto_sync_options: необязательная конфигурация параметров автоматической синхронизации
groups: список ID групп, имеющих доступ к этому CC-pair

Python

class ConnectorCredentialPairMetadata(BaseModel):
  name: str | None = None
  access_type: AccessType
  auto_sync_options: dict[str, Any] | None = None
  groups: list[int] = Field(default_factory=list)

Документы

DocumentBase

DocumentBase — основная структура, используемая в Yahont для хранения данных документов и управления ими. Обратите внимание, что эмбеддинги хранятся в OpenSearch отдельно.

id: уникальный идентификатор. Создаётся Yahont, если не указан
sections: список разделов содержимого (см. TextSection и ImageSection)
source: система, из которой получен документ (см. DocumentSource)
semantic_identifier: отображается в интерфейсе как название документа
metadata: произвольные string или list[string], которые будут сохранены как теги документа
doc_updated_at: метка времени UTC последнего обновления документа
chunk_count: число фрагментов, на которые документ разбивается для обработки
primary_owners: метаданные о людях, связанных с документом
secondary_owners: метаданные о людях, связанных с документом
title: используется для поиска (по умолчанию semantic_identifier, если не указан)
from_ingestion_api: получен ли этот документ через Ingestion API
additional_info: информация, специфичная для коннектора, которая может понадобиться другим частям кода
external_access: данные синхронизации прав (только Enterprise Edition)

Ingestion API расширяет определение DocumentBase полем cc_pair_id, чтобы автоматически связать документ с CC-pair.

Python

class DocumentBase(BaseModel):
  """Used for Yahont ingestion api, the ID is inferred before use if not provided"""

  id: str | None = None
  sections: list[TextSection | ImageSection]
  source: DocumentSource | None = None
  semantic_identifier: str
  metadata: dict[str, str | list[str]]

  doc_updated_at: datetime | None = None
  chunk_count: int | None = None

  primary_owners: list[BasicExpertInfo] | None = None
  secondary_owners: list[BasicExpertInfo] | None = None
  title: str | None = None
  from_ingestion_api: bool = False
  additional_info: Any = None

  external_access: ExternalAccess | None = None

DocumentSource

DocumentSource — перечисление, определяющее допустимые источники документа. Для загрузки файлов в Ingestion API и программного создания Connectors нужно указать DocumentSource.

Python

class DocumentSource(str, Enum):
  INGESTION_API = "ingestion_api"     # Special case, document passed in via Yahont APIs without specifying a source type
  SLACK = "slack"
  WEB = "web"
  GOOGLE_DRIVE = "google_drive"
  GMAIL = "gmail"
  REQUESTTRACKER = "requesttracker"
  GITHUB = "github"
  GITBOOK = "gitbook"
  GITLAB = "gitlab"
  GURU = "guru"
  BOOKSTACK = "bookstack"
  CONFLUENCE = "confluence"
  JIRA = "jira"
  SLAB = "slab"
  PRODUCTBOARD = "productboard"
  FILE = "file"
  NOTION = "notion"
  ZULIP = "zulip"
  LINEAR = "linear"
  HUBSPOT = "hubspot"
  DOCUMENT360 = "document360"
  GONG = "gong"
  GOOGLE_SITES = "google_sites"
  ZENDESK = "zendesk"
  LOOPIO = "loopio"
  DROPBOX = "dropbox"
  SHAREPOINT = "sharepoint"
  TEAMS = "teams"
  SALESFORCE = "salesforce"
  DISCOURSE = "discourse"
  AXERO = "axero"
  CLICKUP = "clickup"
  MEDIAWIKI = "mediawiki"
  WIKIPEDIA = "wikipedia"
  ASANA = "asana"
  S3 = "s3"
  R2 = "r2"
  GOOGLE_CLOUD_STORAGE = "google_cloud_storage"
  OCI_STORAGE = "oci_storage"
  XENFORO = "xenforo"
  NOT_APPLICABLE = "not_applicable"
  DISCORD = "discord"
  FRESHDESK = "freshdesk"
  FIREFLIES = "fireflies"
  EGNYTE = "egnyte"
  AIRTABLE = "airtable"
  HIGHSPOT = "highspot"

  IMAP = "imap"

  # Special case just for integration tests
  MOCK_CONNECTOR = "mock_connector"

TextSection

TextSection — часть документа в Yahont.

text: собственно текстовое содержимое раздела
link: необязательный URL, к которому относится этот текстовый раздел или из которого он получен

Python

class TextSection(Section):
  text: str
  link: str | None = None

ImageSection

ImageSection — изображение, извлечённое из документа в Yahont.

image_file_id: UUID файла изображения, хранящегося в файловом хранилище Yahont
text: необязательное текстовое описание или подпись к изображению
link: необязательный URL, к которому относится этот раздел изображения или из которого он получен

Python

class ImageSection(Section):
  image_file_id: str
  text: str | None = None
  link: str | None = None

AccessType

AccessType определяет, кто может получать доступ к данным Connector в Yahont.

PUBLIC: все пользователи Yahont могут получать доступ к данным этого Connector
PRIVATE: только пользователь, создавший Connector, и указанные группы могут получать доступ к данным этого Connector
SYNC: значение SYNC можно задать только Connectors с поддержкой синхронизации прав. Connector будет синхронизировать права доступа с исходной системой.

Python

class AccessType(str, Enum):
  PUBLIC = "public"
  PRIVATE = "private"
  SYNC = "sync"

InputType

InputType определяет, как Connector получает данные из исходной системы.

LOAD_STATE: однократная загрузка данных из источника
POLL: непрерывный опрос источника на наличие новых данных (начинается с полной загрузки)
EVENT: для большинства Connectors не реализовано
SLIM_RETRIEVAL: для Connectors с синхронизацией прав

Python

class InputType(str, Enum):
  LOAD_STATE = "load_state"
  POLL = "poll"
  EVENT = "event"
  SLIM_RETRIEVAL = "slim_retrieval"

Дальнейшие шаги

Руководство: индексирование файлов с помощью Ingestion API

Узнайте, как индексировать файлы с помощью Ingestion API

Руководство: отправка сообщения чата

Простой пример программной отправки сообщения

Начало работы

Руководства и примеры

Справочник API

Разное

Действия и MCP

Агенты

Чат

Коннекторы

Документы

Дальнейшие шаги

Руководство: индексирование файлов с помощью Ingestion API

Руководство: отправка сообщения чата

​Действия и MCP

​Агенты

​Чат

​Коннекторы

​Документы

​Дальнейшие шаги

Руководство: индексирование файлов с помощью Ingestion API

Руководство: отправка сообщения чата

Действия и MCP

Агенты

Чат

Коннекторы

Документы

Дальнейшие шаги