В «Новостном агенте» нет форм управления — значит, управление должно быть где-то ещё. Оно есть: это набор команд, которыми агент меняет настройки, запускает проверки и готовит публикации. Именно этот набор делает продукт управляемым, а не «настроенным один раз и забытым».
Зачем API
API (программный доступ) — это язык, на котором ваш ИИ-агент разговаривает с продуктом. Через него добавляются источники, ставятся пороги, задаются правила и оповещения, готовятся черновики и запускаются проверки. Человеку учить этот язык не нужно: за него говорит агент, а вы говорите с агентом обычными словами.
Знание устройства API нужно в двух случаях: если вы работаете без ИИ-агента совсем или если подключаете продукт к своей системе.
Ключ управления
Ключ управления задаётся при установке переменной окружения NEWSAGENT_MANAGEMENT_KEY. Хранится не сам ключ, а его необратимый отпечаток — так, что по настройкам сервера исходный ключ не восстановить.
- Пока ключ не задан, изменения запрещены — любой запрос на изменение честно отвечает, что управление агентом выключено. Чтение при этом работает.
- Запрос с ключом получает право менять всё — читать, править настройки, запускать проверки и публикации.
- Ключ — это доступ ко всему продукту, поэтому обращаться с ним стоит как с паролем администратора.
Кто что может
- Человек в интерфейсе — только смотреть и отмечать: «прочитано», «в избранное». Это осознанное ограничение, а не недоделка.
- Агент с ключом управления — менять настройки, запускать и ставить на паузу расписание, готовить черновики, повторять отправки, убирать архив.
- Читатели лент — получать опубликованное по адресу с токеном, и больше ничего.
Справочник для агента
Есть адрес /api/news/docs, который отдаёт сам себя: перечень команд, описание всех файлов настроек и десять готовых сценариев работы агента — от «подключить источник» до «собрать утреннюю сводку». Этот адрес открыт без ключа, но ничего секретного не показывает: он только объясняет, как устроено управление.
Практический смысл: агент, которому вы дали адрес продукта и ключ, дальше разбирается сам. Не нужно пересказывать ему документацию — он её прочитает в первоисточнике.
Самопроверка
Адрес /api/news/health показывает состояние продукта: работает ли расписание проверок, следит ли он за изменениями файлов, жива ли отправка сообщений, сколько задач ИИ стоит в очереди и доступна ли база. Это первый адрес, куда стоит смотреть при любом «а почему тишина».
Что доступно агенту
- Расписание — весь план проверок одним запросом, общая пауза и возврат к работе, в том числе с автоматическим возвратом через заданное время.
- Немедленный запуск — сводка или публикация по расписанию прямо сейчас; ручной запуск не сбивает расписание.
- Повторная обработка — попросить заново сделать краткое содержание или оценку значимости, дополнить текст статьи целиком.
- Работа с материалами и событиями — объединить повторы, скрыть событие из ленты, убрать материал, закрепить исходное значение монитора.
- Оповещения — посмотреть удержанные сообщения, отпустить их вручную, отправить тестовое сообщение по каналу.
- Публикации — собрать черновик, одобрить, отправить, снять с публикации, посмотреть историю версий.
- Настройки — правки с проверкой, копией и журналом; возврат к прежней версии.
- Обслуживание — уборка архива по срокам хранения, отдельное сохранение страницы в архив.
Ограничения частоты и размеров
- Не больше 120 изменений в минуту на ключ — защита от случайного шквала запросов. При превышении продукт отвечает «слишком часто» и подсказывает, когда повторить.
- Ограничения на размер запросов: настройки — до 256 килобайт, приём материалов — до 1 мегабайта, задание на публикацию — до 16 килобайт. Слишком большой запрос отклоняется с объяснением.
- Чтение не ограничивается — сколько угодно просмотров и проверок состояния.
Честные отказы
Если чего-то сделать нельзя, продукт отвечает словами и объясняет причину: «черновик не создан — в материалах не нашлось подтверждённых цитат», «страница во внешнем архиве не найдена», «канал не проверен — сначала отправьте тестовое сообщение». Молчания и загадочных ошибок тут нет: ответ всегда говорит, что произошло и что делать дальше.
Отдельно и важное: проверяйте не только то, что запрос прошёл, но и то, что в ответе. Честные отказы приходят как обычный успешный ответ — с объяснением внутри.
Живые обновления для агента
Агент с ключом управления получает те же живые уведомления, что и интерфейс: появилось событие, пришёл материал, изменился статус отправки, готова публикация. Поэтому внешняя система может реагировать сразу, а не опрашивать продукт каждую минуту: «новое событие — обнови карточку в CRM».
Дальше → Чат с ИИ-агентом и команды