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

アーキテクチャ — 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つの方法で提供できます。

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

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 層 — 数行でエージェントを構築

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

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 コンテナによるサンドボックス実行

1

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

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

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

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

1

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

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

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

1
2
3
4
5

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

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

1

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

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

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

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

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

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

Quick Start — 最小構成で動かす

インストール

1
2
3
4
5

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

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

最小エージェント

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

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 で起動

1
2

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

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

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

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

3つの必要能力

評価次元

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

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

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

LangChain との違い

CrewAI との違い

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

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

基本比較

アーキテクチャの違い

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

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-Agent で OpenClaw のような自律実行エージェントは作れるか

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

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

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

 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

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='あなたは自律型コーディングエージェントです。ユーザーの指示に従い、ファイルの読み書きとコマンド実行でタスクを完了してください。'
)

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

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

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

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）

1
2
3
4
5
6
7
8
9

# 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