BeeAI Framework for Python

Build production-ready multi-agent systems. Also available in TypeScript.

What is BeeAI Framework?

BeeAI Framework is a comprehensive toolkit for building intelligent, autonomous agents and multi-agent systems. It provides everything you need to create agents that can reason, take actions, and collaborate to solve complex problems.

Key Features

Feature	Description
🤖 Agents	Create intelligent agents that can reason, act, and adapt
🔄 Workflows	Orchestrate multi-agent systems with complex execution flows
🔌 Backend	Connect to any LLM provider with unified interfaces
🔧 Tools	Extend agents with web search, weather, code execution, and more
🔍 RAG	Build retrieval-augmented generation systems with vector stores and document processing
📝 Templates	Build dynamic prompts with enhanced Mustache syntax
🧠 Memory	Manage conversation history with flexible memory strategies
📊 Observability	Monitor agent behavior with events, logging, and robust error handling
🚀 Serve	Host agents in servers with support for multiple protocols such as A2A and MCP
💾 Cache	Optimize performance and reduce costs with intelligent caching
💿 Serialization	Save and load agent state for persistence across sessions

Quick Start

Prerequisite

✅ Python >= 3.11

Installation

pip install beeai-framework

Multi-Agent Example

import asyncio

from beeai_framework.agents.requirement import RequirementAgent
from beeai_framework.agents.requirement.requirements.conditional import ConditionalRequirement
from beeai_framework.backend import ChatModel
from beeai_framework.errors import FrameworkError
from beeai_framework.middleware.trajectory import GlobalTrajectoryMiddleware
from beeai_framework.tools import Tool
from beeai_framework.tools.handoff import HandoffTool
from beeai_framework.tools.search.wikipedia import WikipediaTool
from beeai_framework.tools.think import ThinkTool
from beeai_framework.tools.weather import OpenMeteoTool


async def main() -> None:
    knowledge_agent = RequirementAgent(
        llm=ChatModel.from_name("ollama:granite4:micro"),
        tools=[ThinkTool(), WikipediaTool()],
        requirements=[ConditionalRequirement(ThinkTool, force_at_step=1)],
        role="Knowledge Specialist",
        instructions="Provide answers to general questions about the world.",
    )

    weather_agent = RequirementAgent(
        llm=ChatModel.from_name("ollama:granite4:micro"),
        tools=[OpenMeteoTool()],
        role="Weather Specialist",
        instructions="Provide weather forecast for a given destination.",
    )

    main_agent = RequirementAgent(
        name="MainAgent",
        llm=ChatModel.from_name("ollama:granite4:micro"),
        tools=[
            ThinkTool(),
            HandoffTool(
                knowledge_agent,
                name="KnowledgeLookup",
                description="Consult the Knowledge Agent for general questions.",
            ),
            HandoffTool(
                weather_agent,
                name="WeatherLookup",
                description="Consult the Weather Agent for forecasts.",
            ),
        ],
        requirements=[ConditionalRequirement(ThinkTool, force_at_step=1)],
        # Log all tool calls to the console for easier debugging
        middlewares=[GlobalTrajectoryMiddleware(included=[Tool])],
    )

    question = "If I travel to Rome next weekend, what should I expect in terms of weather, and also tell me one famous historical landmark there?"
    print(f"User: {question}")

    try:
        response = await main_agent.run(question, expected_output="Helpful and clear response.")
        print("Agent:", response.last_message.text)
    except FrameworkError as err:
        print("Error:", err.explain())


if __name__ == "__main__":
    asyncio.run(main())

Source: python/examples/agents/requirement/handoff.py

Message Content Helpers (Text / Image / File)

You can build multimodal user messages with simple factory helpers:

from beeai_framework.backend import UserMessage

# Plain text
msg_text = UserMessage.from_text("Explain the solar eclipse")

# Image (data URI or URL)
msg_image = UserMessage.from_image("data:image/png;base64,iVBORw0KGgoAAA...")

# File (either file_id OR file_data)
msg_file = UserMessage.from_file(
    file_id="https://example.com/sample.pdf",
    format="application/pdf",
)

# Inline base64 file
msg_inline_pdf = UserMessage.from_file(
    file_data="data:application/pdf;base64,AAA...",
    format="application/pdf",
)

The file message API is now flattened (no nested file={...} structure). Use file_id for remote/previously uploaded resources or file_data for a data URI.

Running the Example

To run projects, use:

python [project_name].py

➡️ Explore more in our examples library.

Documentation

📖 Complete documentation is available at (framework.beeai.dev)[https://framework.beeai.dev/]

Contribution Guidelines

BeeAI framework is an open-source project and we ❤️ contributions.

If you'd like to help build BeeAI, take a look at our contribution guidelines.

Bugs

We are using GitHub Issues to manage public bugs. We keep a close eye on this, so before filing a new issue, please check to make sure it hasn't already been logged.

Code of Conduct

This project and everyone participating in it are governed by the Code of Conduct. By participating, you are expected to uphold this code. Please read the full text so that you can read which actions may or may not be tolerated.

Legal Notice

All content in these repositories including code has been provided by IBM under the associated open source software license and IBM is under no obligation to provide enhancements, updates, or support. IBM developers produced this code as an open source project (not as an IBM product), and IBM makes no assertions as to the level of quality nor security, and will not be maintaining this code going forward.

Maintainers

For information about maintainers, see MAINTAINERS.md.

Contributors

Special thanks to our contributors for helping us improve BeeAI framework.

Developed by contributors to the BeeAI project, this initiative is part of the Linux Foundation AI & Data program. Its development follows open, collaborative, and community-driven practices.

Metadata

Release files for beeai-framework 0.1.84

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for beeai-framework 0.1.84
File	Size	Uploaded
beeai_framework-0.1.84.tar.gz	220.3 kB	Sep 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for beeai-framework 0.1.84
File	Interpreter	ABI	Platform	Reset
beeai_framework-0.1.84-py3-none-any.whl 397.0 kB Sep 15, 2026	Python 3	none	any	Details

Total release size: 617.3 kB

Release files / beeai_framework-0.1.84.tar.gz

Download URL	beeai_framework-0.1.84.tar.gz
Size	220.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`f414510c5eb41211239ccce035b111fbf6fe96f156a6a6bf16e1586aee0a075d`
BLAKE2b-256 checksum How to use checksums	`fcaaa5657fb5660e856f9d79ab04398e540fd3337ebd0356f8f2949e7f38ab55`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.1 CPython/3.13.7 Darwin/25.6.0`

Release files / beeai_framework-0.1.84-py3-none-any.whl

Download URL	beeai_framework-0.1.84-py3-none-any.whl
Size	397.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d8d2ec26dc47871517bc1a81cd27c992c5af2d5402e94d6f457a14b9a1f75984`
BLAKE2b-256 checksum How to use checksums	`0b227fdc3542880da46f1bb78f1cfca5d2079df7a20548091f7b05d07560a1ef`
Upload date	Sep 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.1 CPython/3.13.7 Darwin/25.6.0`