База данных агента¶

База данных агента даёт вашему агенту собственные структурированные данные — таблицы записей, которые он читает и пополняет по ходу работы. Вам не нужно проектировать базу данных или писать SQL. Она нужна для того, что не умеет база знаний: запоминать, сохранять и обновлять отдельные записи со временем.

Используйте её, когда агенту нужно что-то отслеживать, например:

Сбор заявок / CRM — кто обратился, его контакты и статус.
Заказы и бронирования — принять заказ или бронь и сохранить её.
Опросы и тесты — собирать ответы и баллы.
Прогресс пользователя — помнить, на чём остановился каждый пользователь.
Структурированный каталог или FAQ — искать позиции по полям, а не полнотекстовым поиском.
Журнал событий — добавлять запись каждый раз, когда что-то происходит.

Как это настроить¶

Вам не нужно описывать таблицы или выбирать типы столбцов. Вы своими словами говорите, что агент должен отслеживать («запоминай имя и email каждого клиента и то, связались ли мы с ним»), а билдер сам проектирует таблицы и включает возможность База данных. В первый раз он спрашивает у вас подтверждение.

Это обычная возможность агента, поэтому инструмент «База данных» находится среди инструментов агента рядом с памятью, субагентами и остальным, и там же его можно включить или выключить.

Вкладка «Данные»¶

Когда база данных включена, у агента появляется вкладка Данные, где можно смотреть записи, которые он сохранил, и управлять ими, — табличное представление в духе электронной таблицы:

Просматривайте записи с фильтрацией и сортировкой.
Экспортируйте таблицу в CSV.
Смотрите, сколько места занимают данные агента.

Просмотр доступен всегда. Напрямую редактировать или удалять отдельные строки в этом представлении можно только в режиме отладки, потому что в обычной работе данные меняет агент, а не человек, щёлкающий по таблице. Удаление записи в этом представлении удаляет её, и каждое изменение и удаление записывается в журнал.

Чьи записи вы видите¶

В таблицах с режимом только свои записи вкладка «Данные» показывает ваши собственные записи и записи без владельца. Если агент принадлежит организации, где вы Владелец или Администратор, она показывает и записи участников этой организации. Записи других людей остаются закрытыми для всех, кроме них: вкладка «Данные» не показывает, не экспортирует, не редактирует и не удаляет их, а строка под заголовком таблицы сообщает, сколько записей скрыто.

Таблицы, которые вы открыли для чтения автору, и таблицы без ограничения «только свои записи» показывают все записи. Люди, которым вы дали право Может редактировать, видят таблицы, их столбцы и число записей, но не сами записи. Аналитик читает таблицу так же, когда вы даёте её ему как источник.

Изменение таблиц агента, в котором уже есть данные¶

Когда билдер меняет структуру существующей базы данных — новая таблица, новый столбец, — изменение применяется к рабочим данным агента, поэтому оно либо проходит целиком, либо не проходит вовсе:

Пока изменение применяется, агент приостановлен. Уже идущие запуски сначала завершаются, новые ждут.
Если какая-то часть изменения не удалась, обновление помечается как неудачное, и агент остаётся приостановленным. Текущей остаётся версия, которая работала до этого. Ваши записи не затрагиваются, а существующие данные и история разговоров остаются доступными для чтения.
Повторять безопасно. Каждое изменение таблиц, которое делает платформа, записывается в собственную базу данных агента в момент его выполнения, поэтому повторная попытка знает, что уже прошло: она доделывает незавершённые части и никогда не применяет одно и то же изменение дважды. Это верно независимо от того, было ли изменение прервано до, во время или после применения.

Один вид изменения схемы нельзя откатить автоматически: построение индекса без блокировки таблицы приходится выполнять вне страховки платформы. Если оно прервётся на середине, агент остаётся приостановленным, а обновление просит человека проверить результат, а не гадать, — платформа никогда не повторяет его вслепую.

Самостоятельно размещённые установки

Некоторые самостоятельно размещённые установки запускают базу данных агента в однопользовательском (single-tenant) режиме, где платформа не может гарантировать, что изменение схемы выполнилось ровно один раз. Там применение пакета, добавляющего новые изменения базы данных, к уже существующему агенту сразу отклоняется с объяснением. Создание нового агента из того же пакета работает как обычно, как и обновление агента пакетом, который не меняет таблицы. Облачной платформы Агента Атом это не касается.

Отметки времени у каждой записи¶

Каждая запись автоматически хранит два момента, так что вы и ваш агент всегда знаете, когда что произошло, и никому не нужно задавать их вручную:

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

Управлять ими не нужно — платформа сама поддерживает их точными, а увидеть их можно на вкладке «Данные».

Если у ваших данных есть собственная значимая дата — например, дата публикации статьи или дата проведения мероприятия, — она хранится в отдельном поле, независимо от того, когда агент сохранил запись. Так два разных вопроса не путаются: «что мы добавили сегодня?» и «что опубликовано сегодня?».

Кто какие записи видит¶

База данных агента автоматически соблюдает права доступа, поэтому конечные пользователи опубликованного агента работают только с теми данными, которые им разрешены:

Конечные пользователи опубликованного агента получают изоляцию по пользователям — каждый видит и редактирует только свои записи. Именно поэтому «запомни мой прогресс» или «покажи мои заказы» безопасно работает, когда одним агентом пользуется много людей.
Владелец, а также Владельцы и Администраторы организации владельца — это сторона автора. Когда агент работает для них, он видит все записи таблиц, открытых для всех или закрытых для конечных пользователей, но в таблицах с режимом «только свои записи» — только их собственные записи, если таблица не открыта для чтения автору.
Человек, которому вы дали право «Может редактировать», создаёт агента вместе с вами, но когда агент работает для него, он относится к нему как к любому другому человеку: в таблицах с таким режимом тот видит свои записи, а не записи людей, которые пользуются агентом. Изменение таблиц, которое он просит у билдера, по-прежнему выполняется с правами владельца базы данных на структуру таблиц и на таблицы без режима «только свои записи», но не может читать или менять чужие записи в таблицах с режимом «только свои записи». Давайте право Может редактировать тем, кому доверяете остальные данные.
Билдер работает с базой данных от имени того, кто создаёт агента, включая владельца: когда он проверяет или загружает записи, он видит только то, что этот человек может видеть как пользователь агента. Чтобы загрузить каталог или FAQ, который пользователи только читают, он добавляет строки в рамках изменения таблиц, а не как пользователь.

Для каждой таблицы можно задать политику доступа — могут ли конечные пользователи её читать и/или записывать в неё, и касается ли это только их собственных записей или шире. Так можно сделать, например, каталог, который могут читать все, а обновлять только агент, рядом с таблицей заказов, разделённой по пользователям.

Менять доступ к таблице на вкладке «Данные» может только владелец. Человек с правом Может редактировать может попросить билдер открыть таблицу для всех авторизованных только пока она пуста; когда в ней появились записи, открыть её решает владелец, потому что это показало бы строки каждого человека всем пользователям. А когда в таблице с режимом «только свои записи» появились записи других людей, ослабить её не может никто, включая владельца.

Изоляция на уровне строк — зона ответственности платформы. Изменение таблиц, которое пишет билдер, не может создать, изменить или удалить правила, разделяющие записи разных людей, отключить их или выполнить SQL, собранный на лету; билдер отказывается от такого изменения и вместо этого задаёт доступ через политику таблицы.

Таблица, в которую могут записывать все авторизованные, — это одно общее пространство: любой из них может изменить любую строку, и по строкам не видно, кто их записал. Вы как автор видите в ней все записи, а люди, которые пользуются агентом, узнают об этом до начала работы. Записи, которые люди туда добавили, остаются в агенте, когда они уходят. Храните персональные данные в таблицах с режимом «только свои записи».

Запуск обращается к базе данных от имени того человека, которому он принадлежит, — в чате, голосом, через API-ключ и на каждом шаге воркфлоу. Поэтому воркфлоу, запущенный посетителем, видит записи этого посетителя, а не владельца. Код собственного бэкенда агента тоже не выбирает себе доступ: каждый обслуживаемый им запрос несёт вошедшего человека, который его сделал, база данных применяет права этого человека, а код, пытающийся действовать от имени кого-то другого, получает отказ. Запрос к бэкенду без вошедшего человека вообще не получает доступа к базе данных.

Новая таблица изначально закрыта для конечных пользователей. Единственное исключение — таблица со столбцом владельца: она изначально в режиме «только свои записи», так что каждый видит только свои строки. Любая другая таблица остаётся закрытой, пока билдер или вы сознательно её не откроете, например сделаете каталог доступным для чтения всем авторизованным. Так никто случайно не увидит чужие данные.

Таблицы, открытые для чтения автору¶

Некоторые агенты существуют, чтобы собирать записи, которые нужно читать автору, — CRM, журнал пациентов, отправленные формы. Для таблицы с режимом «только свои записи» можно разрешить стороне автора — вам и Владельцам и Администраторам вашей организации — читать записи всех людей: включите Автор может читать записи всех — это показывается посетителям до начала работы в настройках доступа таблицы на вкладке Данные или попросите билдер. Каждый, кто пользуется агентом, узнаёт об этом до начала работы (см. С чем соглашаются посетители). Каждый человек по-прежнему меняет только свои записи, а люди с правом Может редактировать чужих записей там никогда не видят.

Решайте, пока таблица пуста. Когда в таблице с режимом «только свои записи» появились записи других людей, никто — включая вас — не может открыть её для чтения автору, переключить в другой режим или сменить её столбец владельца. Для данных, которые вы хотите читать, создайте новую таблицу.

Таблицы, которые уже работали так до появления этой настройки, были автоматически открыты для чтения автору, а людей, пользующихся такими агентами, спрашивают об этом один раз.

Самостоятельно размещённые установки

В некоторых самостоятельно размещённых установках база данных агента работает в однопользовательском режиме, где база данных не разделяет записи. Там в том, с чем соглашаются посетители, сказано, что автор может читать все таблицы.

Общая база данных команды¶

Команда агентов может использовать одну общую базу данных в дополнение к собственной базе каждого агента. Её таблицы создаёт билдер ведущего агента, а читают и записывают их все агенты-участники.

Действует та же политика доступа по таблицам — чтение / запись: никто, владелец, все авторизованные или только свои записи — и та же изоляция по пользователям для конечных пользователей: конечные пользователи опубликованного агента-участника видят в таблицах «только свои записи» лишь свои записи. Когда агент-участник работает для владельца или для Владельца или Администратора организации владельца, он видит все записи общих таблиц, кроме чужих записей в таблицах с режимом «только свои записи», — если таблица не открыта для чтения автору.

На вкладке «Данные» ведущего агента есть режим Команда, где показаны общие таблицы, их строки, экспорт и редактор политики доступа. В общих таблицах с режимом «только свои записи» владелец команды видит свои записи и записи без владельца; остальные подсчитываются, но не показываются. Кнопка Данные на странице команд сразу открывает этот режим.

Приложение, созданное для агента-участника, читает и записывает общие таблицы так же, как собственные, — билдер делает это, когда вы просите («форма сохраняет ответы в общую таблицу команды»).

Закрытая сторона администратора, открытая сторона формы

Не публикуйте саму команду, а опубликуйте отдельно агента, который собирает данные. Респонденты записывают свои записи через опубликованного агента. Чтобы сторона администратора видела их все, откройте общую таблицу для чтения автору, пока она ещё пуста, — респонденты узнают об этом до начала работы.

Примечание

Таблицы, существовавшие до появления этой функции, продолжают работать. При первом использовании каждая получает то же значение по умолчанию, что и новая таблица, — «только свои записи», если в таблице есть столбец владельца, иначе закрыта для конечных пользователей, — и ведущий агент может потом его изменить.

Старого хранилища состояния больше нет

У агентов, которые хранили данные в старом хранилище «ключ — значение» (state store), и у страниц, которые его читали, его больше нет: хранилище и инструмент, который в него писал, удалены, а их записи не перенесены. Попросите билдер перенести то, что агент там хранил, в базу данных.

Как отключить¶

Базу данных можно отключить — тогда все данные сохраняются, но у агента пропадает возможность «База данных», — или удалить данные навсегда; для этого нужно ввести подтверждение, чтобы избежать случайностей. Удалить данные навсегда может только владелец; человек с правом Может редактировать может только отключить базу данных.