Building with Qwen-Agent: A Practical Guide

基于 Qwen-Agent^[1] 官方仓库整理，面向本项目的实战指南。
官方文档：https://qwenlm.github.io/Qwen-Agent/en/guide/

目录

1. 1. 框架概览^[2]

2. 2. 安装与配置^[3]

3. 3. 核心架构^[4]

4. 4. LLM 配置详解^[5]

5. 5. Tool（工具）开发^[6]

6. 6. Agent（智能体）开发^[7]

• • 6.1 使用内置 Assistant^[8]

• • 6.2 继承 Agent 基类开发自定义 Agent^[9]

• • 6.3 嵌套 Agent 模式^[10]

• • 6.4 内置 Agent 类型一览^[11]

• • 6.5 Agent 的 run() 方法^[12]

• • 6.6 Router — 多 Agent 路由^[13]

• • 6.7 GroupChat — 多 Agent 群聊^[14]

7. 7. RAG 知识库检索^[15]

8. 8. MCP 协议集成^[16]

9. 9. GUI 界面部署^[17]

10. 10. 消息 Schema^[18]

11. 11. 上下文管理^[19]

12. 12. 本项目映射对照^[20]

13. 13. 常见问题 FAQ^[21]

14. 14. 参考资源^[22]

1. 框架概览

Qwen-Agent 是阿里通义千问团队开源的 Agent 开发框架，现已作为 Qwen Chat^[23] 的后端运行。

核心特性

包结构

qwen_agent/
├── agent.py              # Agent 基类（ABC）
├── agents/               # 内置 Agent 实现
│   ├── assistant.py      # ⭐ Assistant - 通用智能体（本项目使用）
│   ├── fncall_agent.py   # FnCallAgent - 函数调用智能体
│   ├── react_chat.py     # ReActChat - ReAct 推理模式
│   ├── router.py         # Router - 多 Agent 路由选择
│   ├── group_chat.py     # GroupChat - 多智能体群聊
│   ├── user_agent.py     # UserAgent - 人类用户代理
│   ├── memo_assistant.py # MemoAssistant - 带记忆的助手
│   ├── doc_qa/           # 文档问答 Agent
│   └── writing/          # 写作类 Agent
├── llm/                  # LLM 抽象层
│   ├── base.py           # BaseChatModel 基类
│   ├── function_calling.py  # Function Calling 实现
│   └── schema.py         # Message, ContentItem 等数据模型
├── tools/                # 内置工具
│   ├── base.py           # BaseTool 基类 + TOOL_REGISTRY
│   ├── code_interpreter.py  # Docker 沙箱代码执行
│   ├── doc_parser.py     # 文档解析（PDF/Word/PPT/TXT/HTML）
│   ├── retrieval.py      # RAG 检索工具
│   ├── web_search.py     # 网页搜索
│   ├── image_gen.py      # 图片生成
│   ├── storage.py        # 键值存储（MemoAssistant 使用）
│   ├── mcp_manager.py    # MCP 管理器
│   └── ...
├── gui/                  # Gradio 5 WebUI
├── memory/               # 记忆模块
└── utils/                # 工具函数

2. 安装与配置

安装

# 最小安装
pip install qwen-agent

# 完整安装（推荐）
pip install "qwen-agent[rag,code_interpreter,gui,mcp]"

# 使用 uv（本项目方式）
uv add "qwen-agent[code-interpreter,gui,mcp,rag]"

可选依赖说明

模型服务准备

方式一：DashScope 云服务（最简单）

export DASHSCOPE_API_KEY="your-api-key"

方式二：本地 OpenAI 兼容服务（本项目使用）

llm_cfg = {
    'model': 'qwen-mlx-model',           # 模型名称
    'model_type': 'oai',                  # OpenAI 兼容接口
    'model_server': 'http://xxx',  # 本地 MLX 服务
    'api_key': 'EMPTY',
}

注意: 对于 QwQ 和 Qwen3 模型，建议不加--enable-auto-tool-choice 和 --tool-call-parser hermes 参数，因为 Qwen-Agent 会自行解析 vLLM 的工具输出。

3. 核心架构

Qwen-Agent 的架构层次分明：

┌─────────────────────────────────────────┐
│              Application Layer          │
│  (CLI / Gradio WebUI / 自定义集成)       │
├─────────────────────────────────────────┤
│              Agent Layer                │
│  Assistant / FnCallAgent / ReActChat    │
│  Router / GroupChat / UserAgent         │
│  (工作流编排: 规划 → 工具调用 → 回答)     │
├──────────────┬──────────────────────────┤
│   LLM Layer  │      Tool Layer          │
│ BaseChatModel│  BaseTool + Registry     │
│ (Function    │  (code_interpreter,      │
│  Calling)    │   web_search, RAG, MCP)  │
├──────────────┴──────────────────────────┤
│          Schema / Message Layer         │
│  Message, ContentItem, FunctionCall     │
└─────────────────────────────────────────┘

核心抽象

1. 1. Agent（基类）: 接收消息列表 → 返回消息流（Generator）

2. 2. BaseTool（基类）: 定义工具名、描述、参数、call() 方法

3. 3. BaseChatModel（基类）: 统一的 LLM 调用接口，支持 Function Calling

4. LLM 配置详解

配置参数

llm_cfg = {
    # ===== 必填 =====
    'model': 'qwen3-235b-a22b',          # 模型名称

    # ===== 条件必填 =====
    'model_type': 'qwen_dashscope',      # 模型类型（见下表）
    'model_server': 'http://...',         # 仅 OpenAI 兼容接口需要
    'api_key': 'YOUR_KEY',               # 可选，也可用环境变量

    # ===== 可选 =====
    'generate_cfg': {
        'top_p': 0.8,
        'temperature': 0.7,
        'max_input_tokens': 90000,        # 最大输入长度（超出自动截断）
        'use_raw_api': False,             # 是否使用模型服务原生工具调用解析
        'fncall_prompt_type': 'nous',     # 工具调用模板（默认 nous，推荐 Qwen3）
    }
}

model_type 选项

不同部署方式的配置示例

# 1. DashScope 云服务
llm_cfg = {
    'model': 'qwen3-max',
    'model_type': 'qwen_dashscope',
    'generate_cfg': {'enable_thinking': True}
}

# 2. DashScope OpenAI 兼容接口
llm_cfg = {
    'model': 'qwen3-max',
    'model_server': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    'api_key': os.getenv('DASHSCOPE_API_KEY'),
}

# 3. 本地 vLLM/SGLang
llm_cfg = {
    'model': 'Qwen3-8B',
    'model_server': 'http://localhost:8000/v1',
    'api_key': 'EMPTY',
    'generate_cfg': {
        'extra_body': {
            'chat_template_kwargs': {'enable_thinking': True}
        }
    }
}

# 4. 本地 MLX（本项目方式）
llm_cfg = {
    'model': 'qwen-mlx-model',
    'model_type': 'oai',
    'model_server': 'http://localhost:8080/v1',
    'api_key': 'EMPTY',
    'generate_cfg': {
        'temperature': 0.7,
        'top_p': 0.9,
        'max_tokens': 2048,
    }
}

直接调用 LLM（不经过 Agent）

from qwen_agent.llm import get_chat_model

llm = get_chat_model(llm_cfg)
messages = [{'role': 'user', 'content': '你好'}]

# 流式输出
for responses in llm.chat(messages=messages, stream=True):
    print(responses)

# 带 Function Calling
functions = [{
    'name': 'get_weather',
    'description': '获取天气信息',
    'parameters': {
        'type': 'object',
        'properties': {
            'city': {'type': 'string', 'description': '城市名称'}
        },
        'required': ['city']
    }
}]
for responses in llm.chat(messages=messages, functions=functions, stream=True):
    print(responses)

5. Tool（工具）开发

方式一：注册式（推荐，支持按名称引用）

parameters 支持 两种格式：

格式 A：OpenAI JSON Schema 格式（推荐，标准化）

import json
from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('my_tool')
class MyTool(BaseTool):
    # name 会自动设为 'my_tool'（取自装饰器参数）
    description = '这个工具的功能描述，LLM 会根据此描述选择工具'
    parameters = {
        'type': 'object',
        'properties': {
            'param1': {
                'type': 'string',
                'description': '参数1的说明'
            },
            'param2': {
                'type': 'number',
                'description': '参数2的说明'
            }
        },
        'required': ['param1']
    }

    def call(self, params: str, **kwargs) -> str:
        """
        执行工具逻辑

        Args:
            params: LLM 生成的 JSON 字符串参数
            **kwargs: 额外参数（如 files, lang 等）
        Returns:
            str: 工具执行结果（字符串格式，Agent 会将其转为字符串传入 LLM）
        """
        import json5
        args = json5.loads(params)
        result = do_something(args['param1'])
        return json.dumps({'result': result}, ensure_ascii=False)

格式 B：List 简化格式（框架内置工具常用）

@register_tool('my_tool')
class MyTool(BaseTool):
    description = '这个工具的功能描述'
    parameters = [{
        'name': 'param1',
        'type': 'string',
        'description': '参数1的说明',
        'required': True,
    }, {
        'name': 'param2',
        'type': 'number',
        'description': '参数2的说明',
        'required': False,
    }]

    def call(self, params: str, **kwargs) -> str:
        import json5
        args = json5.loads(params)
        return json.dumps({'result': args.get('param1')}, ensure_ascii=False)

如何选择: 格式 A 符合 OpenAI 标准，支持 enum、嵌套对象等高级特性；格式 B 更简洁，适合简单参数。两者在运行时行为一致。

方式二：非注册式（直接传对象）

from qwen_agent.tools.base import BaseTool

class MyTool(BaseTool):
    name = 'my_tool'           # 必须手动指定 name
    description = '工具描述'
    parameters = { ... }

    def call(self, params: str, **kwargs) -> str:
        # 实现逻辑
        return 'result'

传递工具给 Agent 的三种方式

from qwen_agent.agents import Assistant

# 方式一：字符串名称（需先 @register_tool）
tools = ['code_interpreter', 'my_tool']

# 方式二：配置字典
tools = [
    {'name': 'code_interpreter', 'timeout': 30},
    {'name': 'weather', 'api_key': 'xxx'},
]

# 方式三：工具实例对象
tools = [MyTool(), AnotherTool()]

# 混合使用
bot = Assistant(llm=llm_cfg, function_list=[
    'code_interpreter',        # 字符串
    {'name': 'weather'},       # 字典
    MyCustomTool(),            # 对象
])

6. Agent（智能体）开发

6.1 使用内置 Assistant（覆盖大多数场景）

from qwen_agent.agents import Assistant

bot = Assistant(
    llm=llm_cfg,                           # LLM 配置
    system_message='你是一个...',      # 系统提示词
    function_list=['tool1', my_tool],       # 工具列表
    files=['./knowledge.pdf'],              # RAG 文档
    name='xxx',                         # Agent 名称
    description='xxx',                # 描述（多 Agent 场景使用）
)

# 运行 Agent
messages = [{'role': 'user', 'content': '请问xxx？'}]
for response in bot.run(messages=messages):
    print(response)

6.2 继承 Agent 基类开发自定义 Agent

只需实现 _run() 方法：

from typing import Iterator, List
from qwen_agent import Agent
from qwen_agent.llm.schema import Message

class MyCustomAgent(Agent):

    def _run(self, messages: List[Message], lang: str = 'en', **kwargs) -> Iterator[List[Message]]:
        """
        定义 Agent 的工作流

        Args:
            messages: 消息列表（对话历史）
            lang: 语言
        Returns:
            消息列表的迭代器（流式输出）
        """
        # 可以使用 self._call_llm() 调用 LLM
        # 可以使用 self._call_tool() 调用工具
        # 可以嵌套其他 Agent

        yield [Message(role='assistant', content='Hello!')]

6.3 嵌套 Agent 模式（推荐高级用法）

将多个 Agent 组合成一个工作流，每个 Agent 可使用独立的 prompt、工具和 LLM：

from qwen_agent import Agent
from qwen_agent.agents import Assistant

class VisualStorytelling(Agent):
    """看图写文：图像理解 + 写作"""

    def __init__(self, llm=None, function_list=None):
        super().__init__(llm=llm)

        # 嵌套 Agent 1: 图像理解（用 VL 模型）
        self.image_agent = Assistant(llm={'model': 'qwen-vl-max'})

        # 嵌套 Agent 2: 写作（用文本模型 + 知识库）
        self.writing_agent = Assistant(
            llm=self.llm,
            function_list=function_list,
            system_message='你是一个作家...',
            files=['writing_guide.md'],
        )

    def _run(self, messages, lang='zh', **kwargs):
        # Step 1: 图像理解
        new_messages = copy.deepcopy(messages)
        new_messages[-1]['content'].append(
            ContentItem(text='请详细描述这张图片的所有细节'))
        response = []
        for rsp in self.image_agent.run(new_messages):
            yield response + rsp
        response.extend(rsp)
        new_messages.extend(rsp)

        # Step 2: 基于理解结果写作
        new_messages.append(Message('user', '请根据以上图片内容写一篇文章'))
        for rsp in self.writing_agent.run(new_messages, lang=lang, **kwargs):
            yield response + rsp

6.4 内置 Agent 类型一览

核心单 Agent

多 Agent 编排

辅助 Agent

6.5 Agent 的 run() 方法

# 流式运行（默认）
for response in bot.run(messages=messages):
    # response 是 List[Message]
    # 每次迭代产生增量更新
    pass

# 非流式运行
final_response = bot.run_nonstream(messages=messages)

# CLI 聊天循环
messages = []
while True:
    query = input('user: ')
    messages.append({'role': 'user', 'content': query})

    response = []
    for response in bot.run(messages=messages):
        # 实时输出
        pass

    messages.extend(response)  # 将完整响应加入历史

6.6 Router — 多 Agent 路由

Router 继承自 Assistant + MultiAgentHub，通过 LLM 自动选择最合适的 Agent 处理用户请求。当 Router 能直接回答时会自行回复，需要专业能力时自动委托给子 Agent。

from qwen_agent.agents import Assistant, ReActChat, Router

# 创建专业化的子 Agent
bot_vl = Assistant(
    llm={'model': 'qwen-vl-max'},
    name='视觉助手',
    description='可以理解图像内容，分析图片中的细节'
)
bot_tool = ReActChat(
    llm=llm_cfg,
    name='工具助手',
    description='可以使用画图工具和运行代码',
    function_list=['image_gen', 'code_interpreter']
)

# 创建 Router，自动路由到合适的子 Agent
bot = Router(
    llm=llm_cfg,
    agents=[bot_vl, bot_tool],
)

# 使用
messages = [{'role': 'user', 'content': '帮我画一只猫'}]
for response in bot.run(messages=messages):
    pass  # Router 会自动选择 "工具助手" 处理

工作原理：

1. 1. Router 将所有子 Agent 的名称和描述拼接到系统提示词中

2. 2. 对每条用户消息，先让 LLM 判断是否需要委托

3. 3. 如果需要委托，解析 Call: <agent_name> 选择对应 Agent 执行

4. 4. 如果能直接回答，Router 自行回复

6.7 GroupChat — 多 Agent 群聊

GroupChat 管理多个 Agent 的发言顺序和对话上下文，支持四种发言选择模式。

from qwen_agent.agents import Assistant, GroupChat, UserAgent

# 方式一：直接传入 Agent 对象
agents = [
    Assistant(llm=llm_cfg, name='专家A', description='技术专家'),
    Assistant(llm=llm_cfg, name='专家B', description='产品专家'),
    UserAgent(name='用户', description='真实用户'),  # 代表人类用户
]

group = GroupChat(
    agents=agents,
    agent_selection_method='auto',  # 'auto' | 'round_robin' | 'random' | 'manual'
    llm=llm_cfg,  # auto 模式必须提供 LLM
)

# 方式二：从配置字典初始化（自动创建 Agent）
config = {
    'background': '一个技术讨论群',
    'agents': [{
        'name': '产品经理',
        'description': '关注用户体验',
        'instructions': '你是产品经理，从用户角度思考问题',
        'knowledge_files': ['product_guide.md'],
        'selected_tools': ['web_search'],
    }, {
        'name': '开发者',
        'description': '技术实现专家',
        'instructions': '你是资深开发者，关注技术可行性',
    }, {
        'name': '用户小明',
        'description': '普通用户',
        'is_human': True,  # 标记为真人，自动创建 UserAgent
    }]
}

group = GroupChat(agents=config, llm=llm_cfg)

# 运行（支持 max_round 控制最大轮次）
for response in group.run(
    messages=[{'role': 'user', 'content': '我们该不该用微服务架构？'}],
    max_round=5,
):
    pass

agent_selection_method 说明：

注意：GroupChat 中每个 Agent 必须设置 name，消息通过 @名字 触发指定 Agent。当某个 Agent 是 UserAgent 时，会返回 PENDING_USER_INPUT 中断群聊，等待用户输入。

7. RAG 知识库检索

自动启用

Assistant 的 files 参数自动触发 RAG：

bot = Assistant(
    llm=llm_cfg,
    files=['./doc.pdf', './knowledge.md', './data.txt'],
    # 也可以传 URL
    # files=['https://example.com/paper.pdf'],
)

支持的文件格式

.pdf, .docx, .pptx, .txt, .csv, .tsv, .xlsx, .xls, .html

工作原理

用户查询 → LLM 生成关键词 → BM25 匹配文档片段 → 拼接到 Prompt → LLM 回答
                                    ↑
                              文档分块（默认 500 tokens）

1. 1. 文档解析: 文件切分为 500 token 的文本块

2. 2. 关键词检索: 使用 BM25 算法进行稀疏关键词匹配

3. 3. 可选关键词生成: LLM 自动从查询中提取多语言关键词

4. 4. 结果截断: 检索结果限制在 max_ref_token（默认 20000 tokens）

高级 RAG 配置

rag_cfg = {
    'max_ref_token': 4000,              # 最大检索引用 token 数（默认 20000）
    'parser_page_size': 500,            # 文档分块大小（token）
    'rag_keygen_strategy': 'SplitQueryThenGenKeyword',  # 关键词生成策略
    'rag_searchers': ['keyword_search', 'front_page_search'],  # 检索方式
}

bot = Assistant(
    llm=llm_cfg,
    files=['./doc.pdf'],
    rag_cfg=rag_cfg,  # 传入高级配置
)

可用的关键词生成策略：

可用的检索方式：

本项目的 RAG 实践

# agents/agriculture_agent.py 中的自动知识库发现
from config.settings import KNOWLEDGE_BASE_DIR

files = None
if KNOWLEDGE_BASE_DIR.exists():
    knowledge_files = []
    knowledge_files.extend(list(KNOWLEDGE_BASE_DIR.glob('*.md')))
    knowledge_files.extend(list(KNOWLEDGE_BASE_DIR.glob('*.pdf')))
    knowledge_files.extend(list(KNOWLEDGE_BASE_DIR.glob('*.txt')))
    if knowledge_files:
        files = [str(f) for f in knowledge_files]

bot = Assistant(llm=llm_cfg, files=files, ...)

8. MCP 协议集成

配置格式

{
    "mcpServers": {
        "memory": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-memory"]
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
        },
        "sqlite": {
            "command": "uvx",
            "args": ["mcp-server-sqlite", "--db-path", "test.db"]
        }
    }
}

在 Agent 中使用 MCP

from qwen_agent.agents import Assistant

# 方式一：直接传 MCP 配置字典
mcp_config = {
    "mcpServers": {
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
        }
    }
}

bot = Assistant(
    llm=llm_cfg,
    function_list=[mcp_config],  # MCP 配置放在 function_list 中
)

# 方式二：从 JSON 文件加载
import json
with open('mcp_config.json') as f:
    mcp_config = json.load(f)
bot = Assistant(llm=llm_cfg, function_list=[mcp_config])

系统依赖

# macOS
brew install node uv git sqlite3

# 验证
node --version   # Node.js LTS
uv --version     # >= 0.4.18

安全提醒: MCP 服务未沙箱隔离，仅用于本地开发环境，不要在生产环境使用。

9. GUI 界面部署

一行代码启动 Web UI

from qwen_agent.gui import WebUI

# 基础用法
WebUI(bot).run()

# 带建议提示
WebUI(bot, chatbot_config={
    'prompt.suggestions': [
        '今天天气怎么样？',
        '帮我分析一下产量数据',
    ]
}).run()

10. 消息 Schema

核心数据模型

from qwen_agent.llm.schema import Message, ContentItem, FunctionCall

# 纯文本消息
msg = Message(role='user', content='你好')

# 多模态消息（文本 + 图片）
msg = Message(role='user', content=[
    ContentItem(text='描述这张图片'),
    ContentItem(image='https://example.com/cat.jpg'),
])

# 带文件的消息（触发 RAG）
msg = Message(role='user', content=[
    ContentItem(text='请回答关于这个文档的问题'),
    ContentItem(file='./doc.pdf'),
])

# Function Call 消息
msg = Message(
    role='assistant',
    content='',
    function_call=FunctionCall(
        name='get_weather',
        arguments='{"city": "北京"}'
    )
)

# Function 返回消息
msg = Message(
    role='function',
    name='get_weather',
    content='{"temperature": 25, "unit": "Celsius"}'
)

# 带推理链的消息（Qwen3/QwQ）
msg = Message(
    role='assistant',
    content='答案是 25 度',
    reasoning_content='首先我需要查找北京的天气...'
)

ContentItem 支持的类型

注意: 每个 ContentItem 只能设置一个字段（text / image / file / audio / video 互斥），设置多个字段会抛出 ValueError。如需同时发送文本和图片，应使用多个 ContentItem 组成列表：

# 正确：多个 ContentItem
content=[
    ContentItem(text='描述这张图片'),
    ContentItem(image='https://example.com/cat.jpg'),
]

# 错误：一个 ContentItem 设多个字段 → ValueError
ContentItem(text='描述', image='url')  # ❌

角色类型

system, user, assistant, function

11. 上下文管理

Qwen-Agent 自动管理上下文长度，确保不超出 max_input_tokens（默认 90000）。

截断策略（S1→S5 逐级压缩）

S1: 移除最早的完整对话轮次
 ↓ 仍然超长？
S2: 折叠（压缩）最早的工具返回结果
 ↓ 仍然超长？
S3: 移除最早的工具调用步骤（保留用户 Query 和最终 Response）
 ↓ 仍然超长？
S4: 折叠最近步骤的工具返回
 ↓ 仍然超长？
S5: 截断用户 Query 或最终 Response

原则: 优先丢弃旧记忆和环境信息，保留最近的关键信息。

# 配置最大输入长度
llm_cfg = {
    'model': 'qwen3-max',
    'generate_cfg': {
        'max_input_tokens': 58000,  # 根据模型调整
    }
}

12. 本项目映射对照

注意: 本节内容为项目特定实现，不属于 Qwen-Agent 框架本身。以下映射展示了如何在具体项目中应用框架的各项能力。

项目如何使用 Qwen-Agent

本项目的 LLM 配置

# config/settings.py
LLM_CONFIG = {
    'model': 'qwen-mlx-model',
    'model_type': 'oai',
    'model_server': 'http://localhost:8080/v1',
    'api_key': 'EMPTY',
    'generate_cfg': {
        'temperature': 0.7,
        'top_p': 0.9,
        'max_tokens': 2048,
    }
}

本项目的 System Prompt 设计

System Prompt 在 config/settings.py 的 SYSTEM_INSTRUCTION 中定义，用于：

• • 指导 LLM 选择正确的工具

• • 定义各工具的参数要求

• • 包含领域知识（如水稻品种参数）

• • 设定输出格式

13. 常见问题 FAQ

Q: 如何使用代码解释器？

确保已安装 Docker，然后在工具列表中添加 'code_interpreter'：

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

Q: 如何在本地使用 Qwen3 模型？

# 使用 vLLM 启动
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen3-8B \
    --port 8000

# 然后在代码中配置
llm_cfg = {
    'model': 'Qwen/Qwen3-8B',
    'model_server': 'http://localhost:8000/v1',
    'api_key': 'EMPTY',
}

Q: Qwen-Agent 如何处理不支持 Function Calling 的模型？

Qwen-Agent 内置了 BaseFnCallModel 类，通过包装 ReAct 风格的 Prompt 模拟工具调用。当模型服务不支持原生工具调用时，框架会自动使用内置解析器。

Q: 如何实现多轮对话？

messages = []
while True:
    query = input('user: ')
    messages.append({'role': 'user', 'content': query})
    response = []
    for response in bot.run(messages=messages):
        pass  # 流式处理
    messages.extend(response)  # 关键：将响应加入历史

Q: 如何创建多 Agent 应用？

方式一：Router（推荐，按需路由）

from qwen_agent.agents import Assistant, ReActChat, Router

agent_a = Assistant(llm=llm_cfg, name='专家A', description='擅长数据分析')
agent_b = ReActChat(llm=llm_cfg, name='专家B', description='擅长代码编写',
                     function_list=['code_interpreter'])

router = Router(llm=llm_cfg, agents=[agent_a, agent_b])
for response in router.run(messages=[{'role': 'user', 'content': '帮我写一段排序代码'}]):
    pass  # Router 自动选择 "专家B" 处理

方式二：GroupChat（多轮群聊）

from qwen_agent.agents import Assistant, GroupChat

agent1 = Assistant(llm=llm_cfg, name='专家A', description='xxx专家')
agent2 = Assistant(llm=llm_cfg, name='专家B', description='xx专家')

group = GroupChat(agents=[agent1, agent2], llm=llm_cfg)
for response in group.run(messages=[{'role': 'user', 'content': '...'}]):
    print(response)

14. 参考资源

引用链接

[1] Qwen-Agent: https://github.com/QwenLM/Qwen-Agent
[2] 框架概览: #1-框架概览
[3] 安装与配置: #2-安装与配置
[4] 核心架构: #3-核心架构
[5] LLM 配置详解: #4-llm-配置详解
[6] Tool（工具）开发: #5-tool工具开发
[7] Agent（智能体）开发: #6-agent智能体开发
[8] 6.1 使用内置 Assistant: #61-使用内置-assistant覆盖大多数场景
[9] 6.2 继承 Agent 基类开发自定义 Agent: #62-继承-agent-基类开发自定义-agent
[10] 6.3 嵌套 Agent 模式: #63-嵌套-agent-模式推荐高级用法
[11] 6.4 内置 Agent 类型一览: #64-内置-agent-类型一览
[12] 6.5 Agent 的 run() 方法: #65-agent-的-run-方法
[13] 6.6 Router — 多 Agent 路由: #66-router--多-agent-路由
[14] 6.7 GroupChat — 多 Agent 群聊: #67-groupchat--多-agent-群聊
[15] RAG 知识库检索: #7-rag-知识库检索
[16] MCP 协议集成: #8-mcp-协议集成
[17] GUI 界面部署: #9-gui-界面部署
[18] 消息 Schema: #10-消息-schema
[19] 上下文管理: #11-上下文管理
[20] 本项目映射对照: #12-本项目映射对照
[21] 常见问题 FAQ: #13-常见问题-faq
[22] 参考资源: #14-参考资源
[23] Qwen Chat: https://chat.qwen.ai/