create-bk-agent 0.16.1 → 0.17.1

package/templates/base/single/src/config.ts

@@ -0,0 +1,18 @@
+import 'dotenv/config';
+
+export interface Config {
+    llmApiKey: string;
+    llmBaseUrl: string;
+    llmModel: string;
+}
+
+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/base/single/src/engine.ts

@@ -0,0 +1,44 @@
+import {
+    AgentEngine,
+    AgentRegistry,
+    ToolRegistry,
+    ProviderRegistry,
+    CallbackTransport,
+} from '@backendkit-labs/agent-core';
+import { OpenAICompatibleProvider } from './providers/openai-compatible';
+import { loadConfig } from './config';
+import { MY_AGENT_PROFILE } from './agents/my-agent';
+import { exampleAction, exampleQuery } from './tools/example-tools';
+
+export function createEngine(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(MY_AGENT_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:   'my-agent',
+        transport,
+        maxIterations:    20,
+        iterationMode:    'auto',
+    });
+}

package/templates/base/single/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/base/single/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/base/single/tsconfig.json

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

package/templates/deploy/hybrid/src/index.ts

@@ -0,0 +1,27 @@
+import * as readline from 'readline';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { createEngine } 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 = createEngine(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('Agent ready. Type your request or /exit to quit.\n');
+prompt();

package/templates/deploy/hybrid/src/server.ts

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+import { AgentMCPServer } from '@backendkit-labs/mcp-server';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { z } from 'zod';
+import { createEngine } from './engine';
+
+const server = new AgentMCPServer({
+    name:    process.env.npm_package_name ?? 'my-agent',
+    version: '1.0.0',
+    port:    parseInt(process.env.MCP_PORT ?? '3001'),
+
+    tools: [
+        {
+            name:        'agent_request',
+            description: 'TODO: describe what requests this agent handles',
+            schema: {
+                request: z.string().describe('Natural-language request for the agent'),
+            },
+            buildPrompt: ({ request }: { request: string }) => request,
+        },
+    ],
+
+    engineFactory: (transport: CallbackTransport) => createEngine(transport),
+});
+
+void (async () => { await server.start(); })();

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

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+import { AgentMCPServer } from '@backendkit-labs/mcp-server';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { z } from 'zod';
+import { createEngine } from './engine';
+
+const server = new AgentMCPServer({
+    name:    process.env.npm_package_name ?? 'my-agent',
+    version: '1.0.0',
+    port:    parseInt(process.env.MCP_PORT ?? '3001'),
+
+    tools: [
+        {
+            name:        'agent_request',
+            description: 'TODO: describe what requests this agent handles',
+            schema: {
+                request: z.string().describe('Natural-language request for the agent'),
+            },
+            buildPrompt: ({ request }: { request: string }) => request,
+        },
+    ],
+
+    engineFactory: (transport: CallbackTransport) => createEngine(transport),
+});
+
+void (async () => { await server.start(); })();

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

@@ -0,0 +1,25 @@
+import 'dotenv/config';
+import { AgentMCPServer } from '@backendkit-labs/mcp-server';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { z } from 'zod';
+import { createEngine } from './engine';
+
+const server = new AgentMCPServer({
+    name:    process.env.npm_package_name ?? 'my-agent',
+    version: '1.0.0',
+
+    tools: [
+        {
+            name:        'agent_request',
+            description: 'TODO: describe what requests this agent handles',
+            schema: {
+                request: z.string().describe('Natural-language request for the agent'),
+            },
+            buildPrompt: ({ request }: { request: string }) => request,
+        },
+    ],
+
+    engineFactory: (transport: CallbackTransport) => createEngine(transport),
+});
+
+void (async () => { await server.startStdio(); })();

package/templates/deploy/repl/src/index.ts

@@ -0,0 +1,27 @@
+import * as readline from 'readline';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { createEngine } 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 = createEngine(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('Agent ready. Type your request or /exit to quit.\n');
+prompt();