# BeeAI Framework: features, protocols, quickstart

## TL;DR

BeeAI Framework is an Apache-2.0 agent library for Python and TypeScript, first written by IBM developers and now developed by BeeAI contributors under the Linux Foundation AI & Data program. Its RequirementAgent enforces rules on tool use, and agents can be served over A2A or MCP. It suits teams wanting rule-constrained agents on local or hosted models.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python, TypeScript |
| License | Apache-2.0 |
| Pricing model | Open source, free |
| Orchestration pattern | Supervisor |
| GitHub stars | 3,423 (as of 2026-09-30) |
| GitHub forks | 509 |
| Last push | 2026-09-28 |
| Latest release | python_v0.1.85 |
| Repository | [i-am-bee/beeai-framework](https://github.com/i-am-bee/beeai-framework) |
| Website | [framework.beeai.dev](https://framework.beeai.dev/introduction/welcome) |
| Documentation | [framework.beeai.dev](https://framework.beeai.dev/introduction/welcome) |
| Last verified | 2026-09-30 |

## Key features

- RequirementAgent constrains tool use with declarative rules, such as forcing a tool at a given step, allowing a tool only after another, or capping invocations. ([source](https://framework.beeai.dev/modules/agents/requirement-agent))
- HandoffTool wraps a specialist agent as a tool, so a lead agent can consult several specialists in one run. ([source](https://github.com/i-am-bee/beeai-framework/blob/main/python/examples/agents/requirement/handoff.py))
- Workflows hold a typed state object and named steps that return the next step, NEXT, SELF or END; AgentWorkflow chains agents as steps. ([source](https://framework.beeai.dev/modules/workflows))
- Memory strategies: unconstrained, sliding window of the last k entries, token-budgeted, and a single running summary. ([source](https://framework.beeai.dev/modules/memory))
- Serve module hosts agents over A2A, MCP, ACP for the Zed editor, IBM watsonx Orchestrate, and OpenAI Chat Completions or Responses-compatible endpoints. ([source](https://framework.beeai.dev/modules/serve))
- MCPTool consumes tools from MCP servers, and MCPServer exposes BeeAI tools, agents or chat models over MCP. ([source](https://framework.beeai.dev/integrations/mcp))
- A2AAgent calls remote A2A agents and A2AServer publishes a BeeAI agent over A2A. ([source](https://framework.beeai.dev/integrations/a2a))
- A Serializer saves and rebuilds framework objects, which is how agent state is persisted between sessions. ([source](https://framework.beeai.dev/modules/serialization))

## Architecture and orchestration pattern

Pattern: Supervisor.

The main agent type is `RequirementAgent`: a tool-calling loop whose choices are narrowed by requirements. A `ConditionalRequirement` can force a tool at a given step, allow it only after another tool, forbid consecutive calls, or set minimum and maximum invocation counts; middleware such as `GlobalTrajectoryMiddleware` observes every step through the event emitter.

Multi-agent setups come in two forms. With `HandoffTool`, a lead agent treats specialist agents as tools, calls them, and uses their answers in its own reply (the README's multi-agent example). With workflows, a `Workflow` holds a typed state model and named steps, each returning the next step or `NEXT`, `SELF` or `END`, and workflows can nest; `AgentWorkflow` adds agents as sequential steps so a final agent can combine earlier results.

Each agent carries a memory object: `UnconstrainedMemory`, `SlidingMemory`, `TokenMemory` or `SummarizeMemory`. Longer-lived state is handled by the `Serializer`, and servers such as `A2AServer` keep per-session memory through a memory manager (an LRU manager in the example).

### Human in the loop

In Python, `AskPermissionRequirement` marks tools that need approval before they run; by default the approval is a simple prompt in the terminal, and a custom `handler` can route the decision to an external system or UI. The docs state this requirement is not yet implemented in TypeScript. No other interrupt or edit-state mechanism is described on the pages read.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://framework.beeai.dev/integrations/mcp) | Client and server: MCPTool consumes tools from MCP servers and MCPServer exposes BeeAI tools, agents or chat models, with Python and TypeScript examples. |
| A2A | Yes (checked 2026-09-30) | [link](https://framework.beeai.dev/integrations/a2a) | Client (A2AAgent) and server (A2AServer, one agent per server). The page carries a 'Supported in Python only' note but also shows TypeScript examples, and the repo has a TypeScript a2a adapter. |
| AG-UI | Unknown (checked 2026-09-30) | — | Searched README, docs llms.txt, GitHub code and issues for ag-ui / agui, and the AG-UI README integration list; nothing found. |

## Best for

- Agents that must follow a fixed tool order or call limits regardless of which model runs them.
- Teams building agents in TypeScript as well as Python from one framework.
- Running on local models through Ollama, as the README multi-agent example does.
- Publishing an agent to other systems over A2A, MCP or an OpenAI-compatible API.

## Not for

- Projects that need a vendor support commitment; the README says IBM has no obligation to maintain or support the code.
- TypeScript projects that need tool approval gates; AskPermissionRequirement is Python-only for now.
- Teams wanting a stable 1.x API; both libraries are still at 0.1.x.

## Quickstart

```sh
pip install beeai-framework
```

Install not yet verified by this site.

```python
import asyncio

from beeai_framework.agents.requirement import RequirementAgent
from beeai_framework.backend import ChatModel
from beeai_framework.tools.handoff import HandoffTool
from beeai_framework.tools.weather import OpenMeteoTool


async def main() -> None:
    llm = ChatModel.from_name("ollama:granite4.1:8b")  # local model served by Ollama
    weather = RequirementAgent(llm=llm, tools=[OpenMeteoTool()], role="Weather Specialist",
                               instructions="Give short forecasts for a named city.")
    lead = RequirementAgent(name="Lead", llm=llm, tools=[
        HandoffTool(weather, name="WeatherLookup", description="Ask the weather specialist.")])
    result = await lead.run("Should I pack an umbrella for Rome this weekend?")
    print(result.last_message.text)


asyncio.run(main())
```

### Common pitfalls

- The Python package requires Python >=3.11 and <3.14.
- Protocol integrations are extras: `pip install 'beeai-framework[a2a]'`, `[mcp]`, `[agentstack]` or `[acp-zed]`.
- The README example needs Ollama running with `granite4.1:8b` pulled; hosted models use `provider:model` names such as `openai:gpt-5-mini` plus the provider's API key.
- The docs quickstart uses the starter repositories (`uv sync` for Python, `npm ci` for TypeScript) rather than a bare install.
- `AskPermissionRequirement` is not implemented in TypeScript, and an A2A server hosts only one agent.

Official quickstart: https://github.com/i-am-bee/beeai-framework#installation

## Pros

- Python and TypeScript libraries live in one repository with matching module names. ([source](https://github.com/i-am-bee/beeai-framework))
- RequirementAgent gives explicit, testable control over tool order and call counts. ([source](https://framework.beeai.dev/modules/agents/requirement-agent))
- One serve module exposes agents over A2A, MCP, ACP (Zed), watsonx Orchestrate and OpenAI-style APIs. ([source](https://framework.beeai.dev/modules/serve))
- Both MCP directions (consume and expose) are documented for Python and TypeScript. ([source](https://framework.beeai.dev/integrations/mcp))
- Governed as a Linux Foundation AI & Data project rather than by a single vendor. ([source](https://github.com/i-am-bee/beeai-framework#legal-notice))

## Cons

- The README's legal notice says IBM provided the code as an open-source project, not an IBM product, with no obligation to provide updates or support. ([source](https://github.com/i-am-bee/beeai-framework#legal-notice))
- TypeScript lags Python: AskPermissionRequirement (tool approval) is not implemented in TypeScript. ([source](https://framework.beeai.dev/modules/agents/requirement-agent))
- An open issue tracks bringing recoverable tool timeouts, already added in Python, to TypeScript. ([source](https://github.com/i-am-bee/beeai-framework/issues/1653))
- Still pre-1.0 in both languages (python_v0.1.85 and typescript_v0.1.31 in September 2026). ([source](https://github.com/i-am-bee/beeai-framework/releases))
- An A2A server can host only one agent. ([source](https://framework.beeai.dev/integrations/a2a))

## Alternatives

- [Google ADK (Python)](https://multiagentguide.top/tools/google-adk.md)
- [OpenAI Agents SDK (Python)](https://multiagentguide.top/tools/openai-agents-sdk.md)
- [Pydantic AI](https://multiagentguide.top/tools/pydantic-ai.md)
- [Mastra](https://multiagentguide.top/tools/mastra.md)
- [Strands Agents](https://multiagentguide.top/tools/strands-agents.md)

## FAQ

### Does BeeAI Framework support MCP and A2A?

Yes to both. MCPTool and MCPServer cover consuming and exposing MCP tools; A2AAgent and A2AServer cover calling and publishing A2A agents. AG-UI support was not found.

### Is BeeAI Framework free?

Yes. It is Apache-2.0 licensed and no paid tier of the framework is documented. You pay only for any hosted model you choose; local models run through Ollama.

### Which languages does BeeAI Framework support?

Python (3.11 to 3.13) and TypeScript. Some features, such as AskPermissionRequirement, exist only in Python so far.

### Is BeeAI Framework still maintained by IBM?

The README's legal notice says IBM has no obligation to support the code and will not maintain it going forward; development continues through BeeAI contributors under the Linux Foundation AI & Data program, with releases as recent as September 2026.

### How do multiple BeeAI agents work together?

Either a lead agent calls specialist agents through HandoffTool, or a Workflow/AgentWorkflow runs agents as steps over a shared typed state.

## Sources

- [BeeAI Framework GitHub repository (README)](https://github.com/i-am-bee/beeai-framework)
- [README: installation](https://github.com/i-am-bee/beeai-framework#installation)
- [README: legal notice](https://github.com/i-am-bee/beeai-framework#legal-notice)
- [BeeAI Framework documentation](https://framework.beeai.dev/introduction/welcome)
- [Quickstart](https://framework.beeai.dev/introduction/quickstart)
- [Requirement Agent](https://framework.beeai.dev/modules/agents/requirement-agent)
- [Workflows](https://framework.beeai.dev/modules/workflows)
- [Memory](https://framework.beeai.dev/modules/memory)
- [Serve](https://framework.beeai.dev/modules/serve)
- [Serialization](https://framework.beeai.dev/modules/serialization)
- [MCP integration](https://framework.beeai.dev/integrations/mcp)
- [A2A integration](https://framework.beeai.dev/integrations/a2a)
- [Official handoff example (Python)](https://github.com/i-am-bee/beeai-framework/blob/main/python/examples/agents/requirement/handoff.py)
- [Releases](https://github.com/i-am-bee/beeai-framework/releases)
- [Issue #1653: recoverable tool timeouts in TypeScript](https://github.com/i-am-bee/beeai-framework/issues/1653)

## Unknown fields

protocols.agui is unknown: README, docs llms.txt, GitHub code search and issue search for ag-ui / agui returned nothing, and BeeAI is not in the AG-UI README integration list.

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/beeai-framework