Данные в текстовых агентах

Текстовый агент может читать и сохранять записи в данных проекта. Процессы, агенты и страница «Данные» работают с одними и теми же записями.

Это не память агента: записи удаляются по окончании срока хранения; для фактов о собеседнике используйте Память агента.

Когда это полезно

• Читать статус заказа, сохранённый процессом.
• Сохранять заявки, чтобы их обработал процесс или менеджер.
• Не выдать один промокод дважды.

Настройка доступа

В настройках агента в разделе Данные проекта включите доступ и задайте два списка: коллекции для чтения и коллекции для изменения.

• Право на изменение включает чтение; повторно указывать такую коллекцию в списке для чтения не нужно.
• Хотя бы в одном списке должна быть коллекция: пустой список не означает доступ ко всем коллекциям. В каждом списке можно указать не более 20 коллекций.
• Коллекцию можно выбрать или ввести вручную, даже если её ещё нет. Агенту доступны только коллекции из списков.

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

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

Инструменты агента

Инструмент	Аргументы и действие	Доступность
datastore_get	collection, key — читает запись по точному ключу	Есть коллекция для чтения или изменения
datastore_list_keys	collection, prefix — возвращает до 50 ключей с заданным началом	Есть коллекция для чтения или изменения
datastore_set	collection, key, value_json — создаёт или перезаписывает запись	Есть коллекция для изменения
datastore_claim	collection, key, value_json — пытается занять ключ и сохранить значение	Есть коллекция для изменения

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

Если подходящих ключей больше 50, datastore_list_keys сообщает об этом, но следующей страницы у него нет — стройте ключи так, чтобы по их началу можно было сузить поиск (client-7781-…, 2026-09-…).

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

Занять ключ для агента

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

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

Инструкции для агента

Как пользоваться инструментами, платформа объясняет агенту сама. В инструкциях агента опишите ваши данные:

• Какие коллекции что содержат и как устроены их ключи.
• Когда читать и сохранять данные.
• Какую структуру JSON записывать.
• Какие действия нельзя повторять и какой ключ проверять перед ними.
• Что делать при ошибке.

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

Примеры

• Статус заказа: агент только читает orders по номеру заказа и сообщает найденный статус; при отсутствии записи не придумывает его.
• Промокод: перед применением агент вызывает datastore_claim с кодом в качестве ключа и продолжает, только если claimed:true.

Процессы и публикации

Нода «Агент» использует настройки доступа агента. Настройки входят в снапшот публикации, а записи — нет: после изменения настроек создайте новую публикацию.

Ограничения

• Инструменты доступны только текстовым агентам; пользовательские функции не имеют доступа к хранилищу.
• Агент не выбирает срок хранения, не удаляет записи и не выполняет запросы с условиями.
• datastore_list_keys возвращает не больше 50 ключей за вызов и не поддерживает следующую страницу.
• Если у агента уже есть функция, инструмент MCP-сервера или процесс с таким же именем, как у инструмента данных, остаётся прежний инструмент, а инструмент данных агент не получает.
• Вызов инструмента данных длится не больше 30 секунд.
• Общие ограничения хранилища описаны в разделе Ограничения.

Ошибки

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