---
title: "BeeAIフレームワークとは？IBM発エージェント基盤の使い方とRequirementAgentチュートリアル"
url: "https://www.issoh.co.jp/tech/details/8653/"
published: 2025-09-04
updated: 2026-10-07
categories: ["AIエージェント・MCP"]
publisher: "株式会社一創"
---

# BeeAIフレームワークとは？IBM発エージェント基盤の使い方とRequirementAgentチュートリアル

BeeAI Framework（ビーエーアイ・フレームワーク）は、IBM Researchが始めたAIエージェント開発用のオープンソースフレームワークです。PythonとTypeScriptの2つのライブラリがあり、現在はLinux Foundation傘下のプロジェクトとして開発されています。2026年10月7日時点の最新版は、Python版が0.1.85、TypeScript版が0.1.31（どちらも2026年9月28日公開）です。

この記事では、まず「BeeAI」の名前で呼ばれてきた複数のプロジェクトを整理します。そのうえで、公式が推奨するRequirementAgentを使ったエージェントの作り方を、0.1.85で動かしたコードで説明します。後半では、複数エージェントへの委譲、外部への公開方法、採用を見送るべき条件を扱います。

## まとめ：BeeAIフレームワークの現状と始め方の要点

- **正体**：IBM Research発のエージェント開発フレームワーク。ライセンスはApache-2.0、著作権表記は「BeeAI a Series of LF Projects, LLC」。
- **最新版**：Python 0.1.85（`pip install beeai-framework`）、TypeScript 0.1.31（`npm install beeai-framework`）。Python版はPython 3.11以上3.14未満が必要。
- **使うエージェント**：`RequirementAgent`。ReActAgentは積極的なサポートの対象外になり、ToolCallingAgentは0.1.73で非推奨になった。
- **RequirementAgentの肝**：要件（`ConditionalRequirement`）を満たすまで、LLMに渡すツールの一覧から該当ツールや `final_answer` を外す。プロンプトのお願いではなく、選べる手を減らして順序を守らせる。
- **名前の整理**：旧BeeAI PlatformはAgent Stackに改称。IBMのACP（Agent Communication Protocol）は2025年8月25日にA2Aへ合流し、リポジトリはアーカイブ済み。
- **向かない場面**：1.0未満の版で長期間APIを固定したい場合と、TypeScript版のRequirementAgentをA2Aで公開したい場合（0.1.31の標準のA2Aサーバーは未対応）。

## BeeAIフレームワークの成り立ちと2026年の位置づけ

### Bee Agent Frameworkの成立とLinux Foundation傘下への移行

GitHubリポジトリ `i-am-bee/beeai-framework` の作成日は2024年8月23日です。当初の名前はBee Agent Frameworkで、TypeScriptのライブラリとして始まりました。2024年9月作成のTypeScriptスターターの説明文には、今も「Bee Agent Framework」の名前が残っています。

Python版はREADMEの更新履歴によると2025年2月19日にアルファ版が出ました。その後の機能追加はPythonが先行しており、2025年6月3日には実験機能としてRequirementAgentが公開されています。ソースの著作権表記は「BeeAI a Series of LF Projects, LLC」で、READMEにはLF AI & Dataのバッジがあります。

一方、Bee Stack・Bee UI・bee-apiなど初期のアプリ一式のリポジトリは、2025年3月18日を最後に更新が止まり、アーカイブされています。「Bee」で検索して見つかる2024年の情報は、このアーカイブ済みの構成を前提にしていることが多い点に注意してください。

### 最新版と動作要件

| 項目               | Python版               | TypeScript版          |
| ---------------- | --------------------- | -------------------- |
| パッケージ名           | beeai-framework（PyPI） | beeai-framework（npm） |
| 最新版              | 0.1.85                | 0.1.31               |
| 公開日              | 2026-09-28            | 2026-09-28           |
| 言語要件             | Python 3.11以上3.14未満   | Node.js              |
| RequirementAgent | あり（推奨）                | ソースにあり               |
| A2A連携            | あり                    | 実装・公式例あり             |

Pythonの上限には注意が要ります。PyPIのメタデータでは、0.1.79までは `<4.0,>=3.11` でしたが、0.1.80から `<3.14,>=3.11` に変わりました。Python 3.14の環境に入れる前に、仮想環境を3.12や3.13で作っておくのが確実です。

「両言語で機能は完全に同じ」という説明は、2025年時点の資料によく見られます。LiteAgentには「Pythonのみ」の注記があります。A2Aにも同じ注記が残っていますが、同じページにTypeScriptのクライアント・サーバー例があり、注記と実装が一致していません。TypeScript 0.1.31のA2Aサーバーが標準で受け付けるのはReActAgentとToolCallingAgentで、RequirementAgent用の実行処理は登録されていません。

## 「BeeAI」と名の付く3つのプロジェクトとACPの関係

検索で「beeai platform」「ibm bee」と調べると、フレームワーク以外のプロジェクトが混ざって出てきます。現在の名前と状態を表にまとめます。

| 名前              | 役割               | 2026年10月の状態            |
| --------------- | ---------------- | ---------------------- |
| BeeAI Framework | エージェントを書くライブラリ   | 開発継続（Python 0.1.85）    |
| BeeAI Platform  | エージェントの実行・共有基盤   | Agent Stackへ改称（v0.7.1） |
| ACP（IBM）        | エージェント間通信の仕様     | A2Aへ合流・アーカイブ           |
| ACP（Zed）        | エディタとエージェントの接続仕様 | 別物・acp-zed拡張で対応        |

### BeeAI Platformの改称とAgent Stackへの移行

GitHubで `i-am-bee/beeai-platform` を開くと、`i-am-bee/agentstack` に転送されます。Agent Stackは、エージェントをHTTPのサービスとして動かすための実行基盤で、Web UI・CLI・LLMの接続先切り替え・ファイル保存・Kubernetes向けHelmチャートを含みます。最新リリースはv0.7.1（2026年3月30日）です。

フレームワーク側の旧連携モジュール `beeai_framework.adapters.beeai_platform` は、0.1.85でimportすると非推奨の警告を出します。新しく書くコードでは `beeai-framework[agentstack]` の拡張と `AgentStackAgent` を使います。

### ACPは2025年8月にA2Aへ合流

IBMが2025年春に公開したAgent Communication Protocol（ACP）は、2025年8月25日にLinux Foundation傘下のA2A（Agent2Agent）プロトコルへ合流しました。`i-am-bee/acp` リポジトリはこの日を最後に更新が止まってアーカイブされ、READMEにはA2Aへの移行ガイドへのリンクがあります。旧記事でACPを「BeeAIの相互運用の要」と説明していたものは、今はA2Aに読み替える必要があります。A2Aそのものの仕組みは[A2A（Agent2Agent）プロトコルの解説](/tech/details/6732/)で扱っています。

紛らわしいのは、0.1.85に `acp-zed` という拡張があることです。これはZedエディタのAgent Client Protocolで、略称が同じでも別の仕様です。BeeAIのエージェントを1プロセス1エージェントとしてstdioで起動し、Zedのエージェントパネルから使えるようにします。

## BeeAIのエージェント4種類と選び方

0.1.85のドキュメントには、エージェントの実装が4つ載っています。新しく書くならRequirementAgent一択で、ほかは理由がある場合だけ使います。

| クラス              | 位置づけ                  | 対応言語              |
| ---------------- | --------------------- | ----------------- |
| RequirementAgent | 推奨。要件でツールの使い方を制約      | Python（TSもソースにあり） |
| LiteAgent        | システムプロンプトなしの素の実装      | Python            |
| ReActAgent       | 思考・行動・観察の繰り返し。積極サポート外 | Python・TypeScript |
| ToolCallingAgent | 0.1.73で非推奨            | Python・TypeScript |

ToolCallingAgentには `@deprecated(reason="Use RequirementAgent instead.", version="0.1.73")` が付いています。ReActAgentは、ドキュメント上「利用はできるが積極的にはサポートしない」扱いです。ReActの考え方自体は[ReActパターンの解説](/tech/details/16312/)を参照してください。

LiteAgentは、フレームワークが用意するシステムプロンプトを持ちません。モデルの素の能力を確かめたいときや、エージェントの仕組みを学ぶときに使います。本番ではRequirementAgentの制約がある方が扱いやすくなります。

## BeeAIエージェントのチュートリアル：RequirementAgentを動かす手順

### インストールとLLMの指定

以下はmacOS・Linux向けの手順です。Python 3.12を用意し、仮想環境を作ってパッケージを入れます。Ollamaもインストールして起動し、`ollama pull granite4:micro` でモデルを取得します。後掲の在庫コードを `stock_agent.py` に保存し、`python stock_agent.py` で実行します。

```
python3.12 -m venv .venv
source .venv/bin/activate
pip install "beeai-framework==0.1.85"
```

LLMは `ChatModel.from_name("プロバイダ:モデル名")` の文字列で指定します。ローカルで試すならOllamaにIBMのGraniteを入れ、`ollama:granite4:micro` を指定するのが公式ドキュメントの例です。0.1.85のバックエンド対応表には、Ollama・OpenAI・IBM watsonx.ai・Anthropic・Groq・Amazon Bedrock・Google Vertex・Azure OpenAI・xAI・Google Gemini・MistralAI・Transformers・MiniMaxの13プロバイダが載っています。APIキーは `OPENAI_API_KEY` のような環境変数で渡します。

### 自作ツールと要件を付けたエージェントのコード

固定の在庫データを返す模擬ツールを持ち、「最初に考える」「在庫ツールを最低1回呼ぶ」という2つの要件を付けたエージェントです。実際の在庫システムには接続しません。

```
import asyncio
import json

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.memory import UnconstrainedMemory
from beeai_framework.middleware.trajectory import GlobalTrajectoryMiddleware
from beeai_framework.tools import tool
from beeai_framework.tools.think import ThinkTool


@tool()
def get_stock(sku: str) -> str:
    """Returns current stock count for a SKU."""
    stock = {"A-100": 12, "B-200": 0}
    return json.dumps({"sku": sku, "stock": stock.get(sku)})


async def main() -> None:
    agent = RequirementAgent(
        llm=ChatModel.from_name("ollama:granite4:micro"),
        memory=UnconstrainedMemory(),
        tools=[ThinkTool(), get_stock],
        requirements=[
            ConditionalRequirement(ThinkTool, force_at_step=1),
            ConditionalRequirement(get_stock, min_invocations=1),
        ],
        role="在庫アシスタント",
        instructions="在庫数は必ずツールで確認してから答える",
    )
    response = await agent.run("SKU A-100 の在庫は？").middleware(GlobalTrajectoryMiddleware())
    print(response.last_message.text)


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

`@tool()` デコレータは、関数の型ヒントとdocstringからツールの入力スキーマと説明を作ります。docstringはそのままLLMへのツール説明になるので、何を返すかを具体的に書きます。`GlobalTrajectoryMiddleware` を付けると、LLM呼び出し・ツール実行・要件の判定が順にコンソールへ出力されます。

このコードは、beeai-framework 0.1.85をPython 3.12に入れ、LLMの代わりに応答を固定したテスト用モデル（リポジトリの `tests/agents/_scripted.py`）を差し込んで実行し、「A-100の在庫は12個です」が返ることを確認しています。実際のLLMを使う場合の応答内容は、モデルによって変わります。

### 要件がLLMに渡すツールを段階ごとに絞る仕組み

RequirementAgentの特徴は、要件をプロンプトの指示として書くのではなく、各ステップでLLMに渡すツールの一覧と `tool_choice` を書き換える点にあります。上のエージェントで、モデルが途中で早まって `final_answer` を呼ぶ台本を流し、各ステップでLLMが受け取った内容を記録しました。

| ステップ | LLMに渡されたツール                      | tool\_choice | モデルの応答             |
| ---- | -------------------------------- | ------------ | ------------------ |
| 1    | think                            | think        | think              |
| 2    | think, get\_stock                | required     | final\_answer（提示外） |
| 3    | think, get\_stock                | required     | get\_stock         |
| 4    | think, get\_stock, final\_answer | required     | final\_answer      |

読み取れることは3つあります。1つ目に、`force_at_step=1` は1ステップ目のツールを `think` だけにし、`tool_choice` でも指名します。2つ目に、`min_invocations=1` を満たすまで、`final_answer` はツール一覧に入りません。システムプロンプト上でも「Allowed: False」と表示されます。3つ目に、提示されていない `final_answer` を呼んだ2ステップ目の応答はメモリに残らず、同じ段階がやり直されました。最終的なメモリはユーザー入力1件とツール呼び出し・結果3往復の計7件で、記録されたステップは3つでした。

小さなモデルは、ツールを呼ばずに推測で答えたり、同じツールを繰り返し呼んだりしがちです。この仕組みなら、守らせたい順序をモデルの賢さに頼らず強制できます。要件にはほかに、`only_after`（指定ツールの後にだけ許可）、`consecutive_allowed=False`（連続呼び出しの禁止）、`max_invocations` などがあります。ツール実行前に人の承認を求める `AskPermissionRequirement` も用意されています。

### 実行回数の上限と止め方

`agent.run()` には上限を渡せます。0.1.85のRequirementAgentの既定値は、`max_iterations=20`、`total_max_retries=20`、`max_retries_per_step=3` です。モデルが要件を満たせない場合は、反復・再試行の上限や循環検出などによって実行が終了します。そのため、本番では `max_iterations` を処理に見合う小さな値にし、`FrameworkError` を捕まえて `err.explain()` で原因を出す形にします。

出力の形式を決めたいときは、`expected_output` にPydanticモデルかJSON Schemaを渡します。結果は `response.output_structured` で受け取れます。

## 複数エージェントを協調させる2つの方法

BeeAIでマルチエージェントを組む方法は、親エージェントが子へ仕事を渡す `HandoffTool` と、決まった順に処理を流す `AgentWorkflow` の2つです。そもそも複数エージェントに分けるべきかの判断は、[シングルエージェントとマルチエージェントの違い](/tech/details/4261/)で整理しています。

### HandoffToolによる専門エージェントへの委譲

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

llm = ChatModel.from_name("ollama:granite4:micro")
legal = RequirementAgent(llm=llm, role="法務担当", instructions="契約条項を確認する")
boss = RequirementAgent(
    llm=llm,
    tools=[HandoffTool(legal, name="LegalReview", description="契約の法務確認を依頼する")],
)
```

親エージェントから見ると、子エージェントは `task` という文字列を1つ受け取るツールです。Python 3.12・beeai-framework 0.1.85で、応答を固定したテスト用モデルを使って委譲処理を実行し、[HandoffToolのソース（python\_v0.1.85タグ）](https://github.com/i-am-bee/beeai-framework/blob/python%5Fv0.1.85/python/beeai%5Fframework/tools/handoff.py)と照らして次の3点を確認しました。

- ツール名は `to_safe_word` で整形され、`LegalReview` は `legalreview` としてLLMに渡る。
- 呼ばれるたびに子エージェントを複製し、親の会話履歴（システムメッセージを除く）をコピーしたうえで、`task` をユーザー発話として足して実行する。
- 子の最後の応答の文字列が、親のメモリにツール結果として入る。

子には、システムメッセージと末尾の未完了ツール呼び出しを除いた親の履歴が渡るため、その範囲の文脈を引き継げます。その代わり、会話が長くなると子のトークン消費も増えます。0.1.85のHandoffToolには履歴のコピーを止める引数がなく、`propagate_inputs=False` で止まるのは `task` の追加だけです。子に渡す文脈を絞りたい場合は、親のメモリを `SlidingMemory` などで短く保ちます。

### AgentWorkflowによるエージェントの逐次実行

`AgentWorkflow` は、登録したエージェントを入力の順に1つずつ実行し、前のエージェントの最後のやり取りを次へ渡します。公式の例では、調査役・天気担当・要約役の3エージェントに順番に仕事をさせています。

注意点は、`add_agent(name=..., role=..., llm=...)` のようにキーワード引数で登録すると、内部で非推奨のToolCallingAgentが作られることです。0.1.85のソースで確認しました。RequirementAgentで統一したい場合は、`add_agent(RequirementAgent(...))` のようにインスタンスを渡します。

## メモリ・可観測性・RAGなど周辺モジュール

0.1.85のPython版に入っているメモリは次の4種類です（読み取り専用ラッパーの `ReadOnlyMemory` を除く）。

| クラス                 | 保持のしかた        | 主な引数                        |
| ------------------- | ------------- | --------------------------- |
| UnconstrainedMemory | 全メッセージを保持     | なし                          |
| SlidingMemory       | 直近N件だけ保持      | SlidingMemoryConfig(size=…) |
| TokenMemory         | トークン上限で古い順に削除 | max\_tokens                 |
| SummarizeMemory     | LLMで要約して保持    | model                       |

どれも1回の会話の中の短期記憶です。セッションをまたぐ長期記憶は、シリアライズ機能で状態を保存するか、外部のストアを自分で組み合わせます。設計の考え方は[エージェントメモリの解説](/tech/details/16053/)にまとめています。

可観測性は、OpenInferenceの計装パッケージ `openinference-instrumentation-beeai` で、エージェント・ツール・LLM呼び出しをOpenTelemetryのスパンとして出力します。公式例の送信先はArize Phoenixです。属性の体系は[OpenTelemetryのGenAIセマンティック規約](/tech/details/17007/)と合わせて確認してください。

ほかに、ベクトルストアと文書処理をまとめたRAG、LLM応答とツール出力のキャッシュ、DeepEval・Ragasを使う評価モジュールがあり、RAG用の追加依存は `pip install "beeai-framework[rag]"`、評価用は `pip install "beeai-framework[evaluation]"` で入れます。基本的なキャッシュ機能に追加の拡張は不要です。

## 作ったエージェントを外部へ公開するServeモジュール

Serveモジュールは、BeeAIで作ったエージェントやツールをサーバーとして公開します。サーバークラスを作り、`register` で登録して `serve` で起動する流れはどの方式でも共通です。

| 公開方式                                  | インストール                                 |
| ------------------------------------- | -------------------------------------- |
| A2A                                   | beeai-framework\[a2a\]                 |
| Agent Stack                           | beeai-framework\[agentstack\]          |
| MCP                                   | beeai-framework\[mcp\]                 |
| ACP（Zed・stdio）                        | beeai-framework\[acp-zed\]             |
| IBM watsonx Orchestrate               | beeai-framework\[watsonx-orchestrate\] |
| OpenAI Chat Completions・Responses API | beeai-framework                        |

IBMの業務自動化製品watsonx Orchestrateとつなぐ場合は、`WatsonxOrchestrateServer` でエージェントを `/chat/completions` のエンドポイントとして公開します。Orchestrate側では、そのURLとAPIキーを外部エージェントとして登録します。IBMのwatsonx Orchestrate開発者向けチュートリアルでは、IBM Code Engineへのデプロイまでの手順が示されています。

MCPは、BeeAIのエージェントが外部のMCPサーバーのツールを使う方向（クライアント）と、BeeAIのツールをMCPサーバーとして出す方向の両方に対応しています。MCPのツール接続の設計は[AIエージェントにMCPで外部ツールを接続する実装手順](/tech/details/15365/)が参考になります。

## BeeAIを採用すべき場面と見送るべき場面

BeeAIを採用候補にする理由が具体的になるのは、次の2つの場面です。

- **小型モデルにツールの手順を守らせたい**：GraniteのようなローカルのSLMで、「必ず検索してから答える」「この順で呼ぶ」を強制したい場合。RequirementAgentはツール一覧そのものを絞るので、プロンプトの指示より確実に効きます。
- **watsonx OrchestrateやA2Aで外部に出す**：Serveモジュールで公開まで同じライブラリで済みます。

反対に、次の条件に当てはまるなら別の選択肢を先に検討します。

- **APIを長く固定したい**：版は0.1.xのままで、Python版は2026年1〜9月に11回リリースされています。ToolCallingAgentの非推奨化やAgent Stackへの改称のように、名前と推奨が変わる前提で依存の版を固定する必要があります。
- **TypeScriptのRequirementAgentをA2A公開したい**：TypeScript版にもA2AServerはありますが、この版で標準登録されているのはReActAgentとToolCallingAgent用の実行処理です。RequirementAgentの公開には追加実装の検討が必要です。
- **利用者の規模を重視する**：2026年10月7日にGitHub APIで取得したスター数は、BeeAI Frameworkが3,427、LangGraphが42,798、Microsoft Agent Frameworkが13,969でした。状態をグラフで細かく制御したいなら[LangGraphでAIエージェントを実装する手順](/tech/details/17447/)、.NETとPythonの両方で使いたいなら[Microsoft Agent Framework 1.0](/tech/details/11675/)も比較対象になります。

主要フレームワークの横並びの比較は[AIエージェントフレームワークの比較](/tech/details/15367/)にまとめています。

## よくある質問

### BeeAIはIBMの製品ですか？

IBM Researchが始めたオープンソースプロジェクトで、現在はLinux Foundation傘下で開発されています。有償製品ではなく、ライセンスはApache-2.0です。IBMのwatsonx.aiやwatsonx Orchestrateとは連携できますが、使わなくても動きます。

### BeeAI Platformはどうなりましたか？

Agent Stackに改称されました。GitHubの `i-am-bee/beeai-platform` は `i-am-bee/agentstack` へ転送され、最新リリースはv0.7.1（2026年3月30日）です。

### BeeAIのACPとA2Aはどういう関係ですか？

IBMのACP（Agent Communication Protocol）は、2025年8月25日にA2Aへ合流しました。ACPのリポジトリはアーカイブされています。新しく連携を作るならA2Aを使います。

### BeeAI FrameworkはどのPythonで動きますか？

0.1.85はPython 3.11以上3.14未満です。0.1.80から上限が3.14未満に変わったので、Python 3.14の環境では3.12か3.13の仮想環境を別に作ります。

### TypeScript版でもRequirementAgentは使えますか？

TypeScript 0.1.31のソースには `RequirementAgent` クラスがあります。ただしAgentsのドキュメントには「現在Pythonのみ対応」という注記が残っており、A2Aサーバーの標準対応もまだありません。TypeScriptで使う場合は、利用する機能がその版に入っているかをソースとリリースノートで確認してください。

## 関連記事

- [AIエージェントフレームワークとは？主要8種の比較・動作コード・選定基準【2026年9月版】](/tech/details/15367/)
- [A2A（Agent2Agent）プロトコルとは？v1.0の仕組み・MCPとの違い・実装手順](/tech/details/6732/)
- [シングルエージェントとマルチエージェントの違い｜使い分けの判断基準とコスト・失敗モード【2026年版】](/tech/details/4261/)
- [LangGraphでAIエージェントを実装する手順：状態管理から承認フローまで](/tech/details/17447/)
- [Microsoft Agent Framework 1.0とは｜Semantic KernelとAutoGenを統合した.NET/Python共通エージェントSDK](/tech/details/11675/)

---

出典: [BeeAIフレームワークとは？IBM発エージェント基盤の使い方とRequirementAgentチュートリアル](<https://www.issoh.co.jp/tech/details/8653/>)（株式会社一創）