Notion открыл External Agent API и Workers: новый паттерн интеграции агентов

Я – Денис Шохирев, архитектор AI из Эрлангена. В DennisCraft AI Studio я собираю агентные стек-решения для DACH-клиентов в логистике, финтехе и промышленной автоматизации: Claude, Supabase, n8n, Doppler, self-hosted Postgres. За последние полгода внедрил 14 продакшен-агентов. Недавно столкнулся с задачей: клиент на DACH-рынке требует прямой интеграции AI-агентов в корпоративный Notion с учётом аудита и прозрачности. На демо-продуктах это казалось невозможным без костылей, но в мае 2024 Notion открыл External Agent API и Workers, меняя подход к интеграции агентов в реальные B2B-процессы. Ниже — подробный разбор паттерна на боевом стеке без хайпа.

External Agent API: что реально изменилось

Раньше интеграция LLM-агентов с Notion сводилась к синхронизации через Zapier, костыльные webhooks или промежуточные базы. Это приводило к потере контекста, дублированию задач и невозможности реализовать цепочки с несколькими агентами. С мая 2024 Notion официально поддерживает External Agent API [документация], позволяя регистрировать внешние агенты, подписывать их на workspace-ивенты и управлять сессиями в реальном времени.

Ключевые изменения:

• Внешний агент становится first-class citizen Notion (может инициировать, модифицировать и завершать рабочие задачи).
• Возможна подписка на granular-ивенты (update, delete, comment, mention) без polling.
• Сессии агентов логируются с traceability по workspace-правилам. Это критично для аудита.
• Появился workflow-паттерн: цепочка агентов с разными ролями (например, генерация отчёта → юрист-агент проверяет на compliance → интеграция с внутренним CRM).

Notion Workers: оркестрация цепочек агентов

Workers — это серверные функции, исполняемые в инфраструктуре Notion. Они позволяют запускать сложные цепочки действий по триггеру событий или запросу агента. Для меня это решило две болевые точки:

• Оркестрация нескольких агентов без внешних orchestrator'ов (n8n теперь только для кросс-продуктовых сценариев).
• Прозрачная передача контекста между агентами: каждый шаг цепочки имеет доступ к результатам предыдущих и к workspace-permissions.

Пример: согласование AI-генерируемого отчёта

import requests

NOTION_API = "https://api.notion.com/v1/agents"
headers = {"Authorization": "Bearer x-secret"}

def approve_report(report_id):
    # Проверка отчёта юрист-агентом через External Agent API
    response = requests.post(
        f"{NOTION_API}/legal/review",
        json={"report_id": report_id}
    )
    return response.json()

def main(event):
    if event["action"] == "generate_report":
        report = generate_report(event["data"])
        approval = approve_report(report["id"])
        if approval["status"] == "approved":
            send_to_crm(report)

В этом кейсе юридический агент работает как отдельная сущность, подписанная на workspace-ивенты. Сценарий полностью прозрачен для аудита и соответствует требованиям DACH-клиентов.

Преимущества нового паттерна для AI-стека

Практические нюансы интеграции

Безопасность: что проверять на старте

• Лимитировать права агента через scopes Notion API. Не давать доступ к пользовательским данным без строгого обоснования.
• Работать с секретами через Doppler, не хранить токены в коде. На одном из недавних проектов сгенерированный агент случайно попал в public-репозиторий — gitleaks это поймал, но спасло только быстрое ротация токена.
• Сделать статический анализ (semgrep, bandit) для всего кода взаимодействия с Notion API.

Логирование и аудит

Все действия агента логируются в Notion по workspace-правилам. Это снимает часть требований по отдельному хранению audit trail, особенно для финтех- и compliance-кейсов.

RAG и работа с внешними источниками

Agent API не ограничивает вас только Notion-данными. Можно строить Rag-цепочки: агент собирает данные из Postgres, обрабатывает через Claude, результат логирует через Worker в Notion. Главное — не нарушать workspace-permissions: все внешние данные должны явно маркироваться по источнику.

FAQ

Какой стек оптимален для интеграции с Notion Agent API?

Я использую Python (requests, FastAPI), Claude (Anthropic SDK), n8n для внешних цепочек, Supabase для хранения метаданных, Doppler для секретов. Всё деплоится на self-hosted VPS в DACH-регионе.

Как сделать аудит действий агента для комплаенса?

Notion логирует все действия агента (create, update, comment) в workspace-логи. Для глубокого аудита рекомендую дополнительно писать действия в отдельную таблицу Postgres с user_id, agent_id и timestamp.

Есть ли ограничения по скорости/объёму запросов?

Да, Notion API лимитирует количество запросов (rate limit — 3 запроса в секунду на workspace, документация). Для крупных цепочек делайте батчинг и exponential backoff.

Как подключить несколько агентов к одной задаче?

Через workflow Workers: каждый агент подписывается на нужный тип события (например, "сгенерирован отчёт" → "юридическая проверка" → "интеграция в CRM"). Все шаги видны в audit trail.

Что важнее: интеграция в Notion или через внешние orchestrator'ы?

Для сценариев внутри workspace — однозначно Notion API + Workers. Для кросс-системных цепочек (например, интеграция с SAP) — внешний orchestrator (n8n, Airflow) остаётся ключевым.

В вашей практике: какой шаг цепочки агентов чаще всего требует ручной проверки в продакшене — генерация данных, юридический аудит или интеграция с внешними системами? Напишите, если сталкивались с похожими задачами. Провожу бесплатный 30-мин аудит AI-стека для DACH-компаний: пишите в LinkedIn или на @ger_dennis_ai.