核心定位与设计理念

Qwen-Agent 的核心定位是 简化 Agent 应用开发流程，降低大模型应用落地的技术门槛。框架设计遵循以下核心理念：

统一抽象与模块化设计

框架采用模块化架构，将大语言模型调用、工具管理、对话控制、Agent 协作等核心功能解耦为独立模块。开发者可以根据需求灵活组合这些模块，快速构建定制化的 Agent 解决方案。资料来源：qwen_agent/__init__.py:1-20

原生支持函数调用（Function Calling）

Qwen-Agent 原生支持 Qwen 模型的函数调用能力，支持 并行函数调用（Parallel Function Calls）。这使得 Agent 能够精准理解用户意图并调用相应的外部工具，实现与大语言模型的无缝交互。资料来源：README.md

面向生产环境的设计

框架不仅支持在 Gradio 中进行交互式测试和调试，还支持通过 FastAPI 等 Web 框架将 Agent 发布为 API 服务，便于在实际业务系统中集成使用。这是社区中反馈较多的需求之一（Issue #609）。资料来源：examples/

系统架构

Qwen-Agent 的系统架构可以分为以下几个核心层次：

graph TD
    subgraph "应用层 (Application Layer)"
        A[Agent 应用] --> B[FnCallAgent]
        A --> C[ReActChat]
        A --> D[Assistant]
    end
    
    subgraph "核心层 (Core Layer)"
        B --> E[LLM 基类]
        C --> E
        D --> E
        E --> F[工具系统 Tools]
        E --> G[记忆系统 Memory]
    end
    
    subgraph "模型层 (Model Layer)"
        H[Qwen-DashScope]
        I[OpenAI 兼容 API]
        J[本地 vLLM/Ollama]
        E --> H
        E --> I
        E --> J
    end
    
    subgraph "工具层 (Tools Layer)"
        F --> K[内置工具]
        F --> L[ MCP 工具]
        F --> M[自定义工具]
    end

核心模块说明

Agent 类型

Qwen-Agent 提供了多种预置 Agent 类型，以满足不同场景的需求：

FnCallAgent - 函数调用 Agent

FnCallAgent 是专门为函数调用场景设计的 Agent，基于 Qwen 的函数调用能力构建。它能够自动解析用户意图并调用相应的工具函数。

from qwen_agent import FnCallAgent

llm_cfg = {
    'model': 'qwen3-32b',
    'model_type': 'qwen_dashscope',
    'api_key': 'YOUR_DASHSCOPE_API_KEY',
}

agent = FnCallAgent(llm_cfg=llm_cfg)

资料来源：qwen_agent/agentchat/fncall.py

ReActChat - 推理与行动 Agent

ReActChat 基于 ReAct（Reasoning + Acting）范式构建，通过交错推理和行动实现复杂任务的自动化处理。

Assistant - 通用助手

Assistant 提供通用的对话和任务处理能力，适用于多种应用场景。

工具系统（Tools）

工具系统是 Qwen-Agent 的核心组件之一，负责管理和执行各种外部功能。

工具注册机制

graph LR
    A[工具定义] --> B[工具注册]
    B --> C[工具选择]
    C --> D[工具调用]
    D --> E[结果返回]
    E --> F[上下文更新]

内置工具

框架内置了多种常用工具，包括：

MCP（Model Context Protocol）支持

Qwen-Agent 支持通过 MCP 协议连接外部工具服务，并提供 SSE 连接超时管理和自动重连功能（v0.0.26 版本特性）。资料来源：examples/mcp/

自定义工具开发

开发者可以通过装饰器方式快速定义自定义工具：

from qwen_agent.tools import tool

@tool
def my_custom_tool(param1: str, param2: int) -> str:
    """
    自定义工具描述
    
    Args:
        param1: 参数1描述
        param2: 参数2描述
    
    Returns:
        工具执行结果
    """
    # 工具实现逻辑
    return "结果"

长文档处理方案

Qwen-Agent 针对超长文档（最长可达 100 万 tokens）的问答场景提供了两种解决方案：

快速方案 - Fast RAG

Fast RAG 方案通过高效的检索和切分策略，实现对超长文档的快速问答。该方案在保证性能的同时，能够处理极长的文档输入。

from qwen_agent import Assistant

assistant = Assistant(llm_cfg=llm_cfg, system_message='你是一个文档助手。')
assistant.run('基于提供的文档回答：xxx问题')

资料来源：examples/assistant_rag.py

高精度方案 - Parallel Doc QA

Parallel Doc QA 方案采用并行化的文档处理策略，通过多路召回和交叉验证提高答案准确性。该方案虽然计算成本较高，但在具有挑战性的基准测试中表现优于原生长上下文模型。

from qwen_agent import ParallelDocQA

qa_agent = ParallelDocQA(llm_cfg=llm_cfg)
result = qa_agent.run(document_path='长文档路径', query='问题')

资料来源：examples/parallel_doc_qa.py

LLM 配置与参数

基础配置

llm_cfg = {
    # 模型名称
    'model': 'qwen3-32b',
    
    # 模型服务类型
    'model_type': 'qwen_dashscope',  # 或 'openai', 'dashscope'
    
    # API 地址（使用 OpenAI 兼容服务时）
    'model_server': 'http://localhost:8000/v1',
    
    # API 密钥
    'api_key': 'YOUR_API_KEY',
    
    # 生成参数
    'generate_cfg': {
        # 是否启用思考模式
        'enable_thinking': True,
        # 最大思考 token 数
        'max_tokens': 20000,
        # Top P 采样参数
        'top_p': 0.8,
    }
}

参数说明

资料来源：qwen_agent/llm.py

多 Agent 协作（A2A）

社区反馈（Issue #706）关注 Qwen-Agent 是否支持 A2A（Agent-to-Agent）架构。框架支持将一个 Agent 定义为另一个 Agent 的工具，实现多 Agent 协作：

graph TD
    A[用户请求] --> B[主 Agent]
    B --> C[子 Agent 1]
    B --> D[子 Agent 2]
    B --> E[子 Agent 3]
    C --> F[执行结果]
    D --> F
    E --> F
    F --> B
    B --> G[综合响应]

协作模式

部署与集成

Gradio 部署

Qwen-Agent 原生支持 Gradio，可快速构建交互式 Web 界面：

from qwen_agent import FnCallAgent
import gradio as gr

agent = FnCallAgent(llm_cfg=llm_cfg)

demo = gr.ChatInterface(
    fn=agent.run,
    title="Qwen Agent 演示",
    description="基于 Qwen3 的智能助手"
)

demo.launch()

FastAPI 部署

将 Agent 发布为 API 服务：

from fastapi import FastAPI
from qwen_agent import FnCallAgent
from pydantic import BaseModel

app = FastAPI()
agent = FnCallAgent(llm_cfg=llm_cfg)

class ChatRequest(BaseModel):
    message: str

@app.post("/chat")
async def chat(req: ChatRequest):
    response = agent.run(req.message)
    return {"response": response}

这是社区中呼声较高的功能需求（Issue #609），框架层面支持统一的 API 发布将显著简化 Agent 的生产部署。

环境变量配置

安装指南

Windows 环境

winget install --id=astral-sh.uv -e
winget install git.git sqlite.sqlite

Python 环境

pip install qwen-agent

开发环境

git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e .

最佳实践

1. 工具设计原则

• 单一职责：每个工具应专注于完成一个明确的任务
• 清晰描述：为工具和参数提供详细的中文文档字符串
• 错误处理：工具应包含完善的异常处理和边界情况处理

2. Agent 配置建议

3. 性能优化

• 使用流式输出（Streaming）提升用户体验
• 合理设置 top_p 和 temperature 平衡创造性与稳定性
• 长对话场景启用记忆压缩和摘要机制

版本说明

当前稳定版本为 v0.0.26，主要特性：

• 支持 SSE 连接超时配置
• MCP 工具自动重连机制
• 并行函数调用优化
• OpenAI 兼容 API 增强

相关资源

• GitHub 仓库：https://github.com/QwenLM/Qwen-Agent
• 官方文档：https://qwenlm.github.io/Qwen-Agent/
• 示例代码：https://github.com/QwenLM/Qwen-Agent/tree/main/examples
• 问题反馈：https://github.com/QwenLM/Qwen-Agent/issues

社区贡献

Qwen-Agent 是一个开源项目，欢迎社区贡献者参与开发。主要贡献方式包括：

• 提交 Issue 反馈问题或建议
• 提交 Pull Request 修复问题或添加功能
• 完善文档和使用示例
• 分享基于 Qwen-Agent 的应用案例

在报告问题时，团队希望社区成员能够温和表达，共同维护良好的开源协作氛围。资料来源：Issue #1

快速开始

本页面为 Qwen-Agent 框架的入门指南，旨在帮助开发者快速上手构建基于 Qwen 大语言模型的智能体（Agent）应用。文档涵盖环境配置、基础组件使用、自定义工具开发以及常见应用场景的完整示例。

安装指南

本文档详细介绍 Qwen-Agent 框架的完整安装流程、环境配置要求以及常见问题的解决方案。Qwen-Agent 是基于 Qwen 大语言模型的 AI Agent 开发框架，提供了丰富的原子组件（如 LLM、Tools）和高级组件（如 Agents），支持函数调用、代码解释、MCP 协议集成等功能。

概述

Qwen-Agent 是一个基于 Qwen 大语言模型的 Agent 应用开发框架，其核心设计围绕 LLM（语言模型）、Tool（工具）、Agent（智能体） 和 Memory（记忆） 四大原子组件展开。框架采用模块化架构，使开发者能够灵活组合这些组件来构建复杂的 AI 应用。

资料来源：qwen_agent/agent.py:1-50

整体架构图

graph TB
    subgraph "应用层"
        Assistant["Assistant Agent"]
        BrowserQwen["BrowserQwen"]
        CodeInterpreter["Code Interpreter"]
        RAG["RAG 应用"]
    end
    
    subgraph "核心模块层"
        Agent["Agent 基类"]
        LLM["BaseChatModel"]
        Tool["BaseTool"]
        Memory["Memory"]
    end
    
    subgraph "工具生态层"
        MCP["MCP Tools"]
        FunctionCalling["Function Calling"]
        CodeInterp["代码解释器"]
        Search["搜索工具"]
    end
    
    subgraph "模型服务层"
        DashScope["DashScope API"]
        vLLM["vLLM"]
        Ollama["Ollama"]
    end
    
    Application --> Core
    Core --> Tools
    Tools --> ModelService
    
    LLM --> Agent
    Memory --> Agent
    Tool --> Agent

核心模块详解

1. Agent 模块

#### 1.1 Agent 基类

Agent 是整个框架的核心抽象类，负责协调 LLM、Tool 和 Memory 之间的交互。

class Agent:
    def __init__(self, llm, tools=None, memory=None):
        self.llm = llm
        self.tools = tools or []
        self.memory = memory

主要职责：

• 管理对话历史和上下文
• 解析 LLM 响应中的工具调用
• 执行工具并收集结果
• 生成最终回复

资料来源：qwen_agent/agent.py:30-80

#### 1.2 Assistant Agent

Assistant 是 Agent 的具体实现类，提供了开箱即用的对话智能体功能：

from qwen_agent.agents import Assistant

assistant = Assistant(
    llm={'model': 'qwen-max'},
    tools=['google_search', 'code_interpreter'],
    description='助手描述'
)

特性：

• 支持多轮对话
• 内置函数调用解析
• 可扩展的工具系统
• 灵活的提示词模板

资料来源：qwen_agent/agents/assistant.py:1-100

2. LLM 模块

#### 2.1 BaseChatModel 基类

LLM 模块是 Qwen-Agent 与大语言模型交互的核心接口。所有模型实现都继承自 BaseChatModel：

class BaseChatModel:
    def __init__(self, model: str = '', api_key: str = None, ...):
        self.model = model
        self.api_key = api_key or os.getenv('DASHSCOPE_API_KEY')
    
    def chat(self, messages, tools=None, stream=False, **kwargs):
        raise NotImplementedError

支持的模型服务：

资料来源：qwen_agent/llm/base.py:20-60

#### 2.2 函数调用（Function Calling）

函数调用是 LLM 模块的重要功能，支持模型调用外部工具：

from qwen_agent.llm import FunctionCallModel

llm = FunctionCallModel(model='qwen-max')
response = llm.chat(
    messages=[{'role': 'user', 'content': '查询北京天气'}],
    tools=[{
        'type': 'function',
        'function': {
            'name': 'get_weather',
            'parameters': {'type': 'object', 'properties': {...}}
        }
    }]
)

配置参数：

资料来源：qwen_agent/llm/function_calling.py:1-80

3. Tool 模块

#### 3.1 BaseTool 基类

Tool 模块提供了扩展 Agent 能力的标准化接口：

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('my_tool')
class MyTool(BaseTool):
    name = 'my_tool'
    description = '工具描述'
    
    def call(self, params):
        # 工具实现
        return result

工具注册机制：

• 使用 @register_tool 装饰器注册自定义工具
• 工具名称全局唯一
• 支持嵌套工具定义

资料来源：qwen_agent/tools/base.py:30-100

#### 3.2 内置工具生态

graph LR
    MCP["MCP Server"] --> MCP_Tools["MCP 工具"]
    BuiltIn["内置工具"] --> Search["搜索工具"]
    BuiltIn --> Code["代码执行"]
    BuiltIn --> File["文件操作"]
    Custom["自定义工具"] --> Registry["工具注册表"]
    
    MCP_Tools --> Registry
    Search --> Registry
    Code --> Registry
    File --> Registry
    Custom --> Registry

MCP 工具集成示例：

{
    "mcpServers": {
        "memory": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-memory"]
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
        }
    }
}

4. Memory 模块

#### 4.1 Memory 基类

Memory 模块负责管理 Agent 的对话历史和上下文：

class Memory:
    def __init__(self, max_tokens: int = 10000):
        self.messages = []
        self.max_tokens = max_tokens
    
    def add(self, message: dict):
        self.messages.append(message)
    
    def get_messages(self):
        return self.messages
    
    def clear(self):
        self.messages = []

功能特性：

• 自动历史记录管理
• Token 数量限制和截断
• 支持消息过滤和检索

资料来源：qwen_agent/memory/memory.py:1-60

模块交互流程

sequenceDiagram
    participant User as 用户
    participant Agent as Agent
    participant LLM as LLM
    participant Tool as Tool
    participant Memory as Memory
    
    User->>Agent: 发送请求
    Agent->>Memory: 获取历史上下文
    Agent->>LLM: 发送带历史的请求
    LLM-->>Agent: 返回响应/工具调用
    
    alt 需要调用工具
        Agent->>Tool: 执行工具
        Tool-->>Agent: 返回结果
        Agent->>LLM: 继续对话
        LLM-->>Agent: 返回最终响应
    end
    
    Agent->>Memory: 更新对话历史
    Agent-->>User: 返回结果

扩展开发指南

开发自定义 Agent

from qwen_agent.agents import Agent
from qwen_agent.llm import BaseChatModel
from qwen_agent.tools.base import BaseTool

class MyAgent(Agent):
    def __init__(self, llm: BaseChatModel, tools: list[BaseTool] = None):
        super().__init__(llm=llm, tools=tools)
        # 自定义初始化逻辑
    
    def run(self, query: str, **kwargs):
        # 自定义运行逻辑
        return super().run(query, **kwargs)

开发自定义 Tool

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('custom_tool')
class CustomTool(BaseTool):
    name = 'custom_tool'
    description = '自定义工具描述'
    parameters = {
        'type': 'object',
        'properties': {
            'param1': {'type': 'string', 'description': '参数1'}
        },
        'required': ['param1']
    }
    
    def call(self, param1: str, **kwargs):
        # 实现工具逻辑
        return {'result': f'处理了: {param1}'}

社区相关讨论

API 服务化需求

社区 Issue #609 提出了将 Agent 发布为 API 服务的需求：

"目前开了几个Agent，确实效果不错...所以这几天一直在寻找将 Agent 发布成一个 API，可以使用 Fast API 等来发布"

当前框架主要通过 Gradio 提供演示界面，生产环境部署需要开发者自行实现 API 封装。

Agent-to-Agent 架构

Issue #706 询问框架是否支持 A2A（Agent-to-Agent）架构：

"框架是否支持定义一个 Agent 作为一个工具可以由另一个 Agent 去根据需要调用？"

通过将 Agent 注册为 Tool，可以实现 Agent 间的调用和协作。

配置参数汇总

LLM 配置

llm_config = {
    'model': 'qwen-max',
    'api_key': os.getenv('DASHSCOPE_API_KEY'),
    'max_tokens': 2048,
    'top_p': 0.8,
    'temperature': 0.7,
    'stream': False,
    # vLLM 特定参数
    'use_raw_api': True,
}

Agent 配置

总结

Qwen-Agent 的核心模块架构体现了清晰的关注点分离原则：

1. LLM 模块：提供统一的模型调用接口，支持多种后端服务
2. Tool 模块：通过标准化协议扩展 Agent 能力
3. Memory 模块：管理对话历史和上下文
4. Agent 模块：协调以上三个模块，实现智能对话和应用

这种架构设计使得开发者可以专注于业务逻辑，通过组合和扩展核心组件来构建满足特定需求的 AI 应用。

1. 系统概述

Qwen-Agent 是一个基于 Qwen 大语言模型的 Agent 开发框架，旨在帮助开发者快速构建具有指令遵循、工具使用、规划推理和记忆能力的 LLM 应用。Agent 系统是整个框架的核心组件，提供了从基础 Agent 抽象到多种预置 Agent 实现的全方位支持。

1.1 设计目标

Agent 系统的主要设计目标包括以下几个方面：

模块化架构：框架采用继承和多态的面向对象设计，将 Agent 的核心逻辑抽象为基类，具体的 Agent 类型通过继承和重写特定方法来实现差异化功能。这种设计使得开发者可以方便地扩展现有 Agent 或创建全新的 Agent 类型。

工具集成能力：Agent 系统原生支持工具调用机制，开发者可以通过注册工具来扩展 Agent 的能力边界。框架内置了多种常用工具，如代码解释器、函数调用、RAG 检索等，同时也支持通过 MCP（Model Context Protocol）协议接入外部工具服务。

多 Agent 协作：框架提供了 GroupChat 功能，支持多个 Agent 之间的协作交互。这使得复杂任务可以被分解为多个子任务，由不同的专业 Agent 分别处理后再整合结果。

灵活的对话管理：Agent 系统提供了完善的对话历史管理机制，支持流式输出、多轮对话、消息过滤等功能，可以满足不同应用场景的需求。

1.2 核心组件关系

Agent 系统由多个核心组件构成，它们之间的关系如下所示：

graph TD
    A[LLM 大语言模型] --> B[BaseChatModel]
    B --> C[FunctionCallChat]
    B --> D[BaseAgent]
    D --> E[Assistant]
    D --> F[FncallAgent]
    D --> G[ReActChat]
    D --> H[GroupChat]
    E --> I[自定义 Agent]
    F --> I
    G --> I
    H --> I
    J[Tools 工具集] --> K[BaseTool]
    K --> L[代码解释器]
    K --> M[RAG 工具]
    K --> N[MCP 工具]
    I --> J

从图中可以看出，Agent 系统采用了经典的分层架构设计。LLM 是最底层的模型接口层，BaseAgent 定义了 Agent 的标准行为，各种预置的 Agent 实现（Assistant、FncallAgent、ReActChat、GroupChat）提供了不同场景下的最佳实践，而 Tools 系统则为 Agent 提供了执行具体任务的能力。

2. Agent 基类架构

2.1 BaseAgent 抽象类

BaseAgent 是所有 Agent 类型的基类，定义 Agent 的核心接口和行为规范。根据源码，BaseAgent 的主要职责包括消息处理、工具调用控制、对话状态管理等。

BaseAgent 核心属性：

BaseAgent 核心方法：

资料来源：qwen_agent/agent.py:1-150

2.2 消息处理流程

Agent 的消息处理流程可以划分为以下几个阶段：

sequenceDiagram
    participant User as 用户
    participant Agent as BaseAgent
    participant LLM as 大语言模型
    participant Tool as 工具系统
    participant Memory as 记忆系统

    User->>Agent: 发送用户消息
    Agent->>Memory: 查询历史上下文
    Memory-->>Agent: 返回相关记忆
    Agent->>Agent: 构建完整消息列表
    Agent->>LLM: 发送消息请求
    alt 模型返回工具调用
        LLM-->>Agent: 返回函数调用指令
        Agent->>Tool: 执行工具调用
        Tool-->>Agent: 返回执行结果
        Agent->>LLM: 将结果反馈给模型
        LLM-->>Agent: 生成最终回复
    else 模型直接回复
        LLM-->>Agent: 返回文本回复
    end
    Agent->>Memory: 更新对话记忆
    Agent-->>User: 流式返回响应

从上述流程可以看出，Agent 的核心工作模式是一个"思考-行动-观察"的循环。模型根据输入决定是直接回复还是调用工具，工具执行后的结果会被反馈给模型以生成下一轮响应。这个循环会持续进行，直到模型认为任务完成或达到最大迭代次数。

2.3 工具调用机制

工具调用是 Agent 系统的重要能力，它使得 Agent 能够执行具体的操作而不仅仅是生成文本。Qwen-Agent 提供了两种主要的工具调用方式：

Function Calling 模式：通过模型的 function call 能力，让模型直接生成结构化的工具调用指令。这种方式适合与支持 function call 的模型配合使用，如 Qwen2、Qwen3 等。

ReAct 模式：通过提示词引导模型生成"Thought-Action-Observation"格式的推理过程，然后由系统解析并执行相应的工具调用。这种方式更加灵活，可以与不支持原生 function call 的模型配合使用。

3. 预置 Agent 类型详解

3.1 Assistant Agent

Assistant 是最基础的 Agent 类型，提供了简洁易用的对话交互能力。它适合作为开发自定义 Agent 的起点，也是快速验证想法和原型的最佳选择。

主要特性：

• 支持多轮对话和流式输出
• 可配置的系统提示词
• 灵活的工具注册机制
• 文件附件支持
• 对话历史自动管理

基本使用方式：

from qwen_agent.agents import Assistant
from qwen_agent.llm import get_chat_model

llm_cfg = {
    'model': 'qwen-plus',
    'model_server': 'dashscope',
    'api_key': os.getenv('DASHSCOPE_API_KEY')
}
llm = get_chat_model(llm_cfg)

bot = Assistant(
    llm=llm,
    system_message='你是一个有用的AI助手',
    function_list=['my_image_gen', 'code_interpreter']
)

messages = [{'role': 'user', 'content': '请帮我画一张图片'}]
for response in bot.run(messages):
    print(response)

资料来源：qwen_agent/agents/assistant.py:1-100

3.2 FncallAgent 函数调用Agent

FncallAgent 是专门为函数调用场景优化的 Agent 类型，它充分利用了 Qwen2/Qwen3 系列模型的原生 function call 能力，提供了更加稳定和高效的工具调用体验。

与 Assistant 的区别：

FncallAgent 特别适合需要频繁调用工具的生产环境应用，因为它减少了提示词解析的不确定性，提高了工具调用的准确性和稳定性。

资料来源：qwen_agent/agents/fncall_agent.py:1-80

3.3 ReActChat 推理与行动Agent

ReActChat 基于 ReAct（Reasoning + Acting）范式实现，是处理复杂多步推理任务的理想选择。这种 Agent 能够通过显式的思考过程来分解问题，然后逐步执行工具调用来获取信息或执行操作。

ReAct 推理模式：

graph TD
    A[接收用户问题] --> B[Thought: 思考当前状态和下一步]
    B --> C[Action: 选择并执行工具]
    C --> D[Observation: 观察执行结果]
    D --> E{任务完成?}
    E -->|否| B
    E -->|是| F[生成最终回答]

ReAct 的优势：

• 可解释性：推理过程清晰可见，便于调试和理解 Agent 的行为
• 灵活性：不依赖模型的原生 function call 能力，可与各种模型配合
• 鲁棒性：通过多次小步推理降低单次决策失误的影响
• 组合性：可以自然地组合多个工具完成复杂任务

ReActChat 特别适合以下场景：需要多步信息检索的问答系统、需要进行复杂计算或数据处理的任务、需要与环境进行多轮交互的应用。

资料来源：qwen_agent/agents/react_chat.py:1-120

3.4 GroupChat 多Agent协作系统

GroupChat 是 Qwen-Agent 框架中用于实现多 Agent 协作的高级功能。它允许定义多个专业化的 Agent，并通过协调机制让它们协作完成复杂任务。

GroupChat 架构：

graph LR
    subgraph GroupChat
        C[Coordinator<br/>协调器]
        A1[Agent 1]
        A2[Agent 2]
        A3[Agent N]
        C --> A1
        C --> A2
        C --> A3
    end
    U[User<br/>用户]
    U --> C
    A1 --> C
    A2 --> C
    A3 --> C

核心机制：

GroupChat 的协调器负责管理对话流程，它会根据当前任务和 Agent 的能力描述，决定将任务分配给哪个 Agent 处理，以及如何整合各 Agent 的回复。协调器可以采用不同的策略，如顺序执行、并行执行或动态路由。

应用场景：

• 任务分解：将复杂任务分解为多个子任务，分配给专业 Agent
• 专家咨询：不同领域的专家 Agent 协作提供综合建议
• 质量保证：一个 Agent 生成内容，另一个 Agent 进行审查

资料来源：qwen_agent/agents/group_chat.py:1-150

4. 工具系统详解

4.1 工具架构

Qwen-Agent 的工具系统采用插件化设计，所有工具都继承自 BaseTool 基类。这种设计使得开发者可以方便地添加自定义工具，同时保证工具使用的统一接口。

BaseTool 接口定义：

工具注册机制：

框架使用装饰器模式来注册工具，通过 @register_tool 装饰器可以将自定义类注册到全局工具列表中：

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('my_tool')
class MyTool(BaseTool):
    description = '我的自定义工具'
    name = 'my_tool'
    
    def call(self, params: str, **kwargs) -> str:
        # 工具实现
        return result

资料来源：qwen_agent/tools/__init__.py:1-50

4.2 内置工具

框架提供了多种内置工具，开发者可以直接使用：

代码解释器配置：

代码解释器是 Agent 系统的重要工具，它允许 Agent 执行动态生成的代码来完成任务。配置代码解释器需要确保 Docker 环境可用：

tools = ['code_interpreter']  # 内置工具
# 或包含自定义工具
tools = ['my_image_gen', 'code_interpreter']

4.3 MCP 工具集成

MCP（Model Context Protocol）是一种标准化的工具集成协议，Qwen-Agent 提供了对 MCP 的原生支持。通过 MCP，开发者可以接入丰富的外部工具生态系统。

MCP 配置示例：

{
    "mcpServers": {
        "memory": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-memory"]
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
        }
    }
}

MCP 工具的配置需要安装 Node.js 环境，并且对于某些 MCP 服务器还需要 uv 等依赖工具。框架支持自动重连机制，能够在连接断开后自动恢复。

5. 与大语言模型的集成

5.1 LLM 接口抽象

Qwen-Agent 定义了统一的 LLM 接口 BaseChatModel，所有支持的模型服务都实现这个接口。这种设计使得切换不同的模型提供商变得非常简单。

支持的模型服务：

配置示例：

llm_cfg = {
    'model': 'qwen-plus',
    'model_server': 'dashscope',
    'api_key': os.getenv('DASHSCOPE_API_KEY'),
    # 可选参数
    'top_p': 0.8,
    'temperature': 0.7,
    'max_tokens': 2000
}

资料来源：qwen_agent/llm/__init__.py:1-100

5.2 Function Call 配置

对于支持 function call 的模型（如 Qwen2、Qwen3 系列），框架提供了灵活的配置选项：

vLLM 部署建议：

• QwQ 和 Qwen3 模型：建议不要添加 --enable-auto-tool-choice 和 --tool-call-parser hermes 参数，框架会自动解析工具输出
• Qwen3-Coder 模型：建议启用上述参数，使用 vLLM 内置的工具解析，并配合 use_raw_api 参数使用

5.3 流式输出

Agent 系统原生支持流式输出，这使得用户可以实时看到 Agent 的响应，提升交互体验：

response_plain_text = ''
for response in bot.run(messages):
    response_plain_text = typewriter_print(response, response_plain_text)

typewriter_print 函数实现了逐字符的流式打印效果，可以直接用于 Gradio 或 WebUI 界面。

6. 部署与集成

6.1 Gradio 界面部署

Qwen-Agent 提供了便捷的 Gradio 界面支持，只需几行代码即可将 Agent 部署为 Web 应用：

from qwen_agent.gui import WebUI

WebUI(bot).run()

这使得开发者可以快速创建可交互的 Demo，方便测试和演示。

6.2 API 服务化

根据社区反馈（Issue #609），将 Agent 发布为 API 服务是一个重要需求。虽然框架主要面向 Gradio 部署，但开发者可以通过以下方式实现 API 服务化：

FastAPI 集成示例：

from fastapi import FastAPI
from pydantic import BaseModel
from qwen_agent.agents import Assistant

app = FastAPI()

class ChatRequest(BaseModel):
    message: str
    history: list = []

@app.post("/chat")
async def chat(request: ChatRequest):
    messages = request.history + [{'role': 'user', 'content': request.message}]
    responses = []
    for response in agent.run(messages):
        responses.extend(response)
    return {"response": responses[-1], "history": messages + responses}

框架层面可能会在后续版本中提供原生的 API 服务支持，以简化部署流程。

6.3 A2A 架构支持

社区用户（Issue #706）询问框架是否支持 A2A（Agent-to-Agent）架构。GroupChat 功能部分实现了多 Agent 协作能力，允许一个 Agent 将另一个 Agent 作为工具调用：

# Agent A 可以被 Agent B 调用
agent_b = Assistant(
    function_list=['agent_a', 'other_tools']
)

这种设计使得复杂任务可以被分解为多个专业化的 Agent，每个 Agent 负责特定领域的任务。

7. 最佳实践

7.1 工具设计原则

设计有效的工具需要遵循以下原则：

7.2 提示词工程

系统提示词（system_message）对 Agent 的行为有重要影响。以下是一些最佳实践：

• 明确角色：清楚地定义 Agent 的身份和能力范围
• 具体指令：提供清晰的任务执行步骤
• 输出格式：指定期望的输出格式和结构
• 约束条件：说明边界情况和限制

7.3 性能优化

消息历史管理：长期对话会导致上下文过长，影响响应速度和成本。建议实现历史消息的摘要或截断机制。

工具选择优化：不必要的工具会增加模型的选择负担，只注册与当前任务相关的工具。

缓存策略：对于频繁使用的工具结果，可以实现缓存机制避免重复执行。

8. 常见问题

Q1: 如何选择合适的 Agent 类型？

Q2: 如何处理工具调用失败？

框架提供了 max_retries 配置来控制重试次数。工具调用失败时，建议：

1. 检查工具的输入参数格式是否正确
2. 确保工具服务正常运行（如 MCP 服务器）
3. 在工具实现中添加适当的错误处理和日志
4. 考虑添加降级策略，如返回预设的默认值

Q3: 如何实现自定义 Agent？

继承 BaseAgent 并重写以下方法：

from qwen_agent.agent import Agent

class MyAgent(Agent):
    def _run(self, messages: List[Dict]) -> Iterator[Dict]:
        # 自定义运行逻辑
        pass

Q4: 如何进行函数调用微调？

社区用户（Issue #368）关注函数调用微调的问题。微调数据构造需要注意：

1. 数据格式：按照模型要求的 function call 格式组织训练数据
2. 正负样本：包含正确调用和错误调用的示例
3. 多样性：覆盖各种调用场景和边界情况
4. 质量控制：确保标注数据的一致性和准确性

9. 总结

Qwen-Agent 的 Agent 系统提供了完整的多层次解决方案，从底层的 LLM 接口抽象，到中层的 BaseAgent 核心逻辑，再到上层的多种预置 Agent 实现，为开发者构建智能应用提供了坚实的技术基础。

框架的设计理念强调模块化、可扩展性和易用性。通过继承和组合机制，开发者可以灵活地创建满足特定需求的 Agent 类型。内置的工具系统、MCP 集成、多 Agent 协作等高级功能，使得复杂应用的开发变得简单高效。

随着社区的不断发展，框架将继续演进以支持更多的应用场景，包括 API 服务化、A2A 架构增强等方向。建议开发者持续关注框架的更新和社区讨论，以获取最新的功能和改进。

概述

大模型集成是 Qwen-Agent 框架的核心功能模块，它提供了与各类大语言模型（LLM）服务交互的统一接口。Qwen-Agent 支持多种模型服务部署方式，包括阿里巴巴云 DashScope 通义千问服务以及符合 OpenAI 接口规范的第三方模型服务。

该模块的主要职责包括：

• 提供标准化的模型调用接口（BaseChatModel 抽象基类）
• 支持函数调用（Function Calling）能力
• 处理模型响应的流式输出与非流式输出
• 管理不同模型服务的配置与认证

资料来源：qwen_agent/llm/qwen_dashscope.py:1-50

架构设计

整体架构

Qwen-Agent 的大模型集成采用分层架构设计，核心层为抽象基类，具体实现层针对不同服务提供商提供适配器。

graph TD
    A[Agent / 应用层] --> B[BaseChatModel 抽象基类]
    B --> C[QwenDashScope 模型]
    B --> D[OpenAI 兼容模型]
    B --> E[自定义模型扩展]
    
    C --> F[DashScope API]
    D --> G[vLLM / Ollama / 其他兼容服务]
    
    H[Function Calling 模块] --> B
    I[工具注册系统] --> H

核心组件

资料来源：qwen_agent/llm/oai.py:1-80

模型服务配置

DashScope 服务配置

DashScope 是阿里巴巴云提供的大模型服务，Qwen-Agent 提供了开箱即用的集成支持。

环境变量配置：

export DASHSCOPE_API_KEY="your-api-key-here"

基础调用示例：

from qwen_agent.llm import QwenDashScope

llm = QwenDashScope(model='qwen-turbo')
messages = [{'role': 'user', 'content': '你好，请介绍一下你自己'}]
response = llm.chat(messages)

资料来源：qwen_agent/llm/qwen_dashscope.py:20-100

OpenAI 兼容服务配置

对于私有部署或第三方模型服务，Qwen-Agent 支持 OpenAI 接口规范的 API。

支持的部署方案：

配置示例：

from qwen_agent.llm import OpenAI

llm = OpenAI(
    model='qwen2.5-7b-instruct',
    api_key='empty',  # 本地部署通常不需要密钥
    base_url='http://localhost:8000/v1'
)

资料来源：qwen_agent/llm/oai.py:50-150

模型参数配置

框架支持在初始化时传入模型 API 参数：

llm = QwenDashScope(
    model='qwen-plus',
    temperature=0.7,
    top_p=0.8,
    max_tokens=2048,
    seed=1234  # 设置随机种子以实现可复现输出
)

常用参数说明：

资料来源：qwen_agent/llm/qwen_dashscope.py:80-120

函数调用（Function Calling）

功能概述

函数调用是 Qwen-Agent 实现工具增强型 Agent 的核心技术。它允许模型生成结构化的函数调用指令，而非自由文本响应。

graph LR
    A[用户输入] --> B[模型推理]
    B --> C{是否需要调用函数?}
    C -->|是| D[生成函数调用]
    D --> E[执行工具]
    E --> F[返回结果]
    F --> B
    C -->|否| G[直接回复]
    G --> H[用户]
    F --> B
    B --> H

函数注册机制

使用装饰器模式注册自定义工具函数：

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    description = '生成图片的工具'
    parameters = {
        'type': 'object',
        'properties': {
            'prompt': {
                'type': 'string',
                'description': '图片生成描述'
            }
        },
        'required': ['prompt']
    }
    
    def call(self, params: dict, **kwargs) -> str:
        prompt = params.get('prompt')
        # 执行图片生成逻辑
        return f"已生成图片: {prompt}"

资料来源：examples/function_calling.py:1-80

函数调用提示词

框架使用专门的提示词模板来引导模型生成正确的函数调用格式：

from qwen_agent.llm.fncall_prompts.base_fncall_prompt import BaseFncallPrompt

prompt_handler = BaseFncallPrompt()
formatted_prompt = prompt_handler.format(
    messages=messages,
    tools=tools_schema
)

资料来源：qwen_agent/llm/fncall_prompts/base_fncall_prompt.py:1-60

函数调用工作流

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant L as LLM
    participant T as 工具系统
    
    U->>A: 用户消息
    A->>L: 发送带工具描述的请求
    L-->>A: 返回函数调用或文本
    alt 函数调用
        A->>T: 调用工具
        T-->>A: 返回执行结果
        A->>L: 发送工具结果继续推理
        L-->>A: 生成最终回复
    end
    A-->>U: 返回结果

与 Agent 的集成

基础 Agent 配置

大模型集成与 Agent 模块紧密配合：

from qwen_agent.agents import Assistant

agent = Assistant(
    llm=QwenDashScope(model='qwen-plus'),
    tools=['my_image_gen', 'web_search'],
    system_message='你是一个有用的AI助手'
)

模型选择建议

常见问题与最佳实践

关于函数调用微调

社区中有用户反馈自定义数据的函数调用效果不佳（参见 Issue #368）。对于特殊数据格式的函数调用场景，可能需要微调模型。微调数据的构造需要包含：

1. 标准格式的函数描述（JSON Schema）
2. 对应的对话历史
3. 正确的函数调用标签

vLLM 部署注意事项

对于 QwQ 和 Qwen3 模型，不建议添加以下参数：

--enable-auto-tool-choice
--tool-call-parser hermes

框架会自动解析 vLLM 的工具输出。

对于 Qwen3-Coder 模型，建议启用上述参数并结合 use_raw_api 参数使用。

资料来源：README.md - Preparation: Model Service

API 密钥管理

生产环境中建议使用环境变量或密钥管理服务存储 API 密钥：

import os

llm = QwenDashScope(
    model='qwen-plus',
    api_key=os.getenv('DASHSCOPE_API_KEY')
)

扩展开发

自定义模型适配器

如需集成新的模型服务，可以继承 BaseChatModel 基类：

from qwen_agent.llm import BaseChatModel

class MyCustomLLM(BaseChatModel):
    def __init__(self, model: str, **kwargs):
        super().__init__(model=model, **kwargs)
        # 初始化自定义配置
        
    def chat(self, messages: list, **kwargs):
        # 实现自定义调用逻辑
        pass
        
    def chat_with_functions(self, messages: list, functions: list, **kwargs):
        # 实现函数调用逻辑
        pass

提示词模板定制

可以通过继承 BaseFncallPrompt 类来自定义函数调用提示词格式：

from qwen_agent.llm.fncall_prompts.base_fncall_prompt import BaseFncallPrompt

class CustomFncallPrompt(BaseFncallPrompt):
    def format(...):
        # 自定义格式化逻辑
        pass

总结

Qwen-Agent 的大模型集成模块提供了灵活、统一的模型调用接口。通过抽象基类设计，框架同时支持云端服务（DashScope）和私有部署（vLLM、Ollama）。函数调用能力的完善支持使得构建工具增强型 Agent 变得简单高效。开发者可以根据实际需求选择合适的模型服务，并通过自定义扩展机制适配特殊场景。

概述

Qwen-Agent 框架提供了强大的工具（Tool）系统，使 Agent 能够调用外部功能来扩展其能力。工具系统基于面向对象设计，所有工具都继承自 BaseTool 基类，确保了统一的接口和灵活的扩展性。本指南将详细介绍 Qwen-Agent 内置工具的使用方法以及如何开发自定义工具。

资料来源：qwen_agent/tools/base.py:1-50

工具系统架构

核心类层次结构

graph TD
    A[BaseTool] --> B[DocParser]
    A --> C[ImageGen]
    A --> D[WebSearch]
    A --> E[Retrieval]
    A --> F[自定义工具]
    
    G[register_tool 装饰器] --> F
    H[class BaseChatModel] --> I[LLM 调用工具]

Qwen-Agent 的工具系统遵循插件化设计原则，通过 register_tool 装饰器实现工具的注册和管理。

资料来源：qwen_agent/tools/base.py:50-100

工具执行流程

sequenceDiagram
    participant Agent as Agent
    participant Tool as 工具系统
    participant LLM as 大语言模型
    
    Agent->>LLM: 发送用户请求
    LLM-->>Agent: 返回工具调用指令
    Agent->>Tool: 调用指定工具
    Tool->>Tool: 执行工具逻辑
    Tool-->>Agent: 返回执行结果
    Agent->>LLM: 汇总结果生成回复

内置工具详解

DocParser（文档解析工具）

DocParser 工具用于解析各类文档内容，支持 PDF、Word、Excel 等常见文档格式。该工具是构建 RAG（检索增强生成）系统的重要组成部分。

资料来源：qwen_agent/tools/doc_parser.py:1-80

#### 主要功能

#### 使用示例

from qwen_agent.tools.doc_parser import DocParser

# 初始化文档解析器
parser = DocParser()

# 解析文档
result = parser.call({"file_path": "/path/to/document.pdf"})

ImageGen（图像生成工具）

ImageGen 工具集成了图像生成能力，可以根据文本描述生成对应的图像。该工具基于扩散模型实现。

资料来源：qwen_agent/tools/image_gen.py:1-60

#### 配置参数

WebSearch（网络搜索工具）

WebSearch 工具为 Agent 提供网络搜索能力，使其能够获取最新的在线信息。

资料来源：qwen_agent/tools/web_search.py:1-70

#### 搜索功能

#### 使用示例

from qwen_agent.tools.web_search import WebSearch

# 初始化搜索工具
searcher = WebSearch()

# 执行搜索
results = searcher.call({
    "query": "Qwen-Agent 使用教程",
    "recency_days": 7
})

Retrieval（检索工具）

Retrieval 工具用于在向量数据库中进行语义检索，是构建知识库问答系统的核心组件。

资料来源：qwen_agent/tools/retrieval.py:1-90

#### 检索流程

graph LR
    A[用户查询] --> B[向量化编码]
    B --> C[向量数据库]
    C --> D[相似度计算]
    D --> E[返回相关文档]
    
    F[文档入库] --> G[文本向量化]
    G --> C

自定义工具开发

基础工具类

所有自定义工具必须继承自 BaseTool 类，并实现必要的方法。

资料来源：qwen_agent/tools/base.py:100-150

#### 必选方法

#### 可选配置

工具注册装饰器

使用 @register_tool 装饰器将工具类注册到工具管理系统中。

资料来源：qwen_agent/tools/base.py:150-200

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('my_custom_tool')
class MyCustomTool(BaseTool):
    """
    自定义工具示例
    
    该工具实现了一个简单的计算功能
    """
    
    description = "一个简单的计算器工具"
    parameters = [
        {
            "name": "operation",
            "type": "string",
            "description": "运算类型：add/subtract/multiply/divide",
            "required": True
        },
        {
            "name": "a",
            "type": "number",
            "description": "第一个操作数",
            "required": True
        },
        {
            "name": "b",
            "type": "number",
            "description": "第二个操作数",
            "required": True
        }
    ]
    
    def call(self, params: dict) -> str:
        operation = params.get("operation")
        a = params.get("a")
        b = params.get("b")
        
        if operation == "add":
            return str(a + b)
        elif operation == "subtract":
            return str(a - b)
        elif operation == "multiply":
            return str(a * b)
        elif operation == "divide":
            if b == 0:
                return "Error: 除数不能为零"
            return str(a / b)
        else:
            return f"Error: 不支持的运算类型 {operation}"

工具开发最佳实践

#### 1. 错误处理

确保工具具有健壮的错误处理机制：

def call(self, params: dict) -> str:
    try:
        # 业务逻辑
        result = self._process(params)
        return json.dumps({"status": "success", "result": result})
    except ValueError as e:
        return json.dumps({"status": "error", "message": str(e)})
    except Exception as e:
        return json.dumps({"status": "error", "message": "内部错误"})

#### 2. 参数验证

在执行前验证所有必要参数：

def call(self, params: dict) -> str:
    required_params = ["param1", "param2"]
    for param in required_params:
        if param not in params:
            return json.dumps({
                "status": "error",
                "message": f"缺少必要参数: {param}"
            })

#### 3. 返回格式

建议使用结构化的 JSON 格式返回结果：

{
    "status": "success" | "error",
    "result": ...,
    "message": "..."
}

在 Agent 中使用工具

配置工具列表

创建 Agent 时，通过 tools 参数指定可用的工具：

资料来源：qwen_agent/agents/assistant.py:1-100

from qwen_agent.agents import Assistant
from qwen_agent.tools import DocParser, WebSearch, Retrieval

# 创建带有工具的 Agent
bot = Assistant(
    llm={
        "model": "qwen-plus",
        "api_key": "your-api-key"
    },
    tools=[
        DocParser(),
        WebSearch(),
        Retrieval()
    ]
)

# 与 Agent 对话
response = bot.run([
    {"role": "user", "content": "帮我搜索 Qwen-Agent 的最新更新"}
])

动态添加工具

支持在运行时动态添加或移除工具：

from qwen_agent.tools import ImageGen

# 运行时添加图像生成工具
bot.tools.append(ImageGen())

社区相关讨论

根据社区反馈，以下是一些工具使用相关的典型场景：

常见问题

Q: 如何处理工具执行超时？

A: 建议在工具的 call 方法中实现超时控制，或在 Agent 层面配置请求超时参数。

Q: 自定义工具如何支持流式输出？

A: 在返回结果中添加流式标记，Agent 系统会自动处理流式响应。

Q: 工具调用失败时如何处理？

A: 工具应返回结构化的错误信息，Agent 会根据错误类型决定是否重试或继续执行。

扩展阅读

• 函数调用示例
• RAG 应用示例
• BrowserQwen 浏览器助手

总结

Qwen-Agent 的工具系统提供了灵活且可扩展的架构，通过继承 BaseTool 类和使用 @register_tool 装饰器，开发者可以轻松创建自定义工具。内置工具覆盖了文档解析、图像生成、网络搜索和语义检索等常用场景，为构建功能丰富的 AI Agent 应用提供了坚实基础。

概述

代码解释器（Code Interpreter）是 Qwen-Agent 框架中的一个核心工具组件，它允许大语言模型（LLM）在沙箱化的 Docker 容器环境中执行 Python 代码，实现动态计算、数据分析、文件处理等功能。该组件通过集成 Jupyter 内核协议，支持代码的交互式执行、状态保持以及多语言输出（如文本、图片、HTML 等）。

代码解释器的主要作用是扩展 LLM 的能力边界，使其能够执行实际的数据处理任务，而不仅仅依赖预训练知识。通过在隔离的容器环境中运行代码，系统可以安全地执行用户提供的代码逻辑，同时保持与主系统的隔离，确保生产环境的安全性。

架构设计

整体架构

代码解释器采用了客户端-服务端架构设计，包含三个核心组件：代码解释器工具层、Python 执行器层和 Docker 容器运行时层。这种分层设计确保了职责分离和模块化可维护性。

graph TD
    A[LLM Agent] --> B[Code Interpreter Tool]
    B --> C[Python Executor]
    C --> D[Docker Container]
    D --> E[Jupyter Kernel]
    E --> F[Code Execution]
    F --> G[Output Results]
    G --> H[Images/Markdown/JSON]
    
    style A fill:#e1f5fe
    style D fill:#fff3e0
    style E fill:#f3e5f5

组件职责

核心组件详解

CodeInterpreter 工具类

CodeInterpreter 是代码解释器对外暴露的工具接口，继承自 BaseTool 基类。它负责接收来自 LLM 的代码执行请求，并将执行结果转换为格式化的消息返回给调用方。

该类支持多种输出格式，包括纯文本、Markdown、JSON 数据以及图片等多媒体内容。通过内置的输出格式化器，它能够智能识别代码执行结果的类型，并生成对应的可视化展示。

关键特性：

• 多格式输出支持：自动识别并格式化代码执行结果
• 状态持久化：在同一会话中维护代码执行状态
• 错误处理：优雅地处理代码执行错误并返回有意义的错误信息
• 资源限制：防止恶意代码消耗过多系统资源

PythonExecutor 执行器

PythonExecutor 是底层代码执行的核心引擎，负责管理 Jupyter 内核的生命周期和代码执行流程。它通过 ZeroMQ 协议与容器内的 Jupyter 内核进行通信，实现高效的请求-响应交互。

执行器采用以下工作流程：

sequenceDiagram
    participant Agent as LLM Agent
    participant Executor as PythonExecutor
    participant Kernel as Jupyter Kernel
    participant Docker as Docker Container
    
    Agent->>Executor: 发送代码请求
    Executor->>Kernel: 提交代码
    Kernel->>Kernel: 执行代码
    Kernel-->>Executor: 返回结果
    Executor->>Executor: 格式化输出
    Executor-->>Agent: 返回格式化结果

执行器支持以下核心功能：

• 内核管理：启动、连接、断开和重启 Jupyter 内核
• 代码执行：向内核提交代码并获取执行结果
• 输出捕获：捕获 stdout、stderr 以及各种媒体输出
• 状态维护：管理全局变量和函数定义的生命周期

Docker 容器环境

代码解释器依赖 Docker 容器来提供隔离的执行环境。容器镜像基于标准的 Python 运行环境，并预装了数据科学和机器学习常用的库。

Dockerfile 中定义了容器镜像的构建配置，包括基础镜像选择、依赖安装、环境变量设置等。通过使用 Docker，系统可以实现：

• 进程隔离：代码在独立的容器中运行，与主机系统隔离
• 资源控制：限制容器的 CPU、内存和网络使用
• 环境一致性：确保代码在不同环境中有一致的执行结果
• 安全隔离：防止恶意代码影响主机系统

Jupyter 内核初始化

code_interpreter_init_kernel.py 脚本负责初始化 Jupyter 内核环境。它配置了内核的各种参数，包括超时设置、输出格式、预加载模块等。

初始化过程完成以下任务：

• 配置内核连接参数
• 设置输出重定向规则
• 预加载常用库（如 numpy、pandas）
• 配置图形输出后端（如 matplotlib）

使用方式

基本集成

将代码解释器集成到 Agent 中非常简单，只需在创建 Agent 时将其添加到工具列表中：

from qwen_agent.agents import Assistant
from qwen_agent.tools import CodeInterpreter

# 创建代码解释器工具
code_interpreter = CodeInterpreter()

# 创建 Agent 并注册工具
bot = Assistant(
    llm={'model': 'qwen-max'},
    function_tools=[code_interpreter]
)

# 与 Agent 对话
response = bot.run([
    {'role': 'user', 'content': '请计算 1 到 100 的和并可视化'}
])

高级配置

代码解释器支持多种配置参数，可以根据具体需求进行定制：

与 TIR 数学结合

代码解释器可以与 Thinking-Inference-Repeat（TIR）模式结合使用，提升模型在数学推理任务中的表现。通过让模型在思考过程中调用代码解释器执行计算，可以有效减少推理错误。

# 参考 examples/tir_math.py 中的实现模式
from qwen_agent.agents import Assistant
from qwen_agent.tools import CodeInterpreter

llm_cfg = {
    'model': 'qwq-32b',
    'model_type': 'qwen_dashscope',
    'thinking_inference': {
        'type': 'enabled',
        'extra_params': {'enable_search': True}
    }
}

bot = Assistant(
    llm=llm_cfg,
    function_tools=[CodeInterpreter()]
)

工作流程

代码执行完整流程

flowchart TD
    A[用户输入请求] --> B{LLM 分析请求}
    B -->|需要代码执行| C[生成 Python 代码]
    B -->|直接回答| Z[返回文本响应]
    C --> D[调用 CodeInterpreter]
    D --> E[创建/复用 Executor]
    E --> F[提交代码到内核]
    F --> G{执行中?}
    G -->|是| H[监控执行状态]
    G -->|超时| I[终止执行]
    I --> J[返回超时错误]
    H -->|完成| K[捕获输出结果]
    K --> L[格式化输出]
    L --> M[返回结果给 LLM]
    M --> N{LLM 继续?}
    N -->|是| B
    N -->|否| O[返回最终响应]
    
    style G fill:#fff3e0
    style H fill:#e8f5e9
    style I fill:#ffebee

会话状态管理

代码解释器维护一个持久的执行会话，这意味着在会话中定义的变量和函数可以在后续的代码调用中被引用：

# 第一次调用：定义变量
bot.run([{'role': 'user', 'content': '定义数据 data = [1, 2, 3, 4, 5]'}])

# 第二次调用：使用之前定义的变量
bot.run([{'role': 'user', 'content': '计算 data 的平均值'}])

这种状态保持能力使得复杂的多步骤数据处理任务得以实现。

输出格式

代码解释器支持多种输出格式，能够呈现不同类型的结果：

输出格式化器会自动检测输出内容并选择最合适的展示方式。对于图片输出，系统会将其转换为可访问的 URL 或 base64 编码的 data URI。

安全考虑

沙箱隔离

代码解释器在 Docker 容器中执行代码，提供了一定程度的安全隔离。然而，需要注意以下限制：

• 容器挂载：默认情况下，容器会挂载工作目录，需要确保敏感文件不被意外访问
• 网络访问：容器内的代码可能具有网络访问能力
• 资源限制：系统提供了基本的资源限制机制，但不应完全依赖其进行安全防护

使用建议

1. 不要在生产环境中直接暴露代码解释器接口
2. 对用户输入进行必要的验证和过滤
3. 设置合理的超时和资源限制
4. 定期更新容器镜像以获取安全补丁
5. 监控代码执行日志以便追踪异常行为

依赖要求

运行时依赖

安装方式

# 基础安装（不含代码解释器依赖）
pip install qwen-agent

# 完整安装（含代码解释器支持）
pip install qwen-agent[code_interpreter]

# 从源码安装
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./[code_interpreter]

社区相关讨论

在 Qwen-Agent 的社区中，关于代码解释器功能的讨论主要集中在以下几个方面：

集成与部署：Issue #609 中有用户提出希望将 Agent 发布为 API 服务的需求，这涉及到代码解释器在无头（headless）环境中的部署问题。当前代码解释器依赖 Docker 环境，在某些部署场景下可能需要额外的配置。

功能扩展：社区中有用户建议增加无沙箱模式（参考 Issue #698），这反映了用户对于代码解释器灵活性的需求。框架正在考虑提供更易于配置的选项，以满足不同安全级别的使用场景。

扩展阅读

• Qwen-Agent 官方文档
• Jupyter 协议文档
• Docker 容器安全最佳实践

概述

MCP（Model Context Protocol）协议集成是 Qwen-Agent 框架提供的一项重要功能，它允许 Agent 通过标准化的 MCP 协议与外部工具和服务进行交互。MCP 协议为大型语言模型提供了一个统一的接口，用于调用各种外部工具和数据源，从而扩展 Agent 的能力范围。

在 Qwen-Agent 中，MCP 集成通过 MCPToolset 类实现，该类封装了与 MCP 服务器的通信逻辑，支持函数调用、上下文管理和自动重连等核心功能。开发者可以轻松地将现有的 MCP 工具接入到 Qwen-Agent 系统中，构建功能强大的智能 Agent 应用。

安装要求

MCP 支持模块安装

要使用 MCP 协议集成功能，需要在安装 Qwen-Agent 时包含 MCP 相关依赖。可以通过以下方式安装：

# 方式一：使用 pip 安装带 MCP 支持的版本
pip install qwen-agent[mcp]

# 方式二：从源码安装
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./[mcp]

核心架构

MCPToolset 组件

MCPToolset 是 MCP 协议集成的核心组件，它负责管理与 MCP 服务器的连接、工具调用和响应处理。下图展示了 MCPToolset 的基本架构：

graph TD
    A[Agent] --> B[MCPToolset]
    B --> C[MCP 服务器]
    C --> D[外部工具/数据源]
    
    B --> E[连接管理]
    B --> F[工具注册]
    B --> G[请求处理]
    B --> H[响应解析]
    
    E --> I[SSE 连接]
    E --> J[自动重连]
    G --> K[超时控制]

核心类结构

使用方法

基本使用流程

使用 MCP 协议集成的典型流程如下：

graph LR
    A[创建 MCPToolset] --> B[注册 MCP 服务器地址]
    B --> C[初始化连接]
    C --> D[获取可用工具列表]
    D --> E[Agent 调用工具]
    E --> F[处理工具响应]
    F --> G[返回结果给用户]

SQLite 示例：MCP 工具集成

以下示例展示了如何使用 assistant_mcp_sqlite_bot.py 中定义的 MCP 工具进行数据库查询：

from qwen_agent.agents import Assistant
from qwen_agent.tools.mcp_manager import MCPToolset

# 初始化 MCP 工具集
mcp_tools = MCPToolset(
    server_address="http://localhost:8000/mcp",
    tool_names=["sqlite_query", "sqlite_execute"]
)

# 创建 Agent 并注册 MCP 工具
bot = Assistant(
    llm={
        "model": "qwen-plus",
        "api_key": os.getenv("DASHSCOPE_API_KEY"),
    },
    tools=[mcp_tools]
)

# 与 Agent 对话，自动调用 MCP 工具
messages = [{"role": "user", "content": "查询数据库中所有用户的订单数量"}]
response = bot.run(messages)

MCP 服务器配置

在创建 MCPToolset 时，可以通过以下参数进行配置：

高级配置

SSE 连接超时控制

MCP 协议使用 Server-Sent Events（SSE）进行通信，Qwen-Agent 提供了 sse_read_timeout 参数来控制读取超时时间。在 v0.0.26 及以上版本中，可以设置较长的超时时间以支持长时间运行的任务：

mcp_tools = MCPToolset(
    server_address="http://localhost:8000/mcp",
    sse_read_timeout=300,  # 设置 5 分钟超时
    auto_reconnect=True     # 启用自动重连
)

自动重连机制

框架内置了自动重连功能，当 MCP 连接意外断开时，会自动尝试重新建立连接。这一功能在处理不稳定网络环境或长时间运行的任务时尤为重要：

sequenceDiagram
    participant Agent
    participant MCPToolset
    participant MCPServer
    
    MCPToolset->>MCPServer: 建立 SSE 连接
    MCPServer-->>MCPToolset: 连接成功
    Agent->>MCPToolset: 调用工具
    MCPToolset->>MCPServer: 发送请求
    MCPServer-->>MCPToolset: 返回响应
    
    Note over MCPToolset,MCPServer: 连接断开
    MCPToolset->>MCPToolset: 检测连接断开
    MCPToolset->>MCPServer: 自动重连
    MCPServer-->>MCPToolset: 重连成功

工具过滤注册

当 MCP 服务器提供多个工具时，可以使用 tool_names 参数选择性地注册部分工具：

# 只注册特定的工具
mcp_tools = MCPToolset(
    server_address="http://localhost:8000/mcp",
    tool_names=["read_file", "write_file"]  # 只注册文件操作工具
)

与 Agent 集成

注册到 Assistant

MCPToolset 可以与其他工具一起注册到 Assistant Agent 中：

from qwen_agent.agents import Assistant
from qwen_agent.tools.mcp_manager import MCPToolset
from qwen_agent.tools import BaseTool

# 创建 MCP 工具集
mcp_tools = MCPToolset(
    server_address="http://localhost:8000/mcp"
)

# 创建其他自定义工具
class MyCustomTool(BaseTool):
    name = "my_custom_tool"
    description = "一个自定义工具"
    
    def call(self, params, timeout=None, **kwargs):
        # 实现工具逻辑
        return {"result": "success"}

# 组合多个工具
all_tools = [mcp_tools, MyCustomTool()]

# 创建 Agent
bot = Assistant(
    llm={"model": "qwen-plus"},
    tools=all_tools
)

工具调用流程

当用户提出请求时，Agent 会自动判断是否需要调用 MCP 工具：

graph TD
    A[用户输入] --> B[Agent 分析意图]
    B --> C{需要调用工具?}
    C -->|是| D[选择合适工具]
    C -->|否| E[直接生成回复]
    D --> F{是 MCP 工具?}
    F -->|是| G[通过 MCPToolset 调用]
    F -->|否| H[直接调用工具]
    G --> I[MCP 服务器处理]
    H --> J[获取结果]
    I --> K[返回结果]
    K --> J
    J --> L[Agent 生成最终回复]
    E --> L

常见问题与解决方案

连接超时问题

如果遇到连接超时问题，可以尝试以下方法：

1. 增加 sse_read_timeout 参数值
2. 检查 MCP 服务器是否正常运行
3. 确保网络连接稳定

工具未找到错误

如果提示工具未找到，请检查：

1. 工具名称是否正确（区分大小写）
2. MCP 服务器是否已启动并可用
3. tool_names 参数是否正确设置

自动重连失败

当自动重连多次失败时，建议：

1. 检查 MCP 服务器状态
2. 手动重启 MCP 服务器
3. 增加重连间隔时间

最佳实践

生产环境部署

在生产环境中部署 MCP 集成时，建议：

1. 使用 HTTPS 加密通信
2. 配置合理的超时时间
3. 实现连接状态的监控和告警
4. 考虑使用连接池管理多个 MCP 连接

性能优化

• 按需注册工具：避免注册不必要的工具，减少上下文开销
• 合理设置超时：平衡响应时间和资源占用
• 批量操作：对于支持批处理的 MCP 工具，尽量批量调用

相关资源

• 官方示例：assistant_mcp_sqlite_bot.py
• Qwen-Agent 文档首页
• MCP 协议规范

概述

Qwen-Agent 提供了两套针对超长文档问答场景的解决方案，旨在帮助开发者高效处理包含百万级 Token 的超大文档。这两套方案分别在速度与成本之间取得了不同的平衡：

资料来源：examples/assistant_rag.py:1-50

Pitfall Log / 踩坑日志

项目：QwenLM/Qwen-Agent

摘要：发现 9 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Security: Unsandboxed exec()/eval() in PythonExecutor with trivially bypassable filter。

1. 安全/权限坑 · 来源证据：Security: Unsandboxed exec()/eval() in PythonExecutor with trivially bypassable filter

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Unsandboxed exec()/eval() in PythonExecutor with trivially bypassable filter
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7d5e82403e6949e0bd07e5969ad25506 | https://github.com/QwenLM/Qwen-Agent/issues/866 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：coder.qwen.ai "Publish to GitHub" fail,s

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：coder.qwen.ai "Publish to GitHub" fail,s
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c33922a5c96145f790509151aad00dab | https://github.com/QwenLM/Qwen-Agent/issues/783 | 来源类型 github_issue 暴露的待验证使用条件。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | README/documentation is current enough for a first validation pass.

4. 运行坑 · 来源证据：Qwen3.5是否支持image_zoom_in_tool

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Qwen3.5是否支持image_zoom_in_tool
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_11290573df78457d94c7237d599c3cf5 | https://github.com/QwenLM/Qwen-Agent/issues/879 | 来源类型 github_issue 暴露的待验证使用条件。

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | last_activity_observed missing

6. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | no_demo; severity=medium

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_c108f7398a1c4fdc998a669640a849ed | https://github.com/QwenLM/Qwen-Agent#readme | release_recency=unknown