---
title: "Управление агентом по API"
id: "2048"
type: "page"
slug: "api"
published_at: "2026-09-28T03:48:43+00:00"
modified_at: "2026-09-28T04:00:22+00:00"
url: "https://pastukhov.com/agents/news/docs/api"
markdown_url: "https://pastukhov.com/agents/news/docs/api.md"
excerpt: "В «Новостном агенте» нет форм управления — значит, управление должно быть где-то ещё. Оно есть:…"
---

# Управление агентом по API

[https://pastukhov.com/agents/news/docs/api.md](https://pastukhov.com/agents/news/docs/api.md)

В «Новостном агенте» нет форм управления — значит, управление должно быть где-то ещё. Оно есть: это набор команд, которыми агент меняет настройки, запускает проверки и готовит публикации. Именно этот набор делает продукт управляемым, а не «настроенным один раз и забытым».

## Зачем API

API (программный доступ) — это язык, на котором ваш ИИ-агент разговаривает с продуктом. Через него добавляются источники, ставятся пороги, задаются правила и оповещения, готовятся черновики и запускаются проверки. Человеку учить этот язык не нужно: за него говорит агент, а вы говорите с агентом обычными словами.

Знание устройства API нужно в двух случаях: если вы работаете без ИИ-агента совсем или если подключаете продукт к своей системе.

## Ключ управления

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

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

## Кто что может

- **Человек в интерфейсе** — только смотреть и отмечать: «прочитано», «в избранное». Это осознанное ограничение, а не недоделка.
- **Агент с ключом управления** — менять настройки, запускать и ставить на паузу расписание, готовить черновики, повторять отправки, убирать архив.
- **Читатели лент** — получать опубликованное по адресу с токеном, и больше ничего.

## Справочник для агента

Есть адрес `/api/news/docs`, который отдаёт сам себя: перечень команд, описание всех файлов настроек и десять готовых сценариев работы агента — от «подключить источник» до «собрать утреннюю сводку». Этот адрес открыт без ключа, но ничего секретного не показывает: он только объясняет, как устроено управление.

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

## Самопроверка

Адрес `/api/news/health` показывает состояние продукта: работает ли расписание проверок, следит ли он за изменениями файлов, жива ли отправка сообщений, сколько задач ИИ стоит в очереди и доступна ли база. Это первый адрес, куда стоит смотреть при любом «а почему тишина».

## Что доступно агенту

- **Расписание** — весь план проверок одним запросом, общая пауза и возврат к работе, в том числе с автоматическим возвратом через заданное время.
- **Немедленный запуск** — сводка или публикация по расписанию прямо сейчас; ручной запуск не сбивает расписание.
- **Повторная обработка** — попросить заново сделать краткое содержание или оценку значимости, дополнить текст статьи целиком.
- **Работа с материалами и событиями** — объединить повторы, скрыть событие из ленты, убрать материал, закрепить исходное значение монитора.
- **Оповещения** — посмотреть удержанные сообщения, отпустить их вручную, отправить тестовое сообщение по каналу.
- **Публикации** — собрать черновик, одобрить, отправить, снять с публикации, посмотреть историю версий.
- **Настройки** — правки с проверкой, копией и журналом; возврат к прежней версии.
- **Обслуживание** — уборка архива по срокам хранения, отдельное сохранение страницы в архив.

## Ограничения частоты и размеров

- **Не больше 120 изменений в минуту на ключ** — защита от случайного шквала запросов. При превышении продукт отвечает «слишком часто» и подсказывает, когда повторить.
- **Ограничения на размер запросов:** настройки — до 256 килобайт, приём материалов — до 1 мегабайта, задание на публикацию — до 16 килобайт. Слишком большой запрос отклоняется с объяснением.
- **Чтение не ограничивается** — сколько угодно просмотров и проверок состояния.

## Честные отказы

Если чего-то сделать нельзя, продукт отвечает словами и объясняет причину: «черновик не создан — в материалах не нашлось подтверждённых цитат», «страница во внешнем архиве не найдена», «канал не проверен — сначала отправьте тестовое сообщение». Молчания и загадочных ошибок тут нет: ответ всегда говорит, что произошло и что делать дальше.

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

## Живые обновления для агента

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

Дальше → [Чат с ИИ-агентом и команды](/agents/news/docs/agent)

[← Оглавление документации](/agents/news/docs)