BeeAI Framework

Common errors

• TypeError: chatModel is not a constructor

  cause Attempting to use `ChatModel` (or similar core classes) without proper ES Module import or with incorrect CommonJS syntax.
  fix Ensure you are using `import { ChatModel } from 'beeai-framework';` and that your `tsconfig.json` (for TypeScript) or `package.json` (for Node.js) is configured for ES Modules (`"type": "module"`).

• Error: Missing API key for OpenAI. Please set the OPENAI_API_KEY environment variable.

  cause An LLM provider (e.g., OpenAI, Anthropic, Groq) was initialized without the necessary API key configured in the environment variables.
  fix Set the required API key (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GROQ_API_KEY`) as an environment variable in your `.env` file or directly in your deployment environment.

• npm ERR! ERESOLVE unable to resolve dependency tree

  cause Conflict in peer dependency versions between `beeai-framework` and other packages in your project, or between different versions of its own peer dependencies.
  fix Manually inspect the conflicting packages and their required versions. Try to update all related packages to their latest compatible versions or explicitly install peer dependencies to resolve the conflict. Use `npm install --legacy-peer-deps` as a temporary workaround if no direct resolution is found.

• Error: Tool 'calculator' failed to execute: [...] is not a function

  cause The `execute` method of a custom `Tool` class was not correctly implemented or is returning a non-promise where a promise is expected, or an argument mismatch occurred.
  fix Double-check the `execute` method in your custom `Tool` implementation. Ensure it is `async` and always returns a `Promise<any>`. Verify that the `parameters` definition matches the arguments expected by `execute`.

Warnings

• gotcha The BeeAI Framework is currently in 'Beta' status. This indicates that APIs may change, and breaking changes might occur in minor versions as the project evolves towards a stable `1.0` release.
  Fix: Review changelogs carefully for each update, especially for minor version bumps. Consider pinning exact versions in production environments or using dependabot for automated checks.
• breaking The framework migrated its backend to VercelAI SDK v6, which introduced significant changes to how AI model interactions and configurations are handled.
  Fix: If upgrading to `0.1.27` or later, review your `ChatModel` and other backend-related configurations to align with VercelAI SDK v6's API. Consult the relevant `@ai-sdk/*` package documentation for specific provider changes.
• gotcha The framework has a large number of peer dependencies for various LLM providers, vector stores, and utility libraries. Mismatched versions of these peer dependencies can lead to runtime errors or unexpected behavior.
  Fix: Ensure all peer dependencies are explicitly installed in your project and their versions satisfy the ranges specified by `beeai-framework`. Use `npm install --legacy-peer-deps` or `yarn add --dev` for peer dependencies if necessary, and carefully manage your dependency tree.
• gotcha Frequent updates often include fixes for security vulnerabilities (`CVEs`) in underlying dependencies. While beneficial, this rapid pace means older versions might contain unpatched security issues.
  Fix: Always update to the latest available minor version to ensure you benefit from the most recent security patches. Regularly scan your project dependencies for vulnerabilities.

Install

• npm install beeai-framework npm
• yarn add beeai-framework yarn
• pnpm add beeai-framework pnpm

Imports

• Agent
  wrong:

  const Agent = require('beeai-framework').Agent

  correct:

  import { Agent } from 'beeai-framework'

  The framework primarily uses ES Modules. CommonJS require() syntax is not supported for core modules.
• ChatModel
  wrong:

  import ChatModel from 'beeai-framework/backend'

  correct:

  import { ChatModel } from 'beeai-framework'

  Most core components are named exports directly from the main package. Specific sub-paths are generally not needed for common symbols.
• Tool
  wrong:

  const { Tool } = require('beeai-framework')

  correct:

  import { Tool } from 'beeai-framework'

  As a TypeScript-first library, it's designed for static analysis and ESM usage. Ensure your project is configured for ES Modules.
• Message
  wrong:

  import { MessageType } from 'beeai-framework'

  correct:

  import { Message } from 'beeai-framework'

  The primary interface for chat messages is `Message` within the `backend` module context.

Quickstart

Demonstrates initializing an agent with a chat model and a custom tool, then running a simple query for calculation.

import "dotenv/config";
import { Agent, ChatModel, Tool, Message } from 'beeai-framework';

// Define a simple tool that the agent can use
class MyCalculatorTool extends Tool {
  constructor() {
    super({
      name: "calculator",
      description: "A simple calculator tool that can add two numbers.",
      parameters: {
        type: "object",
        properties: {
          a: { type: "number", description: "The first number" },
          b: { type: "number", description: "The second number" }
        },
        required: ["a", "b"]
      }
    });
  }

  async execute(params: { a: number; b: number }): Promise<any> {
    return { result: params.a + params.b };
  }
}

async function runAgent() {
  // Initialize a chat model (e.g., using OpenAI via @ai-sdk/openai peer dep)
  // Ensure OPENAI_API_KEY is set in your .env file
  const chatModel = new ChatModel({
    model: process.env.OPENAI_MODEL ?? 'gpt-4o',
    provider: 'openai' // This would depend on specific @ai-sdk integration
  });

  // Instantiate the agent with the chat model and available tools
  const agent = new Agent({
    model: chatModel,
    tools: [new MyCalculatorTool()] // Add our custom tool
    // Other agent configurations like memory, system prompts etc.
  });

  console.log("Agent initialized. Asking it to perform a calculation...");

  // Interact with the agent
  const response = await agent.run([
    { role: "user", content: "What is 5 plus 3?" }
  ]);

  console.log("Agent's response:", response.messages[response.messages.length - 1].content);
}

runAgent().catch(console.error);