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の上限には注意が要ります。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」と調べると、フレームワーク以外のプロジェクトが混ざって出てきます。現在の名前と状態を表にまとめます。

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）プロトコルの解説で扱っています。

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

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

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

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

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が受け取った内容を記録しました。

読み取れることは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つです。そもそも複数エージェントに分けるべきかの判断は、シングルエージェントとマルチエージェントの違いで整理しています。

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タグ）と照らして次の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 を除く）。

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

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

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

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

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

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

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

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エージェントを実装する手順、.NETとPythonの両方で使いたいならMicrosoft Agent Framework 1.0も比較対象になります。

主要フレームワークの横並びの比較はAIエージェントフレームワークの比較にまとめています。

よくある質問

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月版】
• A2A（Agent2Agent）プロトコルとは？v1.0の仕組み・MCPとの違い・実装手順
• シングルエージェントとマルチエージェントの違い｜使い分けの判断基準とコスト・失敗モード【2026年版】
• LangGraphでAIエージェントを実装する手順：状態管理から承認フローまで
• Microsoft Agent Framework 1.0とは｜Semantic KernelとAutoGenを統合した.NET/Python共通エージェントSDK