Qwen-Agent 公式エージェントフレームワーク完全ガイド — モデル開発チームが作った「全部入り」の設計思想

qwen-agent-official-framework-function-calling-mcp-rag.md

Qwen-Agent 公式エージェントフレームワーク完全ガイド — モデル開発チームが作った「全部入り」の設計思想

@abxxai（Abdul Shakoor）のポストが、Qwen チームが公式リリースしたエージェントフレームワーク「Qwen-Agent」を紹介し、10万ビュー超・2,900ブックマーク・2,200いいねと極めて高い反響を集めています。

BREAKING: The Qwen team just shipped their official agent framework and it has everything. No stitching together third-party libraries. No fighting abstractions.

「サードパーティのライブラリをつなぎ合わせる必要がない」「抽象化と戦わなくていい」という評価は、既存のエージェントフレームワーク（LangChain、CrewAI 等）が抱える複雑さへのアンチテーゼです。

Qwen-Agent とは何か

Qwen-Agent は、Alibaba Cloud の Qwen チームが開発したオープンソースのエージェントフレームワークです。Qwen 3.0 以上のモデルをベースに、Function Calling・MCP・Code Interpreter・RAG・Chrome 拡張を統合した「全部入り」のフレームワークとして設計されています。

最大の特徴: モデルとフレームワークの共進化

LangChain や CrewAI がモデルに依存しない汎用フレームワークであるのに対し、Qwen-Agent は Qwen モデルと一体的に開発されています。

観点	Qwen-Agent	LangChain / CrewAI
開発元	Qwen モデル開発チーム	サードパーティ
モデルとの関係	共進化（同時に開発・最適化）	モデル非依存
ツール呼び出し	ネイティブ統合（テンプレート・パーサー内蔵）	アダプタ経由
抽象化の層	薄い（モデルに直接最適化）	厚い（汎用性のための間接層）
対応モデル	Qwen 系が最適、他モデルも利用可	幅広いモデルに対応

Qwen チームは「モデルの開発当初から、ツール使用と深い推論を含む強力なエージェント能力の実現が戦略の柱だった」と述べています。フレームワークはモデルの能力を最大限に引き出すために設計されており、汎用フレームワークでは到達できない最適化が実現されています。

アーキテクチャ — 3層の構成要素

Qwen-Agent のアーキテクチャは、3つの層で構成されています。

┌─────────────────────────────────────────────┐
│              Agent 層（高レベル）              │
│  Assistant / FnCallAgent / ReActChat        │
│  マルチステップの計画と実行を制御              │
├─────────────────────────────────────────────┤
│         LLM 層（モデルサービス）               │
│  BaseChatModel を継承                        │
│  Function Calling テンプレート・パーサー内蔵  │
│  DashScope / vLLM / Ollama 対応             │
├─────────────────────────────────────────────┤
│         Tool 層（ツール群）                    │
│  BaseTool を継承                             │
│  @register_tool デコレータで自動登録          │
│  MCP / Code Interpreter / RAG 等            │
└─────────────────────────────────────────────┘

LLM 層 — モデルサービスの柔軟な選択

モデルサービスは3つの方法で提供できます。

方式	説明	用途
DashScope	Alibaba Cloud の API サービス	最も手軽。DASHSCOPE_API_KEY を設定するだけ
vLLM / SGLang	高スループット GPU デプロイ	自社サーバーでの本番運用
Ollama	ローカル PC での実行	開発・実験・プライバシー重視

Tool 層 — @register_tool による宣言的なツール定義

ツールの定義は @register_tool デコレータを使った宣言的な方式です。

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('weather_lookup')
class WeatherLookup(BaseTool):
    description = '指定された都市の現在の天気を取得します'
    parameters = {
        'type': 'object',
        'properties': {
            'city': {
                'type': 'string',
                'description': '天気を調べたい都市名'
            }
        },
        'required': ['city'],
    }

    def call(self, params: str, **kwargs) -> str:
        city = json5.loads(params)['city']
        # 天気 API を呼び出して結果を返す
        return json5.dumps({'city': city, 'weather': '晴れ', 'temp': '22°C'})

LangChain の @tool デコレータと似ていますが、Qwen-Agent はツール呼び出しのテンプレートとパーサーをフレームワーク内に内蔵しているため、「ツールを定義すれば、あとはフレームワークが最適な形でモデルに渡してくれる」仕組みです。

Agent 層 — 数行でエージェントを構築

from qwen_agent.agents import Assistant

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    'generate_cfg': {'top_p': 0.8}
}

bot = Assistant(
    llm=llm_cfg,
    system_message='あなたは親切なアシスタントです。',
    function_list=['weather_lookup', 'code_interpreter'],
    files=['./knowledge_base.pdf']
)

Assistant クラスに LLM 設定・ツールリスト・参照ファイルを渡すだけで、Function Calling・RAG・Code Interpreter が統合されたエージェントが完成します。

5つの主要機能を深掘り

1. Function Calling — ネイティブ統合の強み

Qwen-Agent の Function Calling は、モデルのツール呼び出し能力と直接統合されています。

機能	説明
並列呼び出し	複数ツールの同時実行をサポート
マルチステップ	ツールの結果を次のツール呼び出しに活用
マルチターン	会話の文脈を保持した連続的なツール使用
テンプレート内蔵	ツール呼び出しのフォーマットをフレームワークが管理
パーサー内蔵	モデル出力の解析をフレームワークが処理

ツール呼び出しパーサーは2種類から選択できます。

• モデルサーバーのネイティブパーサー: Qwen3-Coder 使用時は --enable-auto-tool-choice --tool-call-parser qwen3_coder を追加
• Qwen-Agent 組み込みパーサー: "hermes" 形式がデフォルト。QwQ と Qwen3 シリーズをサポート

2. Code Interpreter — Docker コンテナによるサンドボックス実行

pip install -U "qwen-agent[code_interpreter]"

Code Interpreter は、Docker コンテナベースのサンドボックスでコードを実行します。

項目	内容
実行環境	Docker コンテナ内の隔離環境
ファイルシステム	コンテナ内に隔離（ホストへのアクセスなし）
対応言語	Python
用途	数値計算、データ可視化、ファイル処理
制約	ローカルテスト用（本番環境では追加の安全対策が必要）

エージェントがシナリオに応じてコードを自律的に生成・実行し、結果を返します。データ分析やグラフ作成のタスクで特に有効です。

3. RAG — 100万トークン対応の高速検索拡張生成

pip install -U "qwen-agent[rag]"

Qwen-Agent の RAG は、超長文ドキュメントの QA に最適化されています。

特徴	説明
対応コンテキスト	最大100万トークン
ベンチマーク性能	ネイティブ長コンテキストモデルを上回る精度
Needle-in-Haystack	100万トークンの単一針テストで完璧なスコア
ファイル形式	PDF、Word、PowerPoint に対応

files パラメータにドキュメントを渡すだけで、エージェントが自動的に RAG パイプラインを構築します。

bot = Assistant(
    llm=llm_cfg,
    function_list=['code_interpreter'],
    files=['./contract.pdf', './specification.docx']
)

4. MCP（Model Context Protocol）サポート

pip install -U "qwen-agent[mcp]"

MCP サーバーとの連携により、外部ツールやデータソースを標準化されたプロトコルで統合できます。

ツールの定義方法は3つあります。

方法	説明
MCP 設定ファイル	MCP サーバーの設定を JSON で記述
Qwen-Agent 統合ツール	フレームワーク内蔵のツールを使用
カスタムツール	@register_tool で独自ツールを定義

5. BrowserQwen — Chrome 拡張によるブラウザエージェント

Chrome 拡張「BrowserQwen」は、ブラウザ上で直接 AI エージェントを動作させます。

機能	説明
ページ理解	閲覧中の Web ページや PDF の内容を理解・要約
閲覧記録	Web ページや PDF/Word/PowerPoint を記録
複数ページ統合	複数ページの内容を横断的に理解
コード実行	Code Interpreter と連携した数値計算・可視化
自動執筆	閲覧内容をもとにした文章の自動生成

ローカルマシンにバックエンドサービス（DB + API）をデプロイし、Chrome 拡張がそのサービスと通信する構成です。

Quick Start — 最小構成で動かす

インストール

# 基本インストール
pip install -U qwen-agent

# 全機能インストール
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"

最小エージェント

from qwen_agent.agents import Assistant

# DashScope API を使用する場合
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
}

# Ollama でローカル実行する場合
# llm_cfg = {
#     'model': 'qwen3:8b',
#     'model_server': 'http://localhost:11434/v1',
#     'api_key': 'EMPTY',
# }

bot = Assistant(llm=llm_cfg, function_list=['code_interpreter'])

messages = [{'role': 'user', 'content': '1から100までの素数を列挙して'}]
for response in bot.run(messages=messages):
    print(response)

GUI で起動

from qwen_agent.gui import WebUI
WebUI(bot).run()

これだけで、Gradio ベースの Web UI チャットインターフェースが起動します。

DeepPlanning — エージェント評価ベンチマーク

Qwen チームは Qwen-Agent と同時に、エージェントの計画能力を評価するベンチマーク「DeepPlanning」もオープンソースで公開しています。

3つの必要能力

能力	説明
Proactive Information Acquisition	環境から必要な情報を能動的に検索・取得
Local Constrained Reasoning	サブタスク内の明示的・暗黙的ロジックの処理
Global Constrained Optimization	全体制約下での解の最適化

評価次元

旅行計画とショッピング計画のタスクで、8次元・21チェックポイントで評価します。

次元	内容
ルートの一貫性	移動経路が論理的に連続しているか
サンドボックス準拠	制約条件を守っているか
旅程の構造	計画が適切に構造化されているか
時間の実現可能性	時間的に実行可能か
営業時間の準拠	施設の営業時間を考慮しているか
所要時間の合理性	各活動の時間配分が現実的か
コスト計算の精度	費用の計算が正確か
活動の多様性	活動が多様で偏りがないか

注目すべきは、GPT-5.2、Claude 4.5、Gemini、Qwen3 を含む最先端モデルでさえ、このベンチマークで苦戦しているという点です。長期的な計画能力は、現在の LLM にとって依然として困難な課題です。

既存フレームワークとの比較

LangChain との違い

観点	Qwen-Agent	LangChain
PyPI ダウンロード	成長中	4,700万+
統合数	Qwen 系に最適化	600+
設計思想	モデルファースト	フレームワークファースト
学習コスト	低い（薄い抽象化）	高い（厚い抽象化層）
ツール呼び出し	テンプレート・パーサー内蔵	アダプタ経由
エコシステム	限定的	LangSmith, LangGraph 等

CrewAI との違い

観点	Qwen-Agent	CrewAI
対象	単一エージェントが中心	マルチエージェントチーム
設計モデル	Agent + Tool + LLM	Role + Goal + Tool
得意領域	ツール呼び出しの精度	エージェント間の協調
ベース	独立フレームワーク	LangChain 上に構築

OpenHands・Claude Code との比較 — 3つの設計思想

Qwen-Agent、OpenHands、Claude Code は設計思想が根本的に異なるため、単純な優劣比較より「何を重視するか」で選ぶべきです。

基本比較

観点	Qwen-Agent	OpenHands	Claude Code
種類	エージェントフレームワーク（SDK）	AI コーディングプラットフォーム	CLI コーディングエージェント
主な用途	LLM アプリ開発の基盤	ソフトウェア開発の自動化	ターミナルでのコード支援
開発元	Alibaba Cloud / Qwen チーム	オープンソースコミュニティ	Anthropic
ライセンス	Apache 2.0（無料）	MIT（無料）	プロプライエタリ（従量課金）
対応モデル	Qwen 系に最適化、他モデルも可	75+ プロバイダ（モデル非依存）	Claude 専用

アーキテクチャの違い

観点	Qwen-Agent	OpenHands	Claude Code
実行環境	Python プロセス / Gradio UI	Docker コンテナ（隔離）	ターミナル（サンドボックス）
ツール呼び出し	ネイティブ統合（パーサー内蔵）	Event Stream 抽象化	Tool Use API
マルチエージェント	限定的（単一エージェント中心）	ハンドオフ・チーム協調対応	Subagent / Teams
コード実行	Docker サンドボックス	Docker / Kubernetes	Bash ツール
MCP サポート	あり	なし（独自統合）	あり
RAG	100万トークン対応の内蔵RAG	なし（外部連携）	ファイル読み取りベース
ブラウザ操作	Chrome 拡張（BrowserQwen）	WebArena 対応	なし

ベンチマーク性能（SWE-bench）

構成	スコア
Claude Sonnet 4 + Claude Code	70.4%
Qwen3-Coder + OpenHands（500ターン）	69.6%
Qwen3-Coder（標準）	67.0%

Qwen3-Coder はオープンウェイトモデルとしてトップクラスの性能を持ち、OpenHands と組み合わせることで Claude Code に迫るスコアを達成しています。

3つのツールの本質的な違い

• Qwen-Agent は「エージェントを作るための SDK」です。カスタムツールの定義、RAG パイプラインの構築、BrowserQwen によるブラウザ自動化など、独自の AI アプリケーションを開発するための基盤を提供します
• OpenHands は「コードを書かせるプラットフォーム」です。Docker コンテナ内でエージェントが自律的にコードを書き、テストし、デバッグします。GitHub Issue の自動修正や SWE-bench タスクに特化しています
• Claude Code は「最高品質のコーディング相棒」です。Claude モデルの推論能力を最大限に活かし、開発者がターミナルで対話的にコーディングを進める体験を提供します

これらは競合関係というより補完関係にあります。例えば、Qwen-Agent で構築したエージェントを OpenHands のプラットフォーム上で動かし、Claude Code で設計レビューを行うといった組み合わせも可能です。

選択の指針

ユースケース	推奨
Qwen モデルで独自エージェントアプリを構築	Qwen-Agent
モデル非依存でコーディング自動化	OpenHands
最高品質のコード支援を今すぐ使いたい	Claude Code
完全ローカル・完全無料で運用	Qwen-Agent + Ollama
GitHub Issue の自動修正	OpenHands
ブラウザ上でエージェントを動かしたい	Qwen-Agent（BrowserQwen）
複数モデルを切り替えて使いたい	LangChain
マルチエージェントのチーム構成が必要	CrewAI
本番環境での監視・テストが必要	LangChain（LangSmith）

Qwen-Agent で OpenClaw のような自律実行エージェントは作れるか

Qwen-Agent が「エージェントを作るための SDK」であるなら、OpenClaw や Claude Code のような自律型コーディングエージェントを構築することは可能なのでしょうか。結論から言えば、可能です。そして Qwen チーム自身がそれを実証しています。

アプローチ1: Qwen-Agent SDK で自作する

BaseTool を継承して、ファイル編集・Bash 実行・Git 操作などのツールを定義すれば、自律実行エージェントの骨格を構築できます。

from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.agents import Assistant
import subprocess, json5

@register_tool('file_edit')
class FileEdit(BaseTool):
    description = 'ファイルの内容を編集する'
    parameters = {
        'type': 'object',
        'properties': {
            'path': {'type': 'string', 'description': 'ファイルパス'},
            'content': {'type': 'string', 'description': '書き込む内容'}
        },
        'required': ['path', 'content'],
    }
    def call(self, params: str, **kwargs) -> str:
        p = json5.loads(params)
        with open(p['path'], 'w') as f:
            f.write(p['content'])
        return json5.dumps({'status': 'ok', 'path': p['path']})

@register_tool('bash')
class BashExec(BaseTool):
    description = 'シェルコマンドを実行する'
    parameters = {
        'type': 'object',
        'properties': {
            'command': {'type': 'string', 'description': '実行するコマンド'}
        },
        'required': ['command'],
    }
    def call(self, params: str, **kwargs) -> str:
        cmd = json5.loads(params)['command']
        result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
        return json5.dumps({'stdout': result.stdout, 'stderr': result.stderr})

bot = Assistant(
    llm={'model': 'qwen3:8b', 'model_server': 'http://localhost:11434/v1', 'api_key': 'EMPTY'},
    function_list=['file_edit', 'bash', 'code_interpreter'],
    system_message='あなたは自律型コーディングエージェントです。ユーザーの指示に従い、ファイルの読み書きとコマンド実行でタスクを完了してください。'
)

ただし、本番品質にするには以下の安全機構を全て自前で実装する必要があります。

安全機構	OpenClaw / Claude Code での実装	自作時の課題
権限制御	ツール実行前にユーザー承認を要求	承認フローの設計・実装
サンドボックス	コンテナ隔離 / カーネルレベル制限	Docker 連携の構築
ファイル差分管理	変更箇所のみを表示・確認	diff 生成・表示の実装
コンテキスト管理	自動圧縮・コンパクション	長期会話のメモリ管理
エラー回復	リトライ・代替アプローチの自動選択	フォールバック戦略の設計

アプローチ2: Qwen Code を使う（既に作られている）

実は Qwen チームが既に答えを出しています。Qwen Code は、Qwen-Agent フレームワーク上に構築された CLI コーディングエージェントで、まさに「Qwen 版 OpenClaw / Claude Code」です。

観点	OpenClaw	Qwen Code	Claude Code
ベースモデル	任意（Claude, GPT 等）	Qwen3-Coder	Claude
フレームワーク	独自実装	Qwen-Agent	独自実装
ターミナル操作	あり	あり	あり
ファイル編集	あり	あり	あり
IDE 統合	VS Code 等	VS Code, Zed, JetBrains	VS Code, JetBrains
無料枠	モデル API 費用が必要	OAuth で1,000リクエスト/日無料	従量課金
ライセンス	Apache 2.0	Apache 2.0	プロプライエタリ

Qwen-Agent と Qwen Code の関係

Qwen-Agent（SDK）
  ├── BrowserQwen（ブラウザエージェント）
  ├── Code Interpreter（コード実行エージェント）
  ├── Custom Assistant（カスタムエージェント）
  └── Qwen Code（CLI コーディングエージェント）← OpenClaw / Claude Code 相当

つまり、**Qwen-Agent は「OpenClaw を作れる SDK」**であり、**Qwen Code は「Qwen-Agent で実際に作られた OpenClaw 相当品」**です。自作する必要がある場合は Qwen-Agent SDK を使い、既製品で十分なら Qwen Code を使うのが現実的な選択です。

日本語環境での利用

Qwen3 シリーズは日本語に強いモデルです。Qwen-Agent と組み合わせることで、日本語環境でのエージェント構築に適しています。

ローカル実行（Ollama）

# Qwen3 8B をダウンロード
ollama pull qwen3:8b

# Qwen-Agent から利用
llm_cfg = {
    'model': 'qwen3:8b',
    'model_server': 'http://localhost:11434/v1',
    'api_key': 'EMPTY',
}

14B 以上のモデルが推奨されますが、8B でも基本的なツール呼び出しと日本語応答は動作します。

まとめ

• Qwen チームが公式エージェントフレームワークをリリース: Function Calling・MCP・Code Interpreter・RAG・Chrome 拡張を統合した「全部入り」設計
• モデルとフレームワークの共進化が最大の強み: ツール呼び出しのテンプレートとパーサーをフレームワーク内に内蔵し、LangChain のような汎用フレームワークでは到達できない最適化を実現
• 3層アーキテクチャ（Agent/LLM/Tool）: @register_tool デコレータによる宣言的なツール定義と、Assistant クラスの数行でエージェント構築が完了
• RAG は100万トークン対応: ネイティブ長コンテキストモデルを上回る精度を達成し、Needle-in-Haystack テストで完璧なスコア
• DeepPlanning ベンチマーク同時公開: 8次元21チェックポイントでエージェントの計画能力を評価。GPT-5.2 や Claude 4.5 でさえ苦戦する難易度
• DashScope / vLLM / Ollama の3方式: クラウド API からローカル PC まで柔軟にデプロイ可能。完全オープンソース・完全無料
• OpenHands・Claude Code とは補完関係: Qwen-Agent は「エージェントを作る SDK」、OpenHands は「コードを書かせるプラットフォーム」、Claude Code は「最高品質のコーディング相棒」。SWE-bench では Qwen3-Coder + OpenHands が69.6%で Claude Code の70.4%に迫る
• Qwen-Agent で OpenClaw 相当品は構築可能: SDK としてファイル編集・Bash 実行ツールを定義すれば自律エージェントの骨格は作れる。ただし安全機構の自前実装が課題。既製品としては Qwen Code が Qwen-Agent 上に構築済み
• 選択の指針: Qwen モデルで最高性能を引き出すなら Qwen-Agent、モデル非依存なら LangChain、マルチエージェントなら CrewAI

参考

• @abxxai のポスト
• Qwen-Agent GitHub リポジトリ
• Qwen-Agent 公式ドキュメント
• Qwen-Agent QuickStart ガイド
• Qwen-Agent: A Guide With Demo Project - DataCamp
• What is Qwen-Agent framework? Inside the Qwen family - Hugging Face Blog
• DeepPlanning: Benchmarking Long-Horizon Agentic Planning - arXiv
• Qwen-Agent Ollama 統合ドキュメント
• BrowserQwen Chrome 拡張ガイド
• AI Agent Frameworks Compared 2026 - Arsum
• OpenHands GitHub リポジトリ
• Claude Code vs Qwen3-Coder - AI Agents Comparison
• Top 5 CLI Coding Agents 2026 - Pinggy
• OpenHands + AMD: Local AI for Developers
• Qwen Code GitHub リポジトリ
• Qwen Code 公式ドキュメント
• Qwen3-Coder: Agentic Coding in the World - Qwen Blog