Skip to main content

​
Overview

The Assistant agent is the most widely applicable agent in Qwen-Agent, combining retrieval-augmented generation (RAG) capabilities with function calling. It extends FnCallAgent and is perfect for building conversational AI applications that need to access documents and use tools.
The Assistant agent is used as the backend for Qwen Chat and has been battle-tested with millions of users.

​
Key Features

RAG Integration

Built-in document parsing and retrieval for question-answering over files

Function Calling

Native support for calling tools and external APIs

Multi-format Support

Process PDF, Word, PowerPoint, HTML, and text documents

Memory Management

Automatic conversation history and context management

​
Constructor

from qwen_agent.agents import Assistant

bot = Assistant(
    function_list=['code_interpreter', 'image_gen'],
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    system_message='You are a helpful assistant.',
    name='MyAssistant',
    description='A versatile AI assistant',
    files=['./document.pdf'],
    rag_cfg={'lang': 'en', 'max_ref_token': 4000}
)

​
Parameters

​
function_list
list
List of tools to enable. Can be tool names (strings), tool configurations (dicts), or tool objects.
​
llm
dict | BaseChatModel
LLM configuration or model object. Include model, model_type, and optionally api_key, model_server.
​
system_message
str
default:"You are a helpful assistant"
System message that defines the agent’s behavior and personality.
​
name
str
Agent name for identification in multi-agent scenarios.
​
description
str
Agent description for routing in multi-agent systems.
​
files
list
Initial list of document URLs or file paths to load into memory.
​
rag_cfg
dict
RAG configuration including:
  • lang: Language (‘en’ or ‘zh’)
  • max_ref_token: Maximum tokens for retrieved context
  • parser_page_size: Pages per document chunk
  • rag_keygen_llm: LLM for keyword generation
  • search_method: Search strategy (‘front_page’, ‘keywords’, ‘vector’, ‘hybrid’)

​
Basic Usage

1

Create an Assistant

Initialize the assistant with your desired tools and configuration:
from qwen_agent.agents import Assistant

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    'api_key': 'YOUR_API_KEY'
}

bot = Assistant(
    llm=llm_cfg,
    system_message='You are a helpful research assistant.',
    function_list=['code_interpreter'],
    files=['./research_paper.pdf']
)
2

Chat with the Assistant

Send messages and receive streaming responses:
messages = [{'role': 'user', 'content': 'Summarize the key findings in the paper'}]

for response in bot.run(messages=messages):
    print(response)

​
RAG Example

The Assistant automatically performs retrieval when documents are provided: 
from qwen_agent.agents import Assistant

# Initialize with documents
bot = Assistant(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    files=[
        './documents/report1.pdf',
        './documents/report2.docx',
        './documents/data.xlsx'
    ],
    rag_cfg={
        'lang': 'en',
        'max_ref_token': 4000,
        'search_method': 'hybrid'  # Use hybrid search for better retrieval
    }
)

# Ask questions about the documents
messages = [{
    'role': 'user',
    'content': 'What are the main conclusions across all three reports?'
}]

for response in bot.run(messages=messages):
    print(response)

​
Function Calling Example

Combine document QA with tool usage: 
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
import json5

# Define a custom tool
@register_tool('search_database')
class SearchDatabase(BaseTool):
    description = 'Search the product database for information'
    parameters = [{
        'name': 'query',
        'type': 'string',
        'description': 'Search query',
        'required': True
    }]
    
    def call(self, params: str, **kwargs) -> str:
        query = json5.loads(params)['query']
        # Your database search logic
        return json5.dumps({'results': [...]})

# Create assistant with both RAG and tools
bot = Assistant(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    function_list=['search_database', 'code_interpreter'],
    files=['./product_manual.pdf'],
    system_message='You are a product support assistant with access to manuals and databases.'
)

messages = [{
    'role': 'user',
    'content': 'Check the manual and database for product XYZ specifications'
}]

for response in bot.run(messages=messages):
    print(response)

​
GUI Integration

Quickly deploy with a web interface: 
from qwen_agent.agents import Assistant
from qwen_agent.gui import WebUI

bot = Assistant(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    function_list=['code_interpreter'],
    files=['./data.csv']
)

chatbot_config = {
    'prompt.suggestions': [
        'Analyze the data in the CSV file',
        'Create a visualization of the trends'
    ]
}

WebUI(bot, chatbot_config=chatbot_config).run()

​
Advanced Configuration

​
Custom RAG Settings

rag_cfg = {
    'lang': 'en',
    'max_ref_token': 8000,  # More context
    'parser_page_size': 1000,  # Smaller chunks
    'search_method': 'hybrid',  # Best of keyword + vector
    'rag_keygen_llm': {  # Separate LLM for keyword generation
        'model': 'qwen-turbo',
        'model_type': 'qwen_dashscope'
    }
}

bot = Assistant(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    files=['./large_document.pdf'],
    rag_cfg=rag_cfg
)

​
Multi-turn Conversations

messages = []

while True:
    user_input = input('You: ')
    messages.append({'role': 'user', 'content': user_input})
    
    response = []
    for response in bot.run(messages=messages):
        # Stream response
        pass
    
    # Add assistant responses to history
    messages.extend(response)
    print('Assistant:', response[-1]['content'])

​
Best Practices

  • Keep documents focused and relevant to avoid irrelevant retrievals
  • Use descriptive filenames for better source attribution
  • Pre-process documents to remove unnecessary content
  • Consider document size limits (very large documents should use ParallelDocQA)
  • Use hybrid search for best retrieval quality
  • Adjust max_ref_token based on your model’s context window
  • Set lang correctly for optimal chunking and keyword extraction
  • Use smaller parser_page_size for fine-grained retrieval
  • Only include tools that are relevant to your use case
  • Provide clear tool descriptions to help the agent choose correctly
  • Test tool combinations to ensure they work well together
  • Monitor tool usage patterns to optimize performance

RAG Guide

Learn more about retrieval-augmented generation

Custom Tools

Create your own tools for the Assistant

GUI Deployment

Deploy your Assistant with a web interface

API Reference

Complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us