create-bk-agent 0.15.0

package/README.md

@@ -0,0 +1,43 @@
+# create-bk-agent
+
+Scaffold a new [BackendKit agent](https://github.com/BackendKit-labs/backendkit-agent-framework) project in seconds.
+
+## Usage
+
+```bash
+npx create-bk-agent my-project
+```
+
+```
+✨  create-bk-agent  v0.14.0
+
+? Project name:  my-project
+? Template:      coding — Coding assistant (files, git, code execution)
+? LLM provider:  Anthropic (Claude)
+
+Creating coding agent in ./my-project...
+Installing dependencies...
+
+✅  Done!
+   cd my-project
+   cp .env.example .env
+   npm run dev
+```
+
+## Templates
+
+| Template | Use case |
+|----------|---------|
+| `coding` | Coding assistant — edit files, run commands, search code |
+| `domain-agent` | Multi-agent system — orchestrator + domain specialists |
+| `autonomous` | Autonomous agent — cron schedules, webhooks, events |
+| `mcp-server` | MCP server — expose tools via Model Context Protocol |
+| `minimal` | Bare engine — full control over everything |
+
+## Providers
+
+Supports Anthropic (Claude), OpenAI, DeepSeek / OpenAI-compatible endpoints, and Ollama (local).
+
+## License
+
+MIT © [BackendKit Labs](https://github.com/BackendKit-labs)

package/dist/bin/create-bk-agent.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+(0, index_1.main)(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/src/index.js

@@ -0,0 +1,83 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const prompts_1 = require("./prompts");
+const scaffold_1 = require("./scaffold");
+const FRAMEWORK_VERSION = '0.14.0';
+const NEXT_STEPS = {
+    coding: ['Edit AGENT.md to describe your project', 'npm run dev'],
+    'domain-agent': ['Rename agents/ and tools/ to match your domain', 'Implement tools in src/tools/', 'npm run dev'],
+    autonomous: ['Configure triggers in src/index.ts', 'npm run dev (or npm start in production)'],
+    'mcp-server': ['Register tools in src/server.ts', 'npm run build && npx my-mcp-server'],
+    minimal: ['Implement your LLMProvider in src/index.ts', 'npm run dev'],
+};
+async function main(argv) {
+    const projectArg = argv[2];
+    console.log(`\n✨  create-bk-agent  v${FRAMEWORK_VERSION}\n`);
+    const defaultName = projectArg ?? 'my-agent';
+    const choices = await (0, prompts_1.askQuestions)(defaultName);
+    if (!choices) {
+        console.log('\nCancelled.');
+        process.exit(0);
+    }
+    const targetDir = path.resolve(process.cwd(), choices.projectName);
+    if (fs.existsSync(targetDir)) {
+        console.error(`\n✗  Directory already exists: ${targetDir}`);
+        process.exit(1);
+    }
+    console.log(`\nCreating ${choices.template} agent in ./${choices.projectName} ...`);
+    try {
+        (0, scaffold_1.scaffold)(choices, targetDir);
+    }
+    catch (err) {
+        console.error(`\n✗  ${err.message}`);
+        process.exit(1);
+    }
+    console.log('Installing dependencies...\n');
+    (0, scaffold_1.installDeps)(targetDir);
+    const steps = NEXT_STEPS[choices.template] ?? ['npm run dev'];
+    console.log(`
+✅  Done! Your agent is ready.
+
+   cd ${choices.projectName}
+   cp .env.example .env      # add your API key
+${steps.map(s => `   ${s}`).join('\n')}
+
+Documentation: https://github.com/BackendKit-labs/backendkit-agent-framework
+`);
+}

package/dist/src/prompts.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.askQuestions = askQuestions;
+const prompts_1 = __importDefault(require("prompts"));
+const TEMPLATES = [
+    { title: 'coding', value: 'coding', description: 'Coding assistant — edit files, run commands, search code' },
+    { title: 'domain-agent', value: 'domain-agent', description: 'Multi-agent — orchestrator + domain specialists (e.g. docker, AWS)' },
+    { title: 'autonomous', value: 'autonomous', description: 'Autonomous — activates on cron schedules, webhooks, events' },
+    { title: 'mcp-server', value: 'mcp-server', description: 'MCP server — expose tools via Model Context Protocol' },
+    { title: 'minimal', value: 'minimal', description: 'Minimal — bare engine, full control over everything' },
+];
+const PROVIDERS = [
+    { title: 'Anthropic (Claude)', value: 'anthropic', description: 'claude-sonnet-4-6 recommended' },
+    { title: 'OpenAI', value: 'openai', description: 'gpt-4o recommended' },
+    { title: 'DeepSeek / OpenAI-compatible', value: 'deepseek', description: 'deepseek-chat or any OpenAI-compatible endpoint' },
+    { title: 'Ollama (local)', value: 'ollama', description: 'llama3.2, codellama, qwen2.5 — no API key needed' },
+];
+async function askQuestions(defaultName) {
+    const answers = await (0, prompts_1.default)([
+        {
+            type: 'text',
+            name: 'projectName',
+            message: 'Project name:',
+            initial: defaultName,
+            validate: (v) => v.trim().length > 0 || 'Name cannot be empty',
+        },
+        {
+            type: 'select',
+            name: 'template',
+            message: 'Template:',
+            choices: TEMPLATES.map(t => ({
+                title: t.title.padEnd(14) + ' ' + t.description,
+                value: t.value,
+            })),
+            initial: 0,
+        },
+        {
+            type: 'select',
+            name: 'provider',
+            message: 'LLM provider:',
+            choices: PROVIDERS.map(p => ({
+                title: p.title.padEnd(30) + ' ' + p.description,
+                value: p.value,
+            })),
+            initial: 0,
+        },
+    ], { onCancel: () => { return false; } });
+    if (!answers.projectName || !answers.template || !answers.provider)
+        return null;
+    return answers;
+}

package/dist/src/scaffold.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffold = scaffold;
+exports.installDeps = installDeps;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const TEMPLATES_DIR = path.resolve(__dirname, '../../templates');
+// ── Provider env var hints ────────────────────────────────────────────────────
+const PROVIDER_ENV = {
+    anthropic: { varName: 'ANTHROPIC_API_KEY', placeholder: 'sk-ant-...', model: 'claude-sonnet-4-6' },
+    openai: { varName: 'OPENAI_API_KEY', placeholder: 'sk-...', model: 'gpt-4o' },
+    deepseek: { varName: 'LLM_API_KEY', placeholder: 'sk-...', model: 'deepseek-chat' },
+    ollama: { varName: 'OLLAMA_BASE_URL', placeholder: 'http://localhost:11434', model: 'llama3.2' },
+};
+// ── Copy template ─────────────────────────────────────────────────────────────
+function copyDir(src, dst) {
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const dstPath = path.join(dst, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, dstPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, dstPath);
+        }
+    }
+}
+// ── Substitute project name in package.json ───────────────────────────────────
+function patchPackageJson(dir, projectName) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    pkg.name = projectName;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+// ── Write .env with provider preset ──────────────────────────────────────────
+function writeEnv(dir, provider) {
+    const envExample = path.join(dir, '.env.example');
+    const envFile = path.join(dir, '.env');
+    // Only create .env if .env.example exists and .env doesn't
+    if (!fs.existsSync(envExample) || fs.existsSync(envFile))
+        return;
+    const p = PROVIDER_ENV[provider];
+    const content = `# Generated by create-bk-agent\n${p.varName}=${p.placeholder}\nLLM_PROVIDER=${provider}\nLLM_MODEL=${p.model}\n`;
+    fs.writeFileSync(envFile, content);
+}
+// ── Main scaffold ─────────────────────────────────────────────────────────────
+function scaffold(choices, targetDir) {
+    const templateDir = path.join(TEMPLATES_DIR, choices.template);
+    if (!fs.existsSync(templateDir)) {
+        throw new Error(`Template not found: ${choices.template} (looked in ${templateDir})`);
+    }
+    if (fs.existsSync(targetDir)) {
+        throw new Error(`Directory already exists: ${targetDir}`);
+    }
+    // 1. Copy template files
+    copyDir(templateDir, targetDir);
+    // 2. Patch package.json name
+    patchPackageJson(targetDir, choices.projectName);
+    // 3. Write .env stub
+    writeEnv(targetDir, choices.provider);
+}
+function installDeps(targetDir) {
+    (0, child_process_1.execSync)('npm install', { cwd: targetDir, stdio: 'inherit' });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-bk-agent",
+  "version": "0.15.0",
+  "description": "Create a new BackendKit agent project",
+  "main": "dist/src/index.js",
+  "bin": {
+    "create-bk-agent": "./dist/bin/create-bk-agent.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BackendKit-labs/backendkit-agent-framework.git",
+    "directory": "packages/create-bk-agent"
+  },
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=20.0.0" },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "node scripts/copy-templates.js && npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.4.0"
+  }
+}

package/templates/autonomous/.env.example

@@ -0,0 +1,8 @@
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+
+LLM_PROVIDER=anthropic
+LLM_MODEL=claude-sonnet-4-6
+
+WEBHOOK_PORT=3000
+# WEBHOOK_SECRET=your-secret   # for GitHub/Slack webhook validation

package/templates/autonomous/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "my-autonomous-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Autonomous agent — activates on cron, webhooks, or custom events",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.14.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/autonomous/src/index.ts

@@ -0,0 +1,64 @@
+import 'dotenv/config';
+import { createAutonomousAgent } from '@backendkit-labs/agent-core';
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// ── Agent definition ──────────────────────────────────────────────────────────
+
+const monitorAgent: AgentProfile = {
+    id: 'monitor',
+    name: 'Monitor',
+    icon: '👁',
+    description: 'Monitors events and executes scheduled tasks',
+    allowedTools: [],
+    delegatesTo: [],
+    systemPrompt: `You are an autonomous monitor agent.
+// TODO: describe what this agent monitors and what actions it takes.
+When activated by a trigger, analyze the input and take appropriate action.`,
+};
+
+// ── Provider ──────────────────────────────────────────────────────────────────
+
+const provider = process.env.LLM_PROVIDER ?? 'anthropic';
+const apiKey   = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? '';
+
+if (!apiKey) { console.error('Missing API key'); process.exit(1); }
+
+// ── Autonomous agent ──────────────────────────────────────────────────────────
+
+const agent = createAutonomousAgent({
+    providers:       { [provider]: { apiKey } },
+    defaultProvider: provider,
+    agents:          [monitorAgent],
+    defaultAgent:    'monitor',
+    goal:            'TODO: describe the agent goal',
+
+    triggers: [
+        // Run every day at 9:00 AM
+        {
+            type: 'schedule',
+            cron: '0 9 * * *',
+            task: 'Run daily check and report findings',
+        },
+
+        // Listen for webhook events (e.g. from GitHub, Slack, etc.)
+        {
+            type:   'webhook',
+            path:   '/events',
+            // secret: process.env.WEBHOOK_SECRET,  // uncomment to validate signatures
+        },
+
+        // TODO: add more triggers as needed
+        // { type: 'event', topic: 'my.custom.event' },
+    ],
+
+    webhookPort: parseInt(process.env.WEBHOOK_PORT ?? '3000'),
+});
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+await agent.start();
+console.log('Autonomous agent started.');
+console.log('Webhook listening on port', process.env.WEBHOOK_PORT ?? 3000);
+
+process.on('SIGTERM', async () => { await agent.stop(); process.exit(0); });
+process.on('SIGINT',  async () => { await agent.stop(); process.exit(0); });

package/templates/autonomous/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/coding/.env.example

@@ -0,0 +1,8 @@
+# LLM provider — pick one
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# DEEPSEEK_API_KEY=...
+
+# Provider to use: anthropic | openai | deepseek
+LLM_PROVIDER=anthropic
+LLM_MODEL=claude-sonnet-4-6

package/templates/coding/AGENT.md

@@ -0,0 +1,10 @@
+# My Coding Agent
+
+## Purpose
+<!-- Describe what this agent does for your project -->
+
+## Stack
+<!-- e.g. Node.js, TypeScript, NestJS, PostgreSQL -->
+
+## Conventions
+<!-- Any project-specific coding conventions the agent should follow -->

package/templates/coding/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "my-coding-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Coding assistant agent — edit files, run commands, search code",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-coding": "^0.14.0",
+    "@backendkit-labs/agent-core": "^0.14.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/coding/src/index.ts

@@ -0,0 +1,48 @@
+import 'dotenv/config';
+import * as readline from 'readline';
+import { createCodingEngine } from '@backendkit-labs/agent-coding';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+
+// ── Provider setup ────────────────────────────────────────────────────────────
+
+const provider = process.env.LLM_PROVIDER ?? 'anthropic';
+const apiKey   = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.LLM_API_KEY ?? '';
+const model    = process.env.LLM_MODEL;
+
+if (!apiKey) {
+    console.error('Missing API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY in .env');
+    process.exit(1);
+}
+
+// ── Engine ────────────────────────────────────────────────────────────────────
+
+const transport = new CallbackTransport((event) => {
+    if (event.type === 'token')       process.stdout.write(event.content);
+    if (event.type === 'tool_call')   console.log(`\n⚙  ${event.name}`);
+    if (event.type === 'block_end')   console.log();
+    if (event.type === 'error')       console.error(`\nError: ${event.message}`);
+});
+
+const engine = createCodingEngine({
+    providers:       { [provider]: { apiKey, ...(model ? { model } : {}) } },
+    defaultProvider: provider,
+    workingDir:      process.cwd(),
+    appName:         'my-coding-agent',
+    transport,
+});
+
+// ── REPL ──────────────────────────────────────────────────────────────────────
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+function prompt() {
+    rl.question('\n> ', async (input) => {
+        const trimmed = input.trim();
+        if (!trimmed || trimmed === '/exit') { rl.close(); return; }
+        await engine.run(trimmed);
+        prompt();
+    });
+}
+
+console.log('Coding agent ready. Type your request or /exit to quit.\n');
+prompt();

package/templates/coding/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/domain-agent/.env.example

@@ -0,0 +1,7 @@
+# LLM — any OpenAI-compatible endpoint
+LLM_API_KEY=sk-...
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4o
+
+# TODO: Add your domain-specific env vars here
+# MY_SERVICE_URL=http://localhost:8080

package/templates/domain-agent/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "my-domain-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Multi-agent system: orchestrator + domain specialists",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.14.0",
+    "dotenv": "^16.0.0",
+    "openai": "^4.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/domain-agent/src/agents/orchestrator.ts

@@ -0,0 +1,22 @@
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// The orchestrator receives every user request and delegates to the right specialist.
+// It does NOT call tools directly — it uses ask_agent to route work.
+export const ORCHESTRATOR_PROFILE: AgentProfile = {
+    id: 'orchestrator',
+    name: 'Orchestrator',
+    icon: '🎯',
+    description: 'Routes requests to the right specialist agent',
+    delegatesTo: ['specialist-a', 'specialist-b'], // TODO: list your specialists
+    allowedTools: [],
+    systemPrompt: `You are the orchestrator for a TODO: <describe your domain> system.
+
+Your ONLY job is to analyze the user request and delegate to the right specialist via ask_agent.
+Do not attempt to handle requests directly.
+
+Available specialists:
+- specialist-a: TODO describe what this specialist handles
+- specialist-b: TODO describe what this specialist handles
+
+Always delegate. Never answer directly.`,
+};

package/templates/domain-agent/src/agents/specialist-a.ts

@@ -0,0 +1,17 @@
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// TODO: Rename this file and agent to match your domain (e.g. docker-agent.ts, k8s-agent.ts)
+export const SPECIALIST_A_PROFILE: AgentProfile = {
+    id: 'specialist-a',
+    name: 'Specialist A',
+    icon: '🔧',
+    description: 'TODO: describe what this specialist does',
+    delegatesTo: [],
+    allowedTools: [
+        'example_action', // TODO: list the tool names this agent can use
+    ],
+    systemPrompt: `You are a specialist in TODO: <your domain area>.
+
+Use the available tools to complete the task delegated to you.
+Be precise and report results clearly.`,
+};

package/templates/domain-agent/src/agents/specialist-b.ts

@@ -0,0 +1,16 @@
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// TODO: Rename and customize for your second specialist
+export const SPECIALIST_B_PROFILE: AgentProfile = {
+    id: 'specialist-b',
+    name: 'Specialist B',
+    icon: '📊',
+    description: 'TODO: describe what this specialist does',
+    delegatesTo: [],
+    allowedTools: [
+        'example_query', // TODO: list the tool names this agent can use
+    ],
+    systemPrompt: `You are a specialist in TODO: <your domain area>.
+
+Use the available tools to complete the task delegated to you.`,
+};

package/templates/domain-agent/src/config.ts

@@ -0,0 +1,19 @@
+import 'dotenv/config';
+
+export interface Config {
+    llmApiKey: string;
+    llmBaseUrl: string;
+    llmModel: string;
+    // TODO: add your domain-specific config fields
+}
+
+export function loadConfig(): Config {
+    const llmApiKey = process.env.LLM_API_KEY ?? '';
+    if (!llmApiKey) throw new Error('Missing LLM_API_KEY in environment');
+
+    return {
+        llmApiKey,
+        llmBaseUrl: process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1',
+        llmModel:   process.env.LLM_MODEL   ?? 'gpt-4o',
+    };
+}

package/templates/domain-agent/src/engine.ts

@@ -0,0 +1,49 @@
+import {
+    AgentEngine,
+    AgentRegistry,
+    ToolRegistry,
+    ProviderRegistry,
+    CallbackTransport,
+} from '@backendkit-labs/agent-core';
+import { OpenAICompatibleProvider } from './providers/openai-compatible';
+import { loadConfig } from './config';
+import { ORCHESTRATOR_PROFILE } from './agents/orchestrator';
+import { SPECIALIST_A_PROFILE } from './agents/specialist-a';
+import { SPECIALIST_B_PROFILE } from './agents/specialist-b';
+import { exampleAction, exampleQuery } from './tools/example-tools';
+
+export function createDomainEngine(transport: CallbackTransport): AgentEngine {
+    const config = loadConfig();
+
+    const tools = new ToolRegistry();
+    tools
+        .register(exampleAction)
+        .register(exampleQuery);
+    // TODO: register more tools
+
+    const agents = new AgentRegistry();
+    agents
+        .register(ORCHESTRATOR_PROFILE)
+        .register(SPECIALIST_A_PROFILE)
+        .register(SPECIALIST_B_PROFILE);
+    // TODO: register more specialists
+
+    const providers = new ProviderRegistry();
+    providers.register('default', new OpenAICompatibleProvider({
+        apiKey:  config.llmApiKey,
+        baseUrl: config.llmBaseUrl,
+        model:   config.llmModel,
+    }));
+
+    return new AgentEngine({
+        model:          { provider: 'default', id: config.llmModel },
+        agents,
+        tools,
+        providers,
+        defaultProvider:  'default',
+        defaultAgentId:   'orchestrator',
+        transport,
+        maxIterations:    30,
+        iterationMode:    'auto',
+    });
+}

package/templates/domain-agent/src/index.ts

@@ -0,0 +1,27 @@
+import * as readline from 'readline';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { createDomainEngine } from './engine';
+
+const transport = new CallbackTransport((event) => {
+    if (event.type === 'token')       process.stdout.write(event.content);
+    if (event.type === 'tool_call')   console.log(`\n⚙  ${event.name}`);
+    if (event.type === 'agent_switch') console.log(`\n→ ${event.to_name ?? event.to}`);
+    if (event.type === 'block_end')   console.log();
+    if (event.type === 'error')       console.error(`\nError: ${event.message}`);
+});
+
+const engine = createDomainEngine(transport);
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+function prompt() {
+    rl.question('\n> ', async (input) => {
+        const trimmed = input.trim();
+        if (!trimmed || trimmed === '/exit') { rl.close(); return; }
+        await engine.run(trimmed);
+        prompt();
+    });
+}
+
+console.log('Domain agent ready. Type your request or /exit to quit.\n');
+prompt();

package/templates/domain-agent/src/providers/openai-compatible.ts

@@ -0,0 +1,104 @@
+import OpenAI from 'openai';
+import type { LLMProvider, LLMMessage, LLMStreamCallbacks, ToolDefinition } from '@backendkit-labs/agent-core';
+
+export interface OpenAICompatibleProviderOptions {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    maxRetries?: number;
+}
+
+function isRetryable(err: unknown): boolean {
+    if (err && typeof err === 'object' && 'status' in err) {
+        const s = (err as { status: number }).status;
+        return s === 429 || s >= 500;
+    }
+    return false;
+}
+
+const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
+
+export class OpenAICompatibleProvider implements LLMProvider {
+    private readonly client: OpenAI;
+    private readonly model: string;
+    private readonly maxRetries: number;
+
+    constructor(opts: OpenAICompatibleProviderOptions) {
+        this.client     = new OpenAI({ apiKey: opts.apiKey, baseURL: opts.baseUrl, maxRetries: 0 });
+        this.model      = opts.model;
+        this.maxRetries = opts.maxRetries ?? 3;
+    }
+
+    async chat(messages: LLMMessage[], tools: ToolDefinition[], callbacks: LLMStreamCallbacks): Promise<void> {
+        const oaiTools = tools.map(t => ({
+            type: 'function' as const,
+            function: { name: t.name, description: t.description, parameters: t.parameters },
+        })) as OpenAI.Chat.ChatCompletionTool[];
+
+        let attempt = 0;
+        let emitted = false;
+
+        while (attempt < this.maxRetries) {
+            attempt++;
+            try {
+                await this.stream(messages, oaiTools, {
+                    ...callbacks,
+                    onChunk: (d) => { emitted = true; callbacks.onChunk?.(d); },
+                });
+                return;
+            } catch (err) {
+                if (emitted || !isRetryable(err) || attempt >= this.maxRetries) {
+                    callbacks.onError(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                await sleep(Math.min(1000 * 2 ** attempt, 16_000));
+            }
+        }
+    }
+
+    private async stream(
+        messages: LLMMessage[],
+        oaiTools: OpenAI.Chat.ChatCompletionTool[],
+        callbacks: LLMStreamCallbacks,
+    ): Promise<void> {
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            messages: messages as OpenAI.Chat.ChatCompletionMessageParam[],
+            tools:       oaiTools.length ? oaiTools : undefined,
+            tool_choice: oaiTools.length ? 'auto'   : undefined,
+            stream: true,
+            stream_options: { include_usage: true },
+        });
+
+        let content = '';
+        const toolBuffers = new Map<number, { id: string; name: string; args: string }>();
+
+        for await (const chunk of stream) {
+            if (chunk.usage) callbacks.onMetrics?.(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
+            const delta = chunk.choices[0]?.delta;
+            if (!delta) continue;
+            if (delta.content) { content += delta.content; callbacks.onChunk?.(delta.content); }
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    if (!toolBuffers.has(tc.index)) toolBuffers.set(tc.index, { id: '', name: '', args: '' });
+                    const buf = toolBuffers.get(tc.index)!;
+                    if (tc.id) buf.id = tc.id;
+                    if (tc.function?.name)      buf.name += tc.function.name;
+                    if (tc.function?.arguments) buf.args += tc.function.arguments;
+                }
+            }
+        }
+
+        const toolCalls = [...toolBuffers.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([, b]) => ({ id: b.id, type: 'function' as const, function: { name: b.name, arguments: b.args } }));
+
+        for (const tc of toolCalls) callbacks.onToolCall?.(tc.function.name, tc.function.arguments, tc.id);
+
+        callbacks.onDone({
+            role: 'assistant',
+            content: content || null,
+            tool_calls: toolCalls.length ? toolCalls : undefined,
+        });
+    }
+}

package/templates/domain-agent/src/tools/example-tools.ts

@@ -0,0 +1,28 @@
+import { defineTool, z } from '@backendkit-labs/agent-core';
+
+// TODO: Replace these with tools that call your actual domain SDK/API
+
+export const exampleAction = defineTool({
+    name: 'example_action',
+    description: 'TODO: describe what this tool does',
+    input: z.object({
+        target: z.string().describe('Target to act on'),
+        // TODO: add more parameters
+    }),
+    execute: async ({ target }) => {
+        // TODO: implement the actual action
+        return `Action executed on: ${target}`;
+    },
+});
+
+export const exampleQuery = defineTool({
+    name: 'example_query',
+    description: 'TODO: describe what this query returns',
+    input: z.object({
+        filter: z.string().optional().describe('Optional filter'),
+    }),
+    execute: async ({ filter }) => {
+        // TODO: implement the actual query
+        return JSON.stringify({ results: [], filter });
+    },
+});

package/templates/domain-agent/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/mcp-server/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "my-mcp-server",
+  "version": "0.1.0",
+  "private": true,
+  "description": "MCP server — expose agent tools via Model Context Protocol",
+  "main": "dist/server.js",
+  "bin": { "my-mcp-server": "./dist/server.js" },
+  "scripts": {
+    "dev": "ts-node src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.14.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "dotenv": "^16.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/mcp-server/src/server.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { exampleHandler, exampleInputSchema } from './tools/example';
+
+// ── MCP Server ────────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+    name: 'my-mcp-server',
+    version: '0.1.0',
+});
+
+// ── Register tools ────────────────────────────────────────────────────────────
+
+// @ts-expect-error: MCP SDK + zod generic depth limit, safe at runtime
+server.tool(
+    'example_query',
+    'TODO: describe what this tool does',
+    exampleInputSchema.shape,
+    async (args: z.infer<typeof exampleInputSchema>) => ({
+        content: [{ type: 'text' as const, text: await exampleHandler(args) }],
+    }),
+);
+
+// TODO: register more tools following the same pattern:
+// server.tool('tool_name', 'description', schema.shape, handler)
+
+// ── Transport: stdio (for Claude Desktop / Cursor / VS Code) ─────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// To use this server, add it to your MCP client config:
+// {
+//   "mcpServers": {
+//     "my-server": { "command": "npx", "args": ["my-mcp-server"] }
+//   }
+// }

package/templates/mcp-server/src/tools/example.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+
+export const exampleInputSchema = z.object({
+    query: z.string().describe('The query to process'),
+});
+
+export async function exampleHandler({ query }: z.infer<typeof exampleInputSchema>): Promise<string> {
+    // TODO: implement your tool logic
+    return `Result for: ${query}`;
+}

package/templates/mcp-server/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/minimal/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "my-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Minimal agent — full control over engine configuration",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.14.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/minimal/src/index.ts

@@ -0,0 +1,40 @@
+import 'dotenv/config';
+import { createBaseEngine } from '@backendkit-labs/agent-core';
+import type { AgentProfile, LLMProvider } from '@backendkit-labs/agent-core';
+
+// ── Provider ──────────────────────────────────────────────────────────────────
+// TODO: replace with the actual provider for your chosen LLM
+// e.g. AnthropicProvider from @backendkit-labs/agent-coding
+// or implement LLMProvider interface directly
+
+const myProvider: LLMProvider = {
+    chat: async (_messages, _tools, callbacks) => {
+        // TODO: call your LLM API here
+        callbacks.onDone({ role: 'assistant', content: 'Hello from my agent!' });
+    },
+};
+
+// ── Agent ─────────────────────────────────────────────────────────────────────
+
+const myAgent: AgentProfile = {
+    id: 'my-agent',
+    name: 'My Agent',
+    description: 'TODO: describe your agent',
+    allowedTools: [],
+    delegatesTo: [],
+    systemPrompt: 'TODO: write your system prompt here.',
+};
+
+// ── Engine ────────────────────────────────────────────────────────────────────
+
+const engine = createBaseEngine({
+    providers:       { default: myProvider },
+    defaultProvider: 'default',
+    agents:          [myAgent],
+    defaultAgent:    'my-agent',
+});
+
+// ── Run ───────────────────────────────────────────────────────────────────────
+
+const input = process.argv[2] ?? 'Hello';
+await engine.run(input);

package/templates/minimal/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}