N8N и автоматизация

Как Timelix отправляет webhook, передаёт mcpServerUrl и принимает ответ от workflow

N8N — отдельная ветка исполнения агента, где Timelix отправляет webhook с полным контекстом, а workflow решает бизнес-логику, может вызвать MCP Timelix и затем возвращает ответ в приложение.

Поток из приложения

sequenceDiagram
  participant UI as Клиент Timelix
  participant API as api/agent/chat
  participant N8 as N8N webhook
  participant MCP as api/agent/mcp
 
  UI->>API: сообщение, agentId, tabId
  API->>API: roleData, todoListBlockId, mcpServerUrl
  API->>N8: POST JSON payload
  N8->>MCP: опционально tools/call
  MCP-->>N8: результат tools
  N8-->>API: ответ
  API-->>UI: JSON или NDJSON stream

Для N8N каноническая точка входа в Timelix сегодня та же, что и для остальных модулей: Timelix Chat через POST /api/agent/chat.

Что уходит в webhook

В handleN8nAgent и callN8n Timelix отправляет на webhook, среди прочего:

{
  "lastMessage": "Текст последнего сообщения пользователя",
  "roleData": {
    "id": "agent-uuid",
    "name": "Имя агента",
    "systemPrompt": "Системная инструкция агента...",
    "model": "claude-opus-4-6",
    "webhookUrl": "https://n8n.example.com/webhook/...",
    "ragEnabled": false
  },
 
  "mcpServerUrl": "https://app.timelix.ru/api/agent/mcp?token=xxx",
 
  "agentId": "agent-uuid",
  "todoListBlockId": "block-uuid",
  "ragContext": "Релевантные фрагменты из базы знаний агента (если RAG включён)"
}

Описание полей

Поле	Тип	Описание
`lastMessage`	`string`	Последнее сообщение пользователя
`userId` / `tabId`	`string`	Контекст пользователя и вкладки
`roleData`	`object`	Полная конфигурация роли и финальный prompt
`chatHistory`	`array`	История сообщений без пустых элементов
`mcpServerUrl`	`string`	Готовый URL MCP со всеми query-параметрами
`agentId`	`string`	ID агента для runtime и MCP
`todoListBlockId`	`string`	ID todo-листа компании агента
`ragContext`	`string`	Результаты RAG-поиска, если он включён

Часть полей дублируется во вложенном объекте body, чтобы старые N8N workflow могли читать их как $json.body.mcpServerUrl.

Использование MCP в N8N

Поле mcpServerUrl лучше использовать целиком, не собирая query вручную. Так вы не потеряете todoListId и timezone.

Его можно передать в AI-ноду N8N или в MCP Client для работы с инструментами Timelix:

// В Code ноде N8N
const mcpUrl = $input.first().json.mcpServerUrl;
 
// Передать в AI Agent ноду как MCP endpoint
return {
  mcpEndpoint: mcpUrl,
  systemPrompt: $input.first().json.roleData.systemPrompt,
  userMessage: $input.first().json.lastMessage,
};

Практические рекомендации

Используйте mcpServerUrl из payload как готовую строку.
Если workflow сам строит MCP URL, обязательно передавайте agentId, иначе набор инструментов может отличаться.
Обрабатывайте non-2xx ответы от Timelix: чат логирует тело ошибки, и по нему проще понять, где сломалась цепочка.

Типичный workflow

Webhook Trigger
    ↓
Code Node (подготовить промпт)
    ↓
AI Agent Node
  ├── MCP Tool: readTodos    ← читает задачи из Timelix
  ├── MCP Tool: getDoc       ← читает документы и планы
  ├── MCP Tool: appendDoc    ← дописывает память / заметки
  └── MCP Tool: sendTelegramMessage
    ↓
Respond to Webhook (вернуть ответ в Timelix)

Конкретный набор MCP tools зависит от конфигурации роли агента. По умолчанию это mcpPreset, а дополнительные built-in инструменты вроде readEpics / getEpicDetails подключаются отдельно.

Формат ответа

N8N должен вернуть ответ в одном из форматов:

Простой текст

{
  "output": "Ответ агента в виде текста"
}

Streaming (NDJSON)

Если N8N возвращает NDJSON (для потоковых ответов):

{"type":"text","text":"Начало "}
{"type":"text","text":"ответа..."}
{"type":"done"}

Timelix ожидает ответ от N8N в течение стандартного timeout. Для долгих операций используйте асинхронные workflow с callback через Telegram или другой канал.

Как настроить агента

В AgentEditor:

Перейдите на вкладку Personality
В поле Webhook URL укажите URL вашего N8N webhook
Установите тип бэкенда: N8N Connector
Сохраните агента

После этого все сообщения пользователю будут проксироваться через N8N.

Как сюда попадает RAG

Если у агента включён RAG, Timelix выполняет поиск по базе знаний и добавляет результаты в поле ragContext. Workflow может встроить его в системный prompt:

const systemPrompt = roleData.systemPrompt;
const ragContext = body.ragContext;
 
const fullPrompt = ragContext
  ? `${systemPrompt}\n\nКонтекст из базы знаний:\n${ragContext}`
  : systemPrompt;

Связанные разделы

Timelix Chat — как выбирается N8N-модуль
Timelix Context — как собираются roleData, ragContext и timezone
MCP-сервер Timelix — как N8N вызывает инструменты Timelix

N8N и автоматизация

On this page