NPM-пакет worken

Пакет worken — официальный TypeScript SDK для Worken. В него входят:

• API-клиент — типизированные обёртки для всех REST-эндпоинтов Worken
• MCP-сервер — хостинг инструментов для Worken-агентов через Model Context Protocol
• TUI — подключение к любому агенту прямо из терминала

Установка

npm install worken
# или
bun add worken

Требования: Node.js 20+ или Bun 1.1+

---

API-клиент

Инициализация

import { WorkenClient } from 'worken'

const worken = new WorkenClient({
  apiKey: process.env.WORKEN_API_KEY,
  baseUrl: 'https://api.worken.ru',  // опционально, по умолчанию
})

Боты

// Список всех ботов
const bots = await worken.bots.list()

// Создать бота
const bot = await worken.bots.create({ name: 'Бот поддержки' })

// Получить бота
const bot = await worken.bots.get(botId)

// Обновить настройки
await worken.bots.settings.update(botId, {
  ai: {
    instruction: 'Ты полезный ассистент.',
    model: { id: 'openai/gpt-4o-mini', temperature: 0.5 },
  },
})

// Клонировать бота (удобно для A/B-тестирования)
const clone = await worken.bots.clone(botId)

// Удалить
await worken.bots.delete(botId)

Чаты и треды

// Список чатов
const chats = await worken.chats.list()

// Список тредов в чате
const threads = await worken.chats.threads.list(chatId)

// Стриминг ответа
const stream = await worken.chats.threads.stream(chatId, threadId, {
  messages: [{ role: 'user', content: 'Привет!' }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk.textDelta ?? '')
}

// Получить сообщения
const messages = await worken.chats.threads.messages.list(chatId, threadId)

// Установить режим треда
await worken.threads.setMode(threadId, 'manual')

// Отправить сообщение оператора
await worken.threads.send(threadId, { text: 'Передаю ваш вопрос специалисту.' })

События в реальном времени

// Подписка на события всех тредов проекта
const stream = worken.threads.events()

for await (const event of stream) {
  if (event.type === 'message.created') {
    console.log(`Новое сообщение в треде ${event.thread_id}`)
  }
}

// Или для конкретного треда
const stream = worken.threads.events(threadId)

Интеграции

// Список интеграций
const integrations = await worken.integrations.list()

// Создать Telegram-интеграцию
const integration = await worken.integrations.create({
  name: 'Telegram поддержка',
  vendor: 'telegram',
  auth_data: { token: process.env.TELEGRAM_TOKEN },
})

// Проверить учётные данные
const profile = await worken.integrations.getProfile(integration.id)

// Создать и активировать чат
const chat = await worken.integrations.chats.create(integration.id, {
  bot_id: botId,
  name: 'Поддержка клиентов',
})
await worken.integrations.chats.setStatus(integration.id, chat.id, 'active')

Биллинг

const account = await worken.billing.getAccount()
console.log(`Баланс: ${account.credits} кредитов`)

const transactions = await worken.billing.transactions.list({ limit: 10 })

// Создать счёт для пополнения
const { payment_url } = await worken.billing.invoices.create({ offer_id: 'starter' })
console.log('Ссылка для оплаты:', payment_url)

---

Хостинг MCP-инструментов

Model Context Protocol (MCP) позволяет расширить возможности Worken-агентов собственными инструментами. Инструменты могут обращаться к базам данных, вызывать внешние API, создавать тикеты — любая логика на ваш выбор.

Как это работает

Ваш сервер (worken mcp)  ←→  Worken-агент (via MCP)  ←→  Диалог с пользователем

Агент вызывает ваши инструменты во время генерации ответа. MCP-сервер работает в вашей инфраструктуре — вы полностью контролируете код и доступ к данным.

Создание MCP-сервера

import { WorkenMcpServer } from 'worken/mcp'
import { z } from 'zod'

const server = new WorkenMcpServer({
  name: 'my-tools',
  version: '1.0.0',
})

// Зарегистрировать инструмент
server.tool(
  'get_order_status',
  'Получить статус заказа по его ID',
  {
    order_id: z.string().describe('ID заказа для поиска'),
  },
  async ({ order_id }) => {
    const order = await db.orders.findById(order_id)
    if (!order) return { status: 'not_found' }
    return {
      status: order.status,
      estimated_delivery: order.estimatedDelivery,
      tracking_url: order.trackingUrl,
    }
  }
)

server.tool(
  'create_support_ticket',
  'Создать тикет поддержки по проблеме клиента',
  {
    subject: z.string(),
    description: z.string(),
    priority: z.enum(['low', 'medium', 'high']).default('medium'),
    customer_email: z.string().email().optional(),
  },
  async (params) => {
    const ticket = await helpdesk.create(params)
    return { ticket_id: ticket.id, url: ticket.url }
  }
)

// Запустить сервер (HTTP/SSE транспорт по умолчанию)
await server.listen({ port: 3100 })
console.log('MCP-сервер запущен на http://localhost:3100/mcp')

Подключить сервер к боту

После деплоя зарегистрируйте URL MCP-сервера в настройках бота:

await worken.bots.settings.update(botId, {
  ai: {
    tools: {
      get_order_status: 'auto',            // агент вызывает автоматически
      create_support_ticket: 'user_approve', // спрашивает пользователя
    },
    mcp_servers: [
      { url: 'https://tools.yourcompany.com/mcp' },
    ],
  },
})

Политики подтверждения инструментов

Политика	Поведение
auto	Агент вызывает инструмент без подтверждения
user_approve	Агент показывает карточку подтверждения пользователю
operator_approve	Агент приостанавливается и уведомляет оператора

Запуск через stdio-транспорт (для разработки)

bunx worken mcp --tools ./tools/index.ts --transport stdio

// tools/index.ts
import { defineTool } from 'worken/mcp'
import { z } from 'zod'

export const getWeather = defineTool({
  name: 'get_weather',
  description: 'Получить текущую погоду в городе',
  input: z.object({ city: z.string() }),
  run: async ({ city }) => {
    const res = await fetch(`https://wttr.in/${city}?format=j1`)
    const data = await res.json()
    return { temperature: data.current_condition[0].temp_C, city }
  },
})

---

TUI — интерфейс в терминале

TUI позволяет общаться с любым Worken-агентом прямо из терминала. Удобно для:

• Отладки поведения агента в процессе разработки
• Быстрых диалогов без открытия браузера
• Написания автоматизированных тест-сценариев

Интерактивный режим

bunx worken chat

TUI предложит выбрать проект и бота, затем откроет интерактивную сессию:

┌─────────────────────────────────────────────────────┐
│  Worken TUI  •  Бот поддержки  •  thread_01j...      │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Ассистент: Привет! Как я могу вам помочь?          │
│                                                     │
│  Вы: Какая у вас политика возврата?                 │
│                                                     │
│  Ассистент: Мы принимаем возвраты в течение 30     │
│  дней с момента покупки. Товар должен быть в        │
│  оригинальном состоянии. Хотите оформить возврат?   │
│                                                     │
├─────────────────────────────────────────────────────┤
│  > Введите сообщение...                   [Ctrl+C]  │
└─────────────────────────────────────────────────────┘

Подключение к конкретному боту

Пропустите диалог выбора, передав ID бота напрямую:

bunx worken chat --bot bot_01j...

Или установите бота по умолчанию для проекта:

bunx worken config set default-bot bot_01j...
bunx worken chat  # теперь всегда открывает этого бота

Программный TUI (для скриптов)

Используйте класс WorkenTui для автоматизированных взаимодействий — интеграционных тестов, демо-сценариев:

import { WorkenTui } from 'worken/tui'

const tui = new WorkenTui({
  apiKey: process.env.WORKEN_API_KEY,
  botId: 'bot_01j...',
})

const session = await tui.start()

const reply = await session.send('Какая у вас политика возврата?')
console.log(reply.text)

await session.send('Хочу вернуть товар, купленный на прошлой неделе.')
// Выводит потоковый ответ в stdout

await session.end()

Просмотр памяти треда

bunx worken memory --thread thread_01j...

Выводит рабочую память агента для треда — полезно для отладки того, что модель сохранила о пользователе.

Просмотр истории диалога

bunx worken history --thread thread_01j... --limit 50

---

Справочник CLI

Все команды принимают --api-key для переопределения переменной окружения.

bunx worken --help

Использование: worken <команда> [опции]

Команды:
  chat          Начать интерактивную сессию чата
  mcp           Запустить MCP-сервер инструментов
  history       Вывести историю сообщений треда
  memory        Вывести рабочую память треда
  bots          Управление ботами (list, create, delete)
  config        Просмотр/установка локальной конфигурации

Опции:
  --api-key     API-ключ Worken (по умолчанию: $WORKEN_API_KEY)
  --project     ID проекта (по умолчанию: первый проект)
  --bot         ID бота
  --thread      ID треда
  --format      Формат вывода: table | json (по умолчанию: table)
  --version     Показать версию
  --help        Показать справку

Примеры

# Список всех ботов проекта
bunx worken bots list

# Создать бота и вывести его ID
bunx worken bots create --name "Демо-бот" --format json | jq .id

# Следить за событиями тредов в реальном времени
bunx worken threads events --follow

# Запустить MCP-сервер из файла инструментов
bunx worken mcp --tools ./tools/index.ts --port 3100

# Однократный тест из скрипта
echo "Привет!" | bunx worken chat --bot bot_01j... --no-interactive

---

Конфигурационный файл

CLI читает настройки из ~/.config/worken/config.json:

{
  "apiKey": "sk-...",
  "defaultProject": "proj_01j...",
  "defaultBot": "bot_01j...",
  "baseUrl": "https://api.worken.ru"
}

Или задайте значения интерактивно:

bunx worken config set api-key sk-...
bunx worken config set default-bot bot_01j...

---

TypeScript-типы

Все типы экспортируются из корневого пакета для использования в вашем коде:

import type {
  Bot,
  BotSettings,
  Chat,
  Thread,
  Message,
  Integration,
  IntegrationVendor,
  BillingAccount,
  Transaction,
} from 'worken'