Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Agent
✓ import { Agent } from 'beeai-framework'
✗ const Agent = require('beeai-framework').Agent
The framework primarily uses ES Modules. CommonJS require() syntax is not supported for core modules.
ChatModel
✓ import { ChatModel } from 'beeai-framework'
✗ import ChatModel from 'beeai-framework/backend'
Most core components are named exports directly from the main package. Specific sub-paths are generally not needed for common symbols.
Tool
✓ import { Tool } from 'beeai-framework'
✗ const { Tool } = require('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
✓ import { Message } from 'beeai-framework'
✗ import { MessageType } from 'beeai-framework'
The primary interface for chat messages is `Message` within the `backend` module context.
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);
Debug
Known issues
gotchaThe 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.fixReview changelogs carefully for each update, especially for minor version bumps. Consider pinning exact versions in production environments or using dependabot for automated checks.
affects: >=0.1.0
breakingThe framework migrated its backend to VercelAI SDK v6, which introduced significant changes to how AI model interactions and configurations are handled.fixIf 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.
affects: >=0.1.27
gotchaThe 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.fixEnsure 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.
affects: >=0.1.0
gotchaFrequent updates often include fixes for security vulnerabilities (`CVEs`) in underlying dependencies. While beneficial, this rapid pace means older versions might contain unpatched security issues.fixAlways update to the latest available minor version to ensure you benefit from the most recent security patches. Regularly scan your project dependencies for vulnerabilities.
affects: <0.1.28 (TypeScript), <0.1.79 (Python)
Errors
Common errors & fixes
TypeError: chatModel is not a constructor
Attempting to use `ChatModel` (or similar core classes) without proper ES Module import or with incorrect CommonJS syntax.
fixEnsure 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.
An LLM provider (e.g., OpenAI, Anthropic, Groq) was initialized without the necessary API key configured in the environment variables.
fixSet 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
Conflict in peer dependency versions between `beeai-framework` and other packages in your project, or between different versions of its own peer dependencies.
fixManually 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
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.
fixDouble-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`.
Audit
Dependencies
@a2a-js/sdkoptionalIntegration with Agent-to-Agent communication SDK.
@ai-sdk/amazon-bedrockoptionalProvider for Amazon Bedrock LLM integration.
@ai-sdk/anthropicoptionalProvider for Anthropic LLM integration.
@ai-sdk/azureoptionalProvider for Azure OpenAI LLM integration.
@ai-sdk/google-vertexoptionalProvider for Google Vertex AI LLM integration.
@ai-sdk/groqoptionalProvider for Groq LLM integration.
@ai-sdk/openaioptionalProvider for OpenAI LLM integration.
@aws-sdk/client-bedrock-runtimeoptionalAWS SDK client for Bedrock runtime interactions.
@elastic/elasticsearchoptionalClient for Elasticsearch interactions, likely for vector stores or search.
@googleapis/customsearchoptionalGoogle Custom Search API client, for tool integrations.
@langchain/communityoptionalCommunity integrations for LangChain, offering additional tools/components.
@langchain/coreoptionalCore LangChain functionalities, potentially for compatibility or advanced features.
@modelcontextprotocol/sdkoptionalSDK for Model Context Protocol integration.
@qdrant/js-client-restoptionalClient for Qdrant vector database integration.
@zilliz/milvus2-sdk-nodeoptionalClient for Milvus vector database integration.
expressoptionalWeb framework, likely for building API backends that host agents.
ollama-ai-provider-v2optionalProvider for Ollama local LLM integration.
sequelizeoptionalORM for database interactions, potentially for memory or state persistence.
yamloptionalYAML parsing/serialization, possibly for configuration or prompt templates.