Что такое робот
Агент — это манифест + реализация. Манифест перечисляет, что робот обещает: функции, триггеры, схему входов и правила. Реализация работает поверх модулей платформы (documents, tasks, cases, invoices, mail, retention, bridge) и не имеет сети наружу, кроме явно разрешённых адаптеров.
{
"id": "doc-detect",
"name": "Dokument-Erkennung",
"category": "documents",
"functions": ["Typ-Erkennung", "Kanal-Zuordnung", "Übergabe an Fach-Agenten"],
"triggers": ["document.created", "manual"],
"inputs": { "documentId": "uuid (optional)", "fileName": "string" },
"config": { "channels": { "invoice": "finance", "contract": "legal" } }
}Идентификатор из манифеста — стабильный ключ: doc-detect, invoice-check, gdpr-guard. По нему запускается робот, ведутся журнал и права.
Что гарантирует рантайм
Агент работает только в контексте текущего тенанта. Все чтения и записи проходят через RLS — чужие данные недоступны.
Каждый запуск — строка agent_runs: кто, когда, с какими входами и что получилось. produced-объекты тоже в журнале.
Повторная доставка того же файла или события не создаёт второй документ: проверка по внешнему ключу и хешу.
Нет данных — ok=false и понятный summary, а не фейковый успех. Отказ — штатный ответ, а не ошибка HTTP.
«Документ не найден», «Сканера нет: установите sane-utils» — штатные результаты. Обработчик должен читать summary и produced, а не только HTTP-код.
Семь каналов, один контракт
Канал выбирает не агент, а внешняя среда. Письмо, скан, файл из папки и REST-запрос приходят к одному и тому же роботу через доменное событие — поэтому подключение новой системы не требует нового кода агента.
Прямой REST
Когда: Любая среда, которая умеет HTTP.
Что нужно: Каталог, манифест, запуск и журнал. Права agents.view / agents.run, Bearer-токен.
Исходящие вебхуки
Когда: Инициатор — платформа: «что-то произошло».
Что нужно: Подпись HMAC-SHA256, очередь с retry. Получатель отвечает 2xx и обязан быть идемпотентным.
Входящие триггеры
Когда: Инициатор — внешняя система: пришёл файл или событие.
Что нужно: POST /api/v1/documents:ingest, Idempotency-Key, доменное событие → манифестные триггеры.
Email-вход
Когда: Старые ERP, кассы, сотрудники умеют только письма.
Что нужно: IMAP-ящик → mail.received → mail-accept. Ответы — через SMTP после подтверждения.
Папка и сканер
Когда: Сканер, сетевая шара, legacy-экспорт.
Что нужно: SANE или FOLDER через desktop-bridge. Файл, Idempotency-Key, дедупликация по SHA-256.
Очередь / мост
Когда: ESB, сервисная шина, межсистемный шлюз.
Что нужно: Очередь webhook_events + api-bridge. Маршруты по правилам, каждый перенос в аудите.
Офлайн JSON / CSV
Когда: Изолированный контур без сети.
Что нужно: Экспорт журнала agent_runs, импорт файлов через scan-папку или ingest. Это снимки, а не живой канал.
Legacy-система не умеет HTTP? Поставьте перед ней тонкую обёртку, локальный скрипт с тем же контрактом inputs → {ok, summary, produced} или полуавтоматический режим: робот готовит, человек подтверждает.
Права, подписи, человек
Аутентификация и права
- Люди — сессия платформы, проверки
@PreAuthorizeна контроллерах. - Машины — API-токены (scope, лимит запросов, срок). Значение показывается один раз, хранится только хеш.
- Устройства —
X-Device-Key: показывается один раз, читается из окружения, не логируется. - Каталог и журнал —
agents.view, запуск —agents.run. Выдавайте раздельно.
Тенантность и границы
tenant_id есть в каждой бизнес-таблице, RLS включён в режиме ENABLE + FORCE. Контекст тенанта берётся из сессии, а не из тела запроса — внешняя система не может «попроситься» в чужой тенант.
Входящие вебхуки проверяются до чтения тела: X-BC-Signature = hex(HMAC-SHA256(secret, timestamp + "." + body)). Метка времени защищает от replay, сравнение — с постоянным временем. Неподписанный запрос отклоняется целиком.
Что агент никогда не делает сам
| Действие | Правило | Пример |
|---|---|---|
| Удаление персональных данных | Только план; стирание — отдельный акт человека | gdpr-guard |
| Удаление по срокам хранения | Только отчёт о кандидатах, без исполнения | retention |
| Деструктивные внешние изменения | Только шаг плана с подтверждением владельца | data-sync |
Сеть наружу агенту закрыта, кроме разрешённых адаптеров (mail/CalDAV/API-мосты). Робот не может «тихо» отправить данные стороннему сервису.
Чек-лист пилота
- 01
Определите категорию
Найдите процесс в каталоге и проверьте поле implemented: манифест может быть, а рабочая реализация — ещё в работе.
- 02
Выберите канал
От возможностей внешней среды: REST → вебхуки → email → папка → офлайн. Не наоборот.
- 03
Выдайте минимум прав
agents.view и agents.run — раздельно. Для документов — API-токен со scope documents:write, лимитом и сроком.
- 04
Настройте приём
Ingest с X-Filename / Idempotency-Key, IMAP-ящик или scan-папку. Проверьте, что событие создаёт ожидаемый доменный триггер.
- 05
Настройте доставку результата
Вебхук с секретом HMAC и идемпотентным обработчиком либо ночная JSON/CSV-выгрузка журнала.
- 06
Прогоните пробный запуск
POST …/run на реальных данных тенанта. Прочитайте ok, summary и produced — не полагайтесь на побочные эффекты.
- 07
Проверьте идемпотентность
Доставьте один и тот же файл или событие дважды. Второй раз должен вернуться существующий объект, а не дубль.
- 08
Проверьте отказ
Оборвите сеть на доставке: retry не должен терять скан и не должен задваивать событие. ok=false — повод для мониторинга, не для паники.
8 категорий → типовые среды
Ориентир для выбора первого контура. Внутри категории роботы отличаются входами и правилами, но говорят с внешней средой через один и тот же контракт.
| Категория | Типовые среды | Вход | Роботов |
|---|---|---|---|
| Документы и данные | DMS / ECM · Сканеры и МФУ · Сетевые папки · Архив | Scan-папка / desktop-bridge | 10 |
| Коммуникации | IMAP / SMTP · Почтовые шлюзы · Legacy-ERP «только письма» | Email-вход / выход | 8 |
| Финансы | Бухгалтерия / ERP · Банк и выписки · DATEV-экспорт | REST | 8 |
| Процессы | Task / ITSM · CalDAV / ICS · BPM-контур | Исходящие вебхуки | 6 |
| Комплаенс | Юридический контур · Архив / retention · Privacy-модуль | REST (планы и отчёты) | 5 |
| Аналитика | BI / дашборды · DWH / отчётность · Руководство и контроллинг | REST | 5 |
| CRM | CRM · Marketing / Sales · Customer Service | Вебхуки | 5 |
| Интеграции | ESB / сервисная шина · API-шлюзы · Мониторинг | Очередь webhook_events | 3 |
Запуск: запрос и ответ
Правило простое: запустили → получили runId → прочитали ok / summary / produced → при необходимости запросили журнал. Это единственный путь, по которому интеграция узнаёт результат.
Authorization: Bearer $TOKEN
Content-Type: application/json
{
"trigger": "invoice.imported",
"inputs": {
"rawText": "Rechnung Nr. RE-2026-0042 …",
"record": "true"
}
}{
"runId": "9b1e…",
"ok": true,
"summary": "Счёт RE-2026-0042: поставщик Nordlicht GmbH, 1 428,00 € брутто.",
"produced": [
{ "kind": "invoice", "ref": "inv_7f31c2", "label": "Входящий счёт" },
{ "kind": "task", "ref": "task_19b0", "label": "Проверка счёта" }
]
}Журнал: GET /api/v1/agents/{id}/runs?limit=20. Экспорт для офлайн-контура — тот же журнал, JSON или CSV.
Проверка
Один процесс.
Один канал. Один робот.
Начните с пилота на реальных данных, проверьте idempotency и отказ, а затем расширяйте парк. Каталог и демо уже открыты.