worken npm package

The worken package is the official TypeScript SDK for Worken. It includes:

• API client — typed wrappers for all Worken REST endpoints
• MCP server — host your own tools and expose them to Worken agents via the Model Context Protocol
• TUI — connect to any Worken agent from the terminal for interactive sessions and debugging

Installation

npm install worken
# or
bun add worken

Requirements: Node.js 20+ or Bun 1.1+

---

API Client

Initialisation

import { WorkenClient } from 'worken'

const worken = new WorkenClient({
  apiKey: process.env.WORKEN_API_KEY,
  baseUrl: 'https://api.worken.ru',  // optional, default
})

Bots

// List all bots
const bots = await worken.bots.list()

// Create a bot
const bot = await worken.bots.create({ name: 'Support Bot' })

// Get a bot
const bot = await worken.bots.get(botId)

// Update settings
await worken.bots.settings.update(botId, {
  ai: {
    instruction: 'You are a helpful assistant.',
    model: { id: 'openai/gpt-4o-mini', temperature: 0.5 },
  },
})

// Clone a bot (useful for A/B testing)
const clone = await worken.bots.clone(botId)

// Delete
await worken.bots.delete(botId)

Chats & Threads

// List chats
const chats = await worken.chats.list()

// List threads in a chat
const threads = await worken.chats.threads.list(chatId)

// Stream a response
const stream = await worken.chats.threads.stream(chatId, threadId, {
  messages: [{ role: 'user', content: 'Hello!' }],
})

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

// Get messages
const messages = await worken.chats.threads.messages.list(chatId, threadId)

// Set thread mode
await worken.threads.setMode(threadId, 'manual')

// Send an operator message
await worken.threads.send(threadId, { text: 'Escalating to a human agent.' })

Real-time events

// Subscribe to all thread events in the project
const stream = worken.threads.events()

for await (const event of stream) {
  if (event.type === 'message.created') {
    console.log(`New message in thread ${event.thread_id}`)
  }
}

// Or for a single thread
const stream = worken.threads.events(threadId)

Integrations

// List integrations
const integrations = await worken.integrations.list()

// Create a Telegram integration
const integration = await worken.integrations.create({
  name: 'Telegram Support',
  vendor: 'telegram',
  auth_data: { token: process.env.TELEGRAM_TOKEN },
})

// Check credentials
const profile = await worken.integrations.getProfile(integration.id)

// Create and activate a chat
const chat = await worken.integrations.chats.create(integration.id, {
  bot_id: botId,
  name: 'Customer Support',
})
await worken.integrations.chats.setStatus(integration.id, chat.id, 'active')

Billing

const account = await worken.billing.getAccount()
console.log(`Balance: ${account.credits} credits`)

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

// Create a top-up invoice
const { payment_url } = await worken.billing.invoices.create({ offer_id: 'starter' })
console.log('Pay here:', payment_url)

---

MCP Tool Hosting

The Model Context Protocol (MCP) lets you expose custom tools to Worken agents. Tools can look up data, call external APIs, write to databases — anything your business logic requires.

How it works

Your server (worken mcp)  ←→  Worken agent (via MCP)  ←→  User conversation

The Worken agent calls your tools during inference. The MCP server runs in your infrastructure — you control the code and data access.

Creating an MCP server

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

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

// Register a tool
server.tool(
  'get_order_status',
  'Look up the status of a customer order by order ID',
  {
    order_id: z.string().describe('The order ID to look up'),
  },
  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',
  'Create a support ticket for a customer issue',
  {
    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 }
  }
)

// Start the server (HTTP/SSE transport by default)
await server.listen({ port: 3100 })
console.log('MCP server running on http://localhost:3100/mcp')

Register the server with your bot

After deploying your MCP server, register its URL in the bot's tool settings:

await worken.bots.settings.update(botId, {
  ai: {
    tools: {
      get_order_status: 'auto',           // agent calls automatically
      create_support_ticket: 'user_approve', // asks user before calling
    },
    mcp_servers: [
      { url: 'https://tools.yourcompany.com/mcp' },
    ],
  },
})

Tool approval policies

Policy	Behaviour
auto	Agent calls the tool without confirmation
user_approve	Agent shows a confirmation card to the end user
operator_approve	Agent pauses and notifies the operator for approval

Running with stdio transport (for local development)

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: 'Get current weather for a city',
  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 — Terminal UI

The TUI lets you chat with any Worken agent directly from your terminal. It is useful for:

• Debugging agent behaviour during development
• Quick conversations without opening the browser
• Scripting automated test dialogues

Interactive mode

bunx worken chat

The TUI will prompt you to select a project and a bot, then open an interactive chat session:

┌─────────────────────────────────────────────────────┐
│  Worken TUI  •  Support Bot  •  thread_01j...        │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Assistant: Hello! How can I help you today?        │
│                                                     │
│  You: What is your return policy?                   │
│                                                     │
│  Assistant: Our return policy allows returns        │
│  within 30 days of purchase. Items must be in       │
│  original condition. Would you like me to start     │
│  a return request?                                  │
│                                                     │
├─────────────────────────────────────────────────────┤
│  > Type your message...                   [Ctrl+C]  │
└─────────────────────────────────────────────────────┘

Connect to a specific bot

Skip the selection prompts by passing a bot ID:

bunx worken chat --bot bot_01j...

Or set the bot as the default for the project:

bunx worken config set default-bot bot_01j...
bunx worken chat  # now always opens that bot

Programmatic TUI (scripting)

Use the WorkenTui class for automated interactions — integration tests, demo scripts, etc.:

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('What is your return policy?')
console.log(reply.text)

await session.send('I want to return an item I bought last week.')
// Prints streamed response to stdout

await session.end()

Inspect thread memory

bunx worken memory --thread thread_01j...

Prints the agent's working memory for that thread — useful for debugging what the model has retained.

View conversation history

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

---

CLI reference

All commands accept --api-key to override the environment variable.

bunx worken --help

Usage: worken <command> [options]

Commands:
  chat          Start an interactive chat session
  mcp           Start an MCP tool server
  history       Print thread message history
  memory        Print working memory for a thread
  bots          Manage bots (list, create, delete)
  config        Get/set local configuration

Options:
  --api-key     Worken API key (default: $WORKEN_API_KEY)
  --project     Project ID (default: first project)
  --bot         Bot ID
  --thread      Thread ID
  --format      Output format: table | json (default: table)
  --version     Show version
  --help        Show help

Examples

# List all bots in the project
bunx worken bots list

# Create a bot and print its ID
bunx worken bots create --name "Demo Bot" --format json | jq .id

# Tail live thread events
bunx worken threads events --follow

# Start MCP server from a tools file
bunx worken mcp --tools ./tools/index.ts --port 3100

# Run a single-turn test from a script
echo "Hello!" | bunx worken chat --bot bot_01j... --no-interactive

---

Configuration file

The CLI reads from ~/.config/worken/config.json:

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

Or set values interactively:

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

---

TypeScript types

All types are exported from the root package for use in your own code:

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