BeeAI Framework 是 IBM 主导开发、现由 Linux Foundation AI & Data 托管的一个开源框架，用于构建生产级的多智能体系统，同时支持 Python 和 TypeScript。

它的核心设计是“可插拔”：LLM 后端、工具、记忆、协议层都是模块化的，你可以用几行代码把 Agent 挂到 A2A 或 MCP 服务器上对外服务。

以下是完整的部署教程。

1. 环境要求

要求 Python 路线 TypeScript 路线
语言运行时 Python 3.11+ Node.js (建议 LTS 版本)
包管理器 uv（推荐）或 pip npm
容器环境 Docker / Rancher / Podman（代码解释器需要） 同上
LLM 后端 Ollama（本地）或任意云端 API Key 同左

关于 uv：BeeAI 的 Python Starter 模板使用 uv 管理依赖，它比 pip 快很多，且能自动处理虚拟环境。安装方式见 uv 官方文档。

2. 快速开始（推荐路径）

BeeAI 官方提供了 Starter 模板，已经配置好依赖、linting、Docker Compose 和示例 Agent。这是最省事的入门方式。

2.1 克隆 Starter 模板

1
2
3
4
5
6
7
# Python
git clone https://github.com/i-am-bee/beeai-framework-py-starter.git
cd beeai-framework-py-starter

# TypeScript
git clone https://github.com/i-am-bee/beeai-framework-ts-starter.git
cd beeai-framework-ts-starter

2.2 安装依赖

1
2
3
4
5
6
# Python
uv sync

# TypeScript
nvm install && nvm use
npm ci

2.3 配置环境变量

1
cp .env.template .env

编辑 .env，至少设置以下一项：

方式一：使用本地 Ollama（免费）

1
2
LLM_CHAT_MODEL_NAME="ollama:granite4.1:8b"
OLLAMA_BASE_URL=http://localhost:11434

然后拉取模型：

1
ollama pull granite4.1:8b

方式二：使用云端 API（以 OpenAI 为例）

1
2
LLM_CHAT_MODEL_NAME="openai:gpt-4o-mini"
OPENAI_API_KEY="sk-..."

BeeAI 支持 15+ 家 LLM 提供商，包括 Anthropic、Watsonx、Azure OpenAI、Groq 等，只需在 .env 中填入对应提供商的 API Key 即可。

2.4 启动基础设施服务（可选但推荐）

Starter 模板包含一个代码解释器服务，Agent 可以用它执行 Python 代码：

1
uv run poe infra --type start

服务启动后运行在 http://127.0.0.1:50081。

2.5 运行第一个 Agent

1
uv run python beeai_framework_starter/agent.py

这是一个活动规划助手，它会调用天气工具来回答“明天出门该穿什么”之类的问题。输入 q 退出。

3. 从零手动搭建（不使用 Starter）

如果你想把 BeeAI 集成到已有项目中，可以直接安装库：

1
2
3
4
5
# Python
pip install beeai-framework

# TypeScript
npm install beeai-framework

然后创建一个 .env 文件配置 LLM：

1
2
3
4
5
6
7
8
# 本地 Ollama
OLLAMA_BASE_URL=http://localhost:11434

# 或者 OpenAI
OPENAI_API_KEY=sk-...

# 或者 Anthropic
ANTHROPIC_API_KEY=sk-ant-...

BeeAI 的配置优先级是：构造函数参数 > 环境变量 > 提供商默认值。

4. 运行多智能体示例

BeeAI 官方 README 提供了一个“知识 Agent + 天气 Agent + 主 Agent”的 Handoff 示例，展示了多智能体协作的核心模式。

创建一个文件 multi_agent.py：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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.1:8b"),
        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.1:8b"),
        tools=[OpenMeteoTool()],
        role="Weather Specialist",
        instructions="Provide weather forecast for a given destination.",
    )

    main_agent = RequirementAgent(
        name="MainAgent",
        llm=ChatModel.from_name("ollama:granite4.1:8b"),
        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)],
        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())

运行：

1
python multi_agent.py

这个示例的关键点是 HandoffTool——主 Agent 可以把子任务“移交”给专门的子 Agent，子 Agent 完成后结果会返回给主 Agent 汇总。

5. 暴露 Agent 为服务（Serve 模块）

BeeAI 的 Serve 模块让你可以把 Agent 通过 A2A 或 MCP 协议暴露给外部客户端调用。

安装协议支持

1
2
3
4
5
# A2A 协议
pip install beeai-framework[a2a]

# MCP 协议
pip install beeai-framework[mcp]

启动 A2A 服务器

1
2
3
4
5
6
7
8
9
from beeai_framework.adapters.a2a import A2AServer
from beeai_framework.agents.requirement import RequirementAgent
from beeai_framework.backend import ChatModel

llm = ChatModel.from_name("ollama:granite4.1:8b")
agent = RequirementAgent(llm=llm)

server = A2AServer().register(agent)
server.serve()

默认监听 localhost:9999。客户端可以通过 A2AAgent(url="http://127.0.0.1:9999") 连接并发送任务。

6. 可观测性（Observability）

BeeAI 内置了基于 OpenInference 的追踪支持，可以把 Agent 内部的每一步（工具调用、LLM 请求、推理步骤）导出到 Phoenix 或 Arize AX 等平台。

使用 Phoenix（本地）

1
docker run -p 6006:6006 -i -t arizephoenix/phoenix:latest

然后运行 Starter 模板中的观测示例：

1
python beeai_framework_starter/agent_observe.py

打开 localhost:6006 即可看到完整的调用链。

使用 Arize AX（云端）

1
pip install arize-otel openinference-instrumentation-beeai beeai-framework
1
2
3
4
5
6
7
8
9
10
import os
from arize.otel import register
from openinference.instrumentation.beeai import BeeAIInstrumentor

tracer_provider = register(
    space_id=os.environ["ARIZE_SPACE_ID"],
    api_key=os.environ["ARIZE_API_KEY"],
    project_name="beeai-tracing-example",
)
BeeAIInstrumentor().instrument(tracer_provider=tracer_provider)

注意要在导入 beeai_framework 之前初始化 instrumentor，否则追踪不会生效。

7. 常见问题

LLM 连接失败：检查 .env 中的 API Key 是否正确；如果使用 Ollama，确认 ollama serve 正在运行且模型已拉取；可以用 ollama list 验证模型名称。

代码解释器启动失败：确认 Docker/Rancher 正在运行；uv run poe infra --type start 需要 Compose 支持。

A2A/MCP 服务器无法注册 Agent：检查是否安装了对应的 extra（pip install beeai-framework[a2a]），以及 Agent 类型是否被服务器支持。如果不支持，需要注册自定义 factory。

Python 版本问题：BeeAI Framework 要求 Python 3.11+，低版本会直接报错。

8. 学习路径建议

  1. 先跑通 Starter 模板 → 理解 Agent + Tools 的基本模式
  2. 运行多智能体 Handoff 示例 → 理解 RequirementAgent 和协作机制
  3. 查看 python/examples/ 目录 → 覆盖 Memory、Templates、RAG、Serve 等模块的独立示例
  4. 按需接入 Serve 模块 → 把 Agent 变成可被外部调用的 HTTP 服务