Edmondo's Vault

BeeAI

May 18, 20267 min read

BeeAI is an open-source framework developed by IBM and contributed to the Linux Foundation (LF AI & Data Foundation) in April 2025 for building production-grade multi-agent systems. The framework emphasizes enterprise stability, governance, and observability while maintaining flexibility for complex agent orchestration. BeeAI provides complete feature parity between Python and TypeScript, supports 10+ LLM providers, and implements the Agent Communication Protocol (ACP) as its reference implementation.

The framework addresses the problem of building reliable, production-ready multi-agent systems through built-in constraint enforcement, rule-based governance, and comprehensive observability. Unlike research-oriented frameworks, BeeAI prioritizes deterministic behavior, resource management, and enterprise deployment requirements.

Agent Architecture and Types

BeeAI implements agents as AI systems built on language models capable of executing complex tasks through structured reasoning and autonomous actions:

  • ReActAgent which implements the ReAct (Reasoning + Acting) pattern alternating between reasoning steps and tool executions. Agent thinks through problems, decides on actions, invokes tools, observes results, and iterates until reaching solution.
  • RequirementAgent emphasizes reliability and deterministic behavior through declarative interface. Allows defining requirements and constraints that framework enforces automatically. Preserves reasoning abilities while ensuring predictable outcomes through rule-based governance.

BeeAI implements an Event-driven architecture: agents emit events during execution enabling monitoring, debugging, and custom behavior injection.

  • update: Progress notifications during execution
  • tool_call: Tool invocation events
  • tool_response: Tool output events
  • error: Error conditions
  • complete: Task completion

Code samples

from beeai_framework.agents.react import ReActAgent
from beeai_framework.backend import ChatModel
from beeai_framework.memory import UnconstrainedMemory
from beeai_framework.tools import tool
 
@tool
def calculator_tool(expression: str) -> str:
    """Evaluate a mathematical expression and return the result."""
    try:
        return str(eval(expression))
    except Exception as e:
        return f"Error: {e}"
 
llm = ChatModel.from_name("ollama:granite3.1-dense:8b")
 
agent = ReActAgent(
    llm=llm,
    tools=[calculator_tool],
    memory=UnconstrainedMemory(),
)
 
response = await agent.run("What is 20 + 2 * 3?")
print(response.last_message.text)
from beeai_framework.agents.experimental import RequirementAgent
from beeai_framework.backend import ChatModel
from beeai_framework.memory import UnconstrainedMemory
from beeai_framework.tools.think import ThinkTool
from beeai_framework.tools.search.wikipedia import WikipediaTool
 
knowledge_agent = RequirementAgent(
    llm=ChatModel.from_name("ollama:granite3.3"),
    tools=[ThinkTool(), WikipediaTool()],
    memory=UnconstrainedMemory(),
    instructions="""Provide detailed, accurate information using available 
    knowledge sources. Think through problems step by step."""
)

Tools and Function Calling Integration

Tools extend agent capabilities beyond text processing enabling interaction with external systems and data sources. BeeAI also supports MCP

Built-in tools

Built-in tools provided by framework:

  • Search tools:

    • DuckDuckGoSearchTool: Web search capabilities
    • WikipediaTool: Knowledge base access

  • Utility tools:

    • OpenMeteoTool: Weather information retrieval
    • ThinkTool: Internal reasoning step without external calls
    • HandoffTool: Agent-to-agent delegation

Custom tool implementation using @tool decorator

from beeai_framework.tools import tool
from typing import Annotated
 
@tool
def web_scraper(
    url: Annotated[str, "URL to scrape"], 
    selector: Annotated[str, "CSS selector"] = "body"
) -> str:
    """Scrape content from a web page using CSS selectors."""
    import requests
    from bs4 import BeautifulSoup
    
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')
    elements = soup.select(selector)
    return "\n".join([el.get_text() for el in elements])

Tool composition patterns:

  • Sequential tool use: Agent uses tools one after another, each result informing next action.
  • Parallel tool use: Agent invokes multiple tools simultaneously when tasks are independent.
  • Conditional tool use: Agent decides tool usage based on intermediate results or constraints.
  • Tool error handling: Framework provides automatic retry logic, fallback mechanisms, and error context for agent recovery.

Memory Strategies and Management

BeeAI provides four memory implementations optimized for different use cases:

  • UnconstrainedMemory stores all messages without size limitations. Ideal for short conversation, complete audit trails, debugging sessions, context where full history is critical.
  • SlidingMemory maintains only the most recent k entries, ideal for long running conversations and resource-constrained environments, it prevents context window overflow
  • TokenMemory manages token usage to stay within model context limits and provide predictable usage patterns
  • SummarizeMemory maintains single summarization of conversation, and it’s ideal for long conevrsations and reducing their memory footprint
from beeai_framework.memory import UnconstrainedMemory
 
memory = UnconstrainedMemory()
agent = ReActAgent(llm=llm, memory=memory, tools=[])
from beeai_framework.memory import SlidingMemory
 
memory = SlidingMemory(k=10)  # Keep last 10 messages
agent = ReActAgent(llm=llm, memory=memory, tools=[])
from beeai_framework.memory import TokenMemory
 
memory = TokenMemory(max_tokens=4096)  # Stay within 4K token limit
agent = ReActAgent(llm=llm, memory=memory, tools=[])
from beeai_framework.memory import SummarizeMemory
 
memory = SummarizeMemory()
agent = ReActAgent(llm=llm, memory=memory, tools=[])

Custom memory implementation: Developers can create custom memory strategies by implementing base memory interface for specialized use cases like hierarchical memory, semantic memory, or external database-backed memory.

Multi-Agent Workflows and Orchestration

BeeAI supports complex multi-agent workflows with state management and handoff mechanisms:

  • HandoffTool pattern enables agent-to-agent delegation
  • Workflow patterns support more advanced orchestration
    • Sequential
    • Parallel
    • Supervisor
    • Conditional
from beeai_framework.agents.experimental import RequirementAgent
from beeai_framework.backend import ChatModel
from beeai_framework.memory import UnconstrainedMemory
from beeai_framework.tools.handoff import HandoffTool
from beeai_framework.tools.think import ThinkTool
from beeai_framework.tools.search.wikipedia import WikipediaTool
from beeai_framework.tools.weather import OpenMeteoTool
 
# Create specialized agents
knowledge_agent = RequirementAgent(
    llm=ChatModel.from_name("ollama:granite3.3"),
    tools=[ThinkTool(), WikipediaTool()],
    memory=UnconstrainedMemory(),
    instructions="Provide detailed, accurate information using knowledge sources."
)
 
weather_agent = RequirementAgent(
    llm=ChatModel.from_name("ollama:granite3.3"),
    tools=[ThinkTool(), OpenMeteoTool()],
    memory=UnconstrainedMemory(),
    instructions="Provide comprehensive weather information and forecasts."
)
 
# Create coordinator agent managing handoffs
coordinator_agent = RequirementAgent(
    llm=ChatModel.from_name("ollama:granite3.3"),
    memory=UnconstrainedMemory(),
    tools=[
        HandoffTool(
            target=knowledge_agent, 
            name="knowledge_specialist", 
            description="For general knowledge and research questions"
        ),
        HandoffTool(
            target=weather_agent, 
            name="weather_expert", 
            description="For weather-related queries"
        ),
    ],
    instructions="""Coordinate between specialist agents. 
    - For weather queries: use weather_expert
    - For research/knowledge questions: use knowledge_specialist  
    - For mixed queries: break them down and use multiple specialists"""
)
 
response = await coordinator_agent.run(
    "What's the weather in Paris and tell me about its history?"
)

Workflows use Pydantic models defining state passed between steps. State provides:

  • Type validation and safety
  • Persistence throughout execution
  • Shared context for all agents
  • Structured data exchange

Workflow transitions:

  • Return step name for explicit next step
  • Workflow.NEXT to proceed sequentially
  • Workflow.SELF to repeat current step
  • Workflow.END to terminate execution

Declarative orchestration: Complex agent systems definable in YAML promoting predictable and maintainable orchestration. YAML definitions specify agent roles, tools, memory configurations, and workflow logic.

Observability with OpenTelemetry

BeeAI provides some key capabilities around observability:

  • Distributed tracing: Track execution flow across multiple agents, tools, and services. Visualize complete request lifecycle from user input to final response.
  • Performance metrics: Monitor latency, throughput, error rates, token usage, and resource consumption. Identify bottlenecks and optimization opportunities.
  • Custom instrumentation: Add application-specific spans and metrics for domain-specific observability requirements.
  • Supported platforms:
    • Arize Phoenix
    • LangFuse: Export traces to LangFuse for advanced analytics and visualization.
    • LangSmith: Integration for Anthropic-specific observability and debugging.
    • Custom backends: Configure OTLP exporter for any OpenTelemetry-compatible backend (Jaeger, Zipkin, Datadog, New Relic).
from openinference.instrumentation.beeai import BeeAIInstrumentor
from opentelemetry import trace as trace_api
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
 
def setup_observability():
    resource = Resource(attributes={})
    tracer_provider = trace_sdk.TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        SimpleSpanProcessor(OTLPSpanExporter())
    )
    trace_api.set_tracer_provider(tracer_provider)
    
    BeeAIInstrumentor().instrument()
 
# Call before running any BeeAI code
setup_observability()

Constraint Enforcement and Governance

BeeAI provides built-in constraint enforcement and rule-based governance. The framework adopts an approach called deterministic rules: unlike prompt-based behavior guidance, BeeAI enforces rules at framework level ensuring compliance regardless of LLM output.

Constraint types:

  • Output constraints: Validate agent outputs against schemas, format requirements, or business rules. Reject invalid outputs automatically.
  • Behavior constraints: Enforce allowed actions, prevent prohibited tool usage, require approval for sensitive operations.
  • Resource constraints: Limit token usage, API calls, execution time, or cost per operation.
  • Security constraints: Enforce data access policies, prevent sensitive data leakage, require authentication for specific actions.

Implementation approaches:

  • Declarative constraints defined in agent configuration or YAML orchestration files.
  • Programmatic constraints implemented through custom validators or middleware.
  • Policy-as-code using external policy engines (OPA, Cedar) for complex governance requirements.

RequirementAgent enforcement: Specialized agent type designed for constraint-aware execution. Maintains reasoning abilities while ensuring deterministic compliance with defined requirements.

Version History and Linux Foundation Stewardship

April 2025: IBM contributed BeeAI to LF AI & Data Foundation (Linux Foundation) establishing open governance model. Contribution reflects commitment to open collaboration and responsible AI development.

Latest release (as of May 5, 2025): Version 0.1.21 including bug fixes for datetime field retrieval.

Future roadmap priorities:

  • Enhanced workflow composition capabilities
  • Additional LLM provider integrations
  • Improved constraint enforcement mechanisms
  • Advanced observability features
  • Performance optimizations
  • Extended MCP integration
  • Multi-language support beyond Python/TypeScript

Graph View

Backlinks

  • No backlinks found