@chatbotkit/agent 1.28.0 → 1.29.1

package/README.md

@@ -9,6 +9,20 @@
 
 Build autonomous AI agents that can use custom tools and execute complex tasks with the full power of the ChatBotKit platform.
 
+## Why ChatBotKit?
+
+**Build lighter, future-proof AI agents.** When you build with ChatBotKit, the heavy lifting happens on our servers—not in your application. This architectural advantage delivers:
+
+- 🪶 **Lightweight Agents**: Your agents stay lean because complex AI processing, model orchestration, and tool execution happen server-side. Less code in your app means faster load times and simpler maintenance.
+
+- 🛡️ **Robust & Streamlined**: Server-side processing provides a more reliable experience with built-in error handling, automatic retries, and consistent behavior across all platforms.
+
+- 🔄 **Backward & Forward Compatible**: As AI technology evolves—new models, new capabilities, new paradigms—your agents automatically benefit. No code changes required on your end.
+
+- 🔮 **Future-Proof**: Agents you build today will remain capable tomorrow. When we add support for new AI models or capabilities, your existing agents gain those powers without any updates to your codebase.
+
+This means you can focus on building great user experiences while ChatBotKit handles the complexity of the ever-changing AI landscape.
+
 ## Installation
 
 ```bash
@@ -178,6 +192,59 @@ The `execute` mode provides system tools for task management:
 - **`progress`** - Track completion status and blockers
 - **`exit`** - Signal task completion with status code
 
+### Skills Loading
+
+Load skills from local directories and pass them as a feature to the agent. Skills are defined using `SKILL.md` files with front matter containing name and description.
+
+```javascript
+import { execute, loadSkills, createSkillsFeature } from '@chatbotkit/agent'
+import { ChatBotKit } from '@chatbotkit/sdk'
+
+const client = new ChatBotKit({ secret: process.env.CHATBOTKIT_API_TOKEN })
+
+// Load skills from directories
+const skillsResult = await loadSkills(['./skills'], { watch: true })
+
+// Create the skills feature for the API
+const skillsFeature = createSkillsFeature(skillsResult.skills)
+
+const stream = execute({
+  client,
+  model: 'gpt-4o',
+  messages: [{ type: 'user', text: 'Help me with my task' }],
+  extensions: {
+    features: [skillsFeature],
+  },
+})
+
+for await (const event of stream) {
+  // Handle events
+}
+
+// Clean up when done
+skillsResult.close()
+```
+
+#### SKILL.md Format
+
+Create a `SKILL.md` file in each skill directory:
+
+```markdown
+---
+name: My Skill
+description: A brief description of what this skill does
+---
+
+# My Skill
+
+Additional documentation for the skill...
+```
+
+#### Skills API
+
+- **`loadSkills(directories, options)`** - Load skills from directories containing SKILL.md files
+- **`createSkillsFeature(skills)`** - Create a feature configuration for the API
+
 ## Documentation
 
 For comprehensive information about the ChatBotKit Agent SDK, including detailed documentation on its functionalities, helper methods, and configuration options, please visit our [type documentation page](https://chatbotkit.github.io/node-sdk/modules/_chatbotkit_agent.html).

package/dist/cjs/agent.cjs

@@ -1,258 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.complete = complete;
-exports.execute = execute;
-const zod_1 = require("zod");
-const zod_to_json_schema_1 = require("zod-to-json-schema");
-async function* complete(options) {
-    const { client, tools, ...request } = options;
-    const channelToTool = new Map();
-    const functions = tools
-        ? Object.entries(tools).map(([name, tool]) => {
-            const randomSuffix = Math.random().toString(36).substring(2, 15);
-            const channel = `${name}_${randomSuffix}`.padEnd(16, '0');
-            channelToTool.set(channel, { name, tool });
-            if (!tool.input) {
-                return {
-                    name,
-                    description: tool.description,
-                    parameters: ({
-                        type: 'object',
-                        properties: {},
-                    }),
-                    result: {
-                        channel,
-                    },
-                };
-            }
-            const schema = ((0, zod_to_json_schema_1.zodToJsonSchema)(tool.input, { target: 'openApi3' }));
-            const parameters = {
-                type: 'object',
-                properties: schema.properties || {},
-                ...(schema.required && schema.required.length > 0
-                    ? { required: schema.required }
-                    : {}),
-            };
-            return {
-                name,
-                description: tool.description,
-                parameters: (parameters),
-                result: {
-                    channel,
-                },
-            };
-        })
-        : undefined;
-    const stream = client.conversation
-        .complete(null, {
-        ...request,
-        functions,
-    })
-        .stream();
-    const toolEventQueue = [];
-    const runningTools = new Set();
-    const executeToolAsync = async (channel, name, tool, args) => {
-        try {
-            let parsedArgs = args;
-            if (tool.input) {
-                const parseResult = tool.input.safeParse(args);
-                if (!parseResult.success) {
-                    const errorMsg = `Invalid arguments: ${parseResult.error.message}`;
-                    toolEventQueue.push({
-                        type: 'toolCallError',
-                        data: { name, error: errorMsg },
-                    });
-                    await client.channel.publish(String(channel), {
-                        message: { error: errorMsg },
-                    });
-                    return;
-                }
-                parsedArgs = parseResult.data;
-            }
-            const result = await tool.handler(parsedArgs);
-            toolEventQueue.push({
-                type: 'toolCallEnd',
-                data: { name, result },
-            });
-            await client.channel.publish(String(channel), {
-                message: { data: result },
-            });
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-            toolEventQueue.push({
-                type: 'toolCallError',
-                data: { name, error: errorMessage },
-            });
-            await client.channel.publish(String(channel), {
-                message: { error: errorMessage },
-            });
-        }
-        finally {
-            runningTools.delete(channel);
-        }
-    };
-    for await (const event of stream) {
-        while (toolEventQueue.length > 0) {
-            const toolEvent = toolEventQueue.shift();
-            if (toolEvent) {
-                yield toolEvent;
-            }
-        }
-        if (event.type === 'waitForChannelMessageBegin' &&
-            event.data &&
-            'channel' in event.data &&
-            'function' in event.data) {
-            const channel = (event.data.channel);
-            const args = (event.data.function).args;
-            const toolInfo = channelToTool.get(String(channel));
-            if (toolInfo) {
-                const { name, tool } = toolInfo;
-                yield {
-                    type: 'toolCallStart',
-                    data: {
-                        name,
-                        args,
-                    },
-                };
-                const toolPromise = executeToolAsync(channel, name, tool, args);
-                runningTools.add(channel);
-                toolPromise.catch(() => {
-                });
-            }
-        }
-        yield event;
+exports.loadAgent = loadAgent;
+const tslib_1 = require("tslib");
+const promises_1 = require("fs/promises");
+const js_yaml_1 = tslib_1.__importDefault(require("js-yaml"));
+const path_1 = require("path");
+function parseAgentFile(content) {
+    const frontMatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)/;
+    const match = content.match(frontMatterRegex);
+    if (!match) {
+        return { frontMatter: {}, body: content.trim() };
     }
-    while (toolEventQueue.length > 0) {
-        const toolEvent = toolEventQueue.shift();
-        if (toolEvent) {
-            yield toolEvent;
+    let frontMatter = ({});
+    try {
+        const parsed = js_yaml_1.default.load(match[1]);
+        if (typeof parsed === 'object' && parsed !== null) {
+            frontMatter = (parsed);
         }
     }
-    while (runningTools.size > 0) {
-        await new Promise((resolve) => setTimeout(resolve, 10));
-        while (toolEventQueue.length > 0) {
-            const toolEvent = toolEventQueue.shift();
-            if (toolEvent) {
-                yield toolEvent;
-            }
-        }
+    catch {
     }
+    return { frontMatter, body: match[2].trim() };
 }
-async function* execute(options) {
-    const { client, tools = {}, maxIterations = 50, ...request } = options;
-    const messages = [...(request.messages || [])];
-    let exitResult = null;
-    const systemTools = {
-        plan: {
-            description: 'Create or update a plan for approaching the task. Break down the task into clear, actionable steps. Use this at the start and whenever you need to revise your approach.',
-            input: zod_1.z.object({
-                steps: zod_1.z
-                    .array(zod_1.z.string())
-                    .describe('Array of step descriptions in order of execution'),
-                rationale: zod_1.z
-                    .string()
-                    .optional()
-                    .describe('Brief explanation of the plan approach'),
-            }),
-            handler: async (input) => {
-                return {
-                    success: true,
-                    message: `Plan created with ${input.steps.length} steps${input.rationale ? ': ' + input.rationale : ''}`,
-                };
-            },
-        },
-        progress: {
-            description: 'Update progress on the current task. Use this to track completed steps, report current status, and identify blockers.',
-            input: zod_1.z.object({
-                completed: zod_1.z
-                    .array(zod_1.z.string())
-                    .optional()
-                    .describe('Steps that have been completed'),
-                current: zod_1.z.string().optional().describe('Current step being worked on'),
-                blockers: zod_1.z
-                    .array(zod_1.z.string())
-                    .optional()
-                    .describe('Any issues preventing progress'),
-                nextSteps: zod_1.z
-                    .array(zod_1.z.string())
-                    .optional()
-                    .describe('Next actions to take'),
-            }),
-            handler: async (input) => {
-                return {
-                    success: true,
-                    message: 'Progress updated',
-                    ...input,
-                };
-            },
-        },
-        exit: {
-            description: 'Exit the task execution with a status code and optional message. Status code 0 indicates success, non-zero indicates failure. Use this when all the tasks are complete or cannot proceed.',
-            input: zod_1.z.object({
-                code: zod_1.z
-                    .number()
-                    .int()
-                    .min(0)
-                    .max(255)
-                    .describe('Exit status code (0 = success, non-zero = failure)'),
-                message: zod_1.z
-                    .string()
-                    .optional()
-                    .describe('Optional message explaining the exit reason'),
-            }),
-            handler: async (input) => {
-                exitResult = { code: input.code, message: input.message };
-                return {
-                    success: true,
-                    message: `Task exiting with code ${input.code}${input.message ? ': ' + input.message : ''}`,
-                };
-            },
-        },
-    };
-    const allTools = { ...systemTools, ...tools };
-    const systemInstruction = `
-${options.extensions?.backstory || ''}
-
-# Task Execution Guidelines
-
-The goal is to complete the assigned task efficiently and effectively. Follow these guidelines:
-
-1. **Plan First**: Use the 'plan' function to create a clear strategy before starting work
-2. **Track Progress**: Regularly use the 'progress' function to update status and identify issues
-3. **Use Tools**: Leverage available tools to accomplish each step of your plan
-4. **Exit When Done**: Call the 'exit' function with code 0 when successful, or non-zero code if unable to complete
-5. **Be Autonomous**: Work through the task systematically without waiting for additional input
-`.trim();
-    let iteration = 0;
-    while (iteration < maxIterations && exitResult === null) {
-        iteration++;
-        yield { type: 'iteration', data: { iteration } };
-        for await (const event of complete({
-            ...request,
-            client,
-            messages,
-            tools: allTools,
-            extensions: {
-                ...options.extensions,
-                backstory: systemInstruction,
-            },
-        })) {
-            yield event;
-        }
-        if (exitResult) {
-            break;
-        }
-        messages.push({
-            type: 'user',
-            text: 'Continue with the next step of your plan. If all steps are complete, call exit with the appropriate status code.',
-        });
-    }
-    if (exitResult === null) {
-        exitResult = {
-            code: 1,
-            message: `Task did not complete within ${maxIterations} iterations`,
-        };
-    }
-    yield { type: 'exit', data: exitResult };
+async function loadAgent(filePath) {
+    const resolvedPath = (0, path_1.resolve)(process.cwd(), filePath);
+    const content = await (0, promises_1.readFile)(resolvedPath, 'utf-8');
+    const { frontMatter, body } = parseAgentFile(content);
+    const name = typeof frontMatter.name === 'string' ? frontMatter.name : undefined;
+    const description = typeof frontMatter.description === 'string'
+        ? frontMatter.description
+        : undefined;
+    const model = typeof frontMatter.model === 'string' ? frontMatter.model : undefined;
+    const botId = typeof frontMatter.botId === 'string' ? frontMatter.botId : undefined;
+    const skillsetId = typeof frontMatter.skillsetId === 'string'
+        ? frontMatter.skillsetId
+        : undefined;
+    const datasetId = typeof frontMatter.datasetId === 'string'
+        ? frontMatter.datasetId
+        : undefined;
+    const frontMatterBackstory = typeof frontMatter.backstory === 'string' ? frontMatter.backstory : '';
+    const backstoryParts = [frontMatterBackstory, body].filter(Boolean);
+    const backstory = backstoryParts.length > 0 ? backstoryParts.join('\n\n') : undefined;
+    return { name, description, backstory, model, botId, skillsetId, datasetId };
 }

package/dist/cjs/agent.d.ts

@@ -1,54 +1,10 @@
-export function complete(options: ConversationCompleteRequest & {
-    client: ChatBotKit;
-    tools?: Tools;
-}): AsyncGenerator<ConversationCompleteStreamType | ToolCallStartEvent | ToolCallEndEvent | ToolCallErrorEvent, void, unknown>;
-export function execute(options: ConversationCompleteRequest & {
-    client: ChatBotKit;
-    tools?: Tools;
-    maxIterations?: number;
-}): AsyncGenerator<ConversationCompleteStreamType | ToolCallStartEvent | ToolCallEndEvent | ToolCallErrorEvent | IterationEvent | ExitEvent, void, unknown>;
-export type ZodObject = import("zod").ZodObject<any>;
-export type ChatBotKit = import("@chatbotkit/sdk").ChatBotKit;
-export type ConversationCompleteRequest = any;
-export type ConversationCompleteStreamType = any;
-export type ToolDefinition<T extends ZodObject> = {
-    description: string;
-    input?: T;
-    handler: (input: any) => Promise<any>;
-};
-export type Tools = Record<string, ToolDefinition<ZodObject>>;
-export type ExitResult = {
-    code: number;
-    message?: string;
-};
-export type ToolCallStartEvent = {
-    type: "toolCallStart";
-    data: {
-        name: string;
-        args: any;
-    };
-};
-export type ToolCallEndEvent = {
-    type: "toolCallEnd";
-    data: {
-        name: string;
-        result: any;
-    };
-};
-export type ToolCallErrorEvent = {
-    type: "toolCallError";
-    data: {
-        name: string;
-        error: string;
-    };
-};
-export type IterationEvent = {
-    type: "iteration";
-    data: {
-        iteration: number;
-    };
-};
-export type ExitEvent = {
-    type: "exit";
-    data: ExitResult;
+export function loadAgent(filePath: string): Promise<AgentDefinition>;
+export type AgentDefinition = {
+    name?: string;
+    description?: string;
+    backstory?: string;
+    model?: string;
+    botId?: string;
+    skillsetId?: string;
+    datasetId?: string;
 };