Skip to main content

​
Overview

The BasicDocQA agent (aliased as DocQAAgent) is specialized for document question-answering tasks. It extends the Assistant agent with optimized prompts and workflows for retrieving and answering questions from documents.
DocQAAgent is the default solution for long document question answering in Qwen-Agent. The actual implementation may change with releases to incorporate improvements.

​
Key Features

Multi-format Support

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

Precise Retrieval

Locate specific sections and details within documents

Optimized Prompts

Specialized prompts for clear, organized answers

Context Management

Automatically manage document context and references

​
Constructor

from qwen_agent.agents import DocQAAgent

agent = DocQAAgent(
    function_list=[],
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    system_message='You are a helpful document QA assistant.',
    name='DocQA',
    description='Document question answering agent',
    files=['./document.pdf', './report.docx'],
    rag_cfg={'lang': 'en', 'max_ref_token': 4000}
)

​
Parameters

​
function_list
list
default:"[]"
Optional list of additional tools. Usually empty for pure document QA.
​
llm
dict | BaseChatModel
LLM configuration or model object.
​
system_message
str
System message for the agent’s behavior.
​
name
str
default:"Basic DocQA"
Agent name.
​
description
str
Agent description. Used for routing in multi-agent setups.
​
files
list
List of document paths or URLs to load.
​
rag_cfg
dict
RAG configuration:
  • lang: ‘en’ or ‘zh’
  • max_ref_token: Maximum tokens for retrieved context
  • parser_page_size: Pages per chunk
  • search_method: ‘keywords’, ‘vector’, ‘hybrid’, ‘front_page’

​
Basic Usage

1

Initialize with Documents

from qwen_agent.agents import DocQAAgent

agent = DocQAAgent(
    llm={
        'model': 'qwen-max-latest',
        'model_type': 'qwen_dashscope'
    },
    files=['./research_paper.pdf']
)
2

Ask Questions

messages = [{
    'role': 'user',
    'content': 'What is the main conclusion of this paper?'
}]

for response in agent.run(messages=messages):
    print(response[-1]['content'])

​
Single Document QA

from qwen_agent.agents import DocQAAgent

# Load a single PDF document
agent = DocQAAgent(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    files=['./technical_manual.pdf'],
    rag_cfg={'lang': 'en', 'search_method': 'hybrid'}
)

# Ask specific questions
questions = [
    'What is covered in Section 3?',
    'Explain Table 2',
    'What are the system requirements?'
]

for question in questions:
    messages = [{'role': 'user', 'content': question}]
    for response in agent.run(messages=messages):
        pass
    print(f"Q: {question}")
    print(f"A: {response[-1]['content']}\n")

​
Multiple Documents QA

from qwen_agent.agents import DocQAAgent

# Load multiple documents
agent = DocQAAgent(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    files=[
        './report_q1.pdf',
        './report_q2.pdf',
        './report_q3.pdf',
        './report_q4.pdf'
    ],
    rag_cfg={
        'lang': 'en',
        'max_ref_token': 8000,  # More context for multiple docs
        'search_method': 'hybrid'
    }
)

messages = [{
    'role': 'user',
    'content': 'Compare the revenue trends across all four quarterly reports'
}]

for response in agent.run(messages=messages):
    print(response[-1]['content'])

​
Web Documents

DocQA can also process documents from URLs: 
from qwen_agent.agents import DocQAAgent

agent = DocQAAgent(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    files=[
        'https://example.com/whitepaper.pdf',
        'https://docs.example.com/api-guide.html'
    ]
)

messages = [{'role': 'user', 'content': 'Summarize the API authentication process'}]

for response in agent.run(messages=messages):
    print(response[-1]['content'])

​
Multi-turn Conversations

from qwen_agent.agents import DocQAAgent

agent = DocQAAgent(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    files=['./user_guide.pdf']
)

messages = []

# First question
messages.append({'role': 'user', 'content': 'How do I install the software?'})
for response in agent.run(messages=messages):
    pass
messages.extend(response)

# Follow-up question
messages.append({'role': 'user', 'content': 'What are the system requirements for that?'})
for response in agent.run(messages=messages):
    pass
messages.extend(response)

print(messages[-1]['content'])

​
RAG Configuration Options

​
Search Methods

# Keyword search - fast, good for exact matches
rag_cfg = {'search_method': 'keywords'}

# Vector search - semantic similarity
rag_cfg = {'search_method': 'vector'}

# Hybrid - combines keyword and vector (recommended)
rag_cfg = {'search_method': 'hybrid'}

# Front page - prioritizes first pages
rag_cfg = {'search_method': 'front_page'}

​
Context Management

rag_cfg = {
    'lang': 'en',
    'max_ref_token': 8000,  # Maximum retrieved context
    'parser_page_size': 500,  # Tokens per chunk
    'rag_keygen_llm': {  # Separate LLM for keyword extraction
        'model': 'qwen-turbo',
        'model_type': 'qwen_dashscope'
    }
}

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

​
Best Practices

  • Use clean, well-formatted documents for best results
  • Remove unnecessary headers/footers that may confuse retrieval
  • For scanned PDFs, use OCR first
  • Keep documents focused on specific topics
  • Be specific in your questions
  • Reference section numbers or headings when known
  • Ask one concept at a time for clearer answers
  • Use follow-up questions for complex topics
  • Use hybrid search for best accuracy
  • Adjust max_ref_token based on document complexity
  • Set appropriate parser_page_size for document structure
  • For very large documents (>1M tokens), consider ParallelDocQA

​
When to Use ParallelDocQA

For extremely large documents or document collections: 
from qwen_agent.agents import ParallelDocQA

# For documents with 1M+ tokens
agent = ParallelDocQA(
    llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
    files=['./massive_dataset.pdf']
)
See ParallelDocQA documentation for details.

​
Supported File Formats

  • PDF: .pdf
  • Microsoft Word: .docx, .doc
  • Microsoft PowerPoint: .pptx, .ppt
  • Excel: .xlsx, .xls
  • HTML: .html, .htm
  • Text: .txt, .md

RAG Guide

Deep dive into RAG implementation

Long Document QA

Handle very large documents

Assistant Agent

RAG + function calling

API Reference

Complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us