Timelix Chat

Timelix Chat — это слой, который принимает сообщение пользователя и решает, куда отправить его дальше: в N8N, TanStack AI, внешний Agent Server или Codex runtime.

Главная точка входа: app/api/agent/chat/route.ts.

Что делает основной роут

POST /api/agent/chat:

• авторизует запрос
• загружает блок роли агента и её дочерние модули
• определяет backend-модуль
• собирает finalSystemPrompt, инструменты и execution context
• проксирует ответ обратно в единый NDJSON/stream-friendly формат

Как определяется backend агента

Порядок зашит в коде и важен:

1. agentServerUrl прямо в content роли
2. дочерний контейнер AgentServer
3. дочерний контейнер N8nConnector
4. дочерний контейнер TanStackAI
5. дочерний контейнер CodexConnector

Если ничего из этого не найдено, чат вернёт NO_CONNECTOR.

Способы авторизации

Роут поддерживает три рабочих сценария:

• обычная session auth
• widget token через X-Widget-Token или widgetToken
• server-to-server proactive trigger через X-Proactive-Trigger и внутренний secret

Это позволяет использовать один и тот же backend для веба, виджетов и внутренних scheduled сценариев.

Что собирается перед отправкой в runtime

Независимо от backend-а, Timelix Chat старается собрать одинаковую базу:

• finalSystemPrompt из getRoleDataForN8nOptimized()
• история сообщений
• agent-specific tools через loadToolsForAgentById()
• mcpServerUrl с userId, agentId, при наличии todoListId и timezone
• execution context для tools
• RAG-контекст, если он включён у пользователя и для агента есть документы

Подробно про этот слой: Timelix Context.

Поддерживаемые backend-модули

N8N Connector

Timelix отправляет webhook payload в webhookUrl и может добавить туда:

• roleData
• agentId
• todoListBlockId
• mcpServerUrl
• ragContext
• историю чата

Этот путь остаётся основным для workflow-автоматизации и кастомной бизнес-логики. Подробности: N8N и автоматизация.

TanStackAI

Встроенный runtime внутри приложения. Используется, когда модель и tool execution должны жить прямо в Next.js-контуре.

Agent Server

Timelix собирает полный payload и отправляет его во внешний runtime POST {serverUrl}/chat. Туда уезжают:

• сообщения
• systemPrompt
• provider, model, enableThinking
• tool definitions
• mcpServerUrl
• сериализованный context

Подробности по отдельному сервису: Agent Server.

CodexConnector

Для ChatGPT subscription / WHAM-потока Timelix использует отдельный Codex flow: OAuth токены пользователя, convertToolsToOpenAI(), tool loop и вызовы через proxy в Agent Server.

Legacy и debug-слой

Наряду с новым модульным роутом в кодовой базе остаётся старое семейство TimelixChat endpoint-ов:

• POST /api/timelixchat/private
• GET /api/timelixchat/debugPrompt
• GET|POST /api/timelixchat/previewPrompt

Этот слой:

• исторически был N8N-centric
• до сих пор полезен для prompt/debug tooling
• местами ещё используется клиентскими поверхностями, в том числе mobile/legacy flows

Но каноническая modular entrypoint для агентского чата сегодня — именно /api/agent/chat.

Типичные вопросы

Почему один и тот же UI может ходить в разные backend-ы?

Потому что Timelix Chat работает как маршрутизатор по конфигурации роли, а не как прямой прокси к одной модели.

Почему tools не вызываются снаружи напрямую?

Потому что модель получает только definitions, а фактическое исполнение данных Timelix идёт через MCP-сервер Timelix или локальный tool runtime.

Почему prompt в debug и в реальном запросе должен совпадать?

Потому что и новый, и legacy слой опираются на одну и ту же генерацию role data и finalSystemPrompt.

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

• Timelix Tools — как подмешиваются инструменты
• Timelix Context — как собирается prompt и контекст
• От чата до модели и инструментов — end-to-end поток на уровне продукта