Qwen-Agent, часть 2: README на русском

От переводчика

Перевод README из репозитория QwenLM/Qwen-Agent (Apache-2.0, © 2023 The Qwen team, Alibaba Group). Картинки (логотип, график результатов на длинных документах) не копируем — ссылки на них даны текстом. Комментарии в коде переведены, сам код не менялся, кроме строк с примерами запросов. Наши пояснения — только в таких блоках. Путеводитель по устройству фреймворка — часть 1.

Ссылки оригинала: Qwen Chat (chat.qwen.ai) · Hugging Face · ModelScope · блог · документация · бенчмарк · WeChat · Discord.

Qwen-Agent — фреймворк для разработки приложений на основе LLM, опирающийся на способности Qwen следовать инструкциям, пользоваться инструментами, планировать и запоминать. В комплекте — примеры приложений: браузерный помощник (Browser Assistant), интерпретатор кода (Code Interpreter) и настраиваемый помощник (Custom Assistant). Сейчас Qwen-Agent работает бэкендом Qwen Chat.

Новости

• 16 февраля 2026: открыта Qwen3.5. Примеры использования — в демо агента Qwen3.5.
• 27 января 2026: открыт бенчмарк оценки агентов DeepPlanning и добавлена документация Qwen-Agent.
• 23 сентября 2025: добавлено демо вызова инструментов Qwen3-VL с инструментами увеличения фрагмента, поиска картинок и поиска в интернете.
• 23 июля 2025: добавлено демо вызова инструментов Qwen3-Coder; добавлена поддержка нативного интерфейса вызова инструментов API — например, встроенного разбора вызовов в vLLM.
• 1 мая 2025: добавлено демо вызова инструментов Qwen3 и кукбуки по MCP.
• 18 марта 2025: поддержка поля reasoning_content; изменён шаблон вызова функций по умолчанию — он подходит для общих моделей Qwen2.5 и QwQ-32B. Если нужен старый шаблон, смотрите, как передать параметры, в примере.
• 7 марта 2025: добавлено демо вызова инструментов QwQ-32B. Поддерживаются параллельные, многошаговые и многоходовые вызовы.
• 3 декабря 2024: графический интерфейс переведён на Gradio 5. Внимание: для интерфейса нужен Python 3.10 или новее.
• 18 сентября 2024: добавлено демо Qwen2.5-Math с рассуждениями, в которые встроен вызов инструментов (Tool-Integrated Reasoning). Внимание: исполнитель Python не изолирован в песочнице и предназначен только для локальных опытов, не для продакшена.

Начало работы

Установка

• Стабильная версия из PyPI:

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# Или `pip install -U qwen-agent` для минимального набора зависимостей.
# Необязательные зависимости в квадратных скобках:
#   [gui] — графический интерфейс на Gradio;
#   [rag] — поддержка RAG;
#   [code_interpreter] — интерпретатор кода;
#   [mcp] — поддержка MCP.

• Или последняя версия для разработки из исходников:

git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"
# Или `pip install -e ./` для минимального набора зависимостей.

Подготовка: сервис модели

Можно пользоваться сервисом моделей облака Alibaba Cloud DashScope или развернуть свой сервис на открытых моделях Qwen.

• Если вы выбрали DashScope, задайте переменную окружения DASHSCOPE_API_KEY — ваш личный ключ DashScope API.
• Если хотите развернуть свой сервис, следуйте инструкциям в README Qwen2 по развёртыванию OpenAI-совместимого API-сервиса. В частности, смотрите раздел vLLM для высокопроизводительного развёртывания на GPU или раздел Ollama для локального развёртывания на CPU (+GPU).

Для моделей QwQ и Qwen3 рекомендуется не добавлять параметры --enable-auto-tool-choice и --tool-call-parser hermes: Qwen-Agent сам разбирает вызовы инструментов в выводе vLLM. Для Qwen3-Coder рекомендуется включить оба параметра, пользоваться встроенным разбором вызовов vLLM и сочетать это с параметром use_raw_api (как передать).

От переводчика

Ссылки на README Qwen2 в оригинале устарели; актуальные команды развёртывания для Qwen3 — в нашем пересказе документации Qwen, часть 2.

Разработка своего агента

Qwen-Agent предлагает атомарные компоненты — модели (наследуются от class BaseChatModel и поддерживают вызов функций) и инструменты (наследуются от class BaseTool), — а также компоненты верхнего уровня, например агенты (наследники class Agent).

Пример ниже показывает, как создать агента, который умеет читать PDF-файлы и пользоваться инструментами, в том числе собственным:

import pprint
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.utils.output_beautify import typewriter_print


# Шаг 1 (необязательный): добавляем свой инструмент с именем `my_image_gen`.
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    # `description` сообщает агенту, что делает инструмент.
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    # `parameters` сообщают агенту, какие входные параметры есть у инструмента.
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        # `params` — аргументы, которые сгенерировал агент на основе LLM.
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json5.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)


# Шаг 2: настраиваем используемую модель.
llm_cfg = {
    # Сервис моделей DashScope:
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',
    # Если 'api_key' здесь не задан, будет взята переменная окружения `DASHSCOPE_API_KEY`.

    # Сервис моделей, совместимый с OpenAI API, например vLLM или Ollama:
    # 'model': 'Qwen2.5-7B-Instruct',
    # 'model_server': 'http://localhost:8000/v1',  # base_url, он же api_base
    # 'api_key': 'EMPTY',

    # (Необязательно) гиперпараметры генерации:
    'generate_cfg': {
        'top_p': 0.8
    }
}

# Шаг 3: создаём агента. Для примера возьмём агента `Assistant`, который умеет пользоваться инструментами и читать файлы.
system_instruction = '''After receiving the user's request, you should:
- first draw an image and obtain the image url,
- then run code `request.get(image_url)` to download the image,
- and finally select an image operation from the given document to process the image.
Please show the image using `plt.show()`.'''
tools = ['my_image_gen', 'code_interpreter']  # `code_interpreter` — встроенный инструмент для выполнения кода. Настройка — в разделе «Вопросы и ответы».
files = ['./examples/resource/doc.pdf']  # Даём боту прочитать PDF-файл.
bot = Assistant(llm=llm_cfg,
                system_message=system_instruction,
                function_list=tools,
                files=files)

# Шаг 4: запускаем агента как чат-бота.
messages = []  # Здесь хранится история диалога.
while True:
    # Например, введите запрос «нарисуй собаку и поверни её на 90 градусов».
    query = input('\nuser query: ')
    # Добавляем запрос пользователя в историю.
    messages.append({'role': 'user', 'content': query})
    response = []
    response_plain_text = ''
    print('bot response:')
    for response in bot.run(messages=messages):
        # Потоковый вывод.
        response_plain_text = typewriter_print(response, response_plain_text)
    # Добавляем ответы бота в историю.
    messages.extend(response)

От переводчика

Системная инструкция переводится так: «Получив запрос пользователя, ты должен: сначала нарисовать картинку и получить её адрес; затем выполнить код request.get(image_url), чтобы скачать картинку; и наконец выбрать из данного документа операцию над изображением и применить её. Показывай картинку через plt.show()». Описания инструмента оставлены по-английски, как в оригинале: модель понимает и русские описания, но для примеров из репозитория лучше не менять текст, на котором их проверяли.

Помимо встроенных агентов вроде class Assistant можно писать свою реализацию агента, наследуясь от class Agent.

Фреймворк также даёт удобный графический интерфейс и позволяет быстро развернуть Gradio-демо для агентов. Например, для агента из примера выше демо запускается так:

from qwen_agent.gui import WebUI
WebUI(bot).run()  # bot — агент, определённый в коде выше; для краткости определение не повторяем.

Теперь с агентом можно общаться в веб-интерфейсе. Больше примеров — в папке examples.

Вопросы и ответы

Как пользоваться интерпретатором кода?

Мы реализовали интерпретатор кода на основе локальных Docker-контейнеров. Можно включить агенту встроенный инструмент code_interpreter, и тот будет сам писать код под конкретную задачу, безопасно выполнять его в изолированной песочнице и возвращать результаты.

⚠️ Внимание: перед использованием инструмента убедитесь, что Docker установлен и запущен в вашей операционной системе. Первая сборка образа контейнера займёт время, зависящее от скорости сети. Как установить и настроить Docker — в официальной документации.

Как пользоваться MCP?

Выберите нужные инструменты на сайте открытых MCP-серверов и настройте соответствующее окружение.

Пример формата вызова MCP:

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

Подробнее — в примере использования MCP.

Для запуска этого примера нужны:

# Node.js (скачайте и установите последнюю версию с официального сайта Node.js)
# uv 0.4.18 или новее (проверьте командой uv --version)
# Git (проверьте командой git --version)
# SQLite (проверьте командой sqlite3 --version)

# Пользователи macOS могут установить их через Homebrew:
brew install uv git sqlite3

# Пользователи Windows — через winget:
winget install --id=astral-sh.uv -e
winget install git.git sqlite.sqlite

От переводчика: Linux

На Ubuntu того же добиться можно так: sudo apt install nodejs npm git sqlite3 и curl -LsSf https://astral.sh/uv/install.sh | sh для uv.

Есть ли вызов функций (он же вызов инструментов)?

Да. Классы моделей поддерживают вызов функций. Кроме того, на вызове функций построены некоторые классы агентов, например FnCallAgent и ReActChat.

Текущий шаблон вызова инструментов по умолчанию нативно поддерживает параллельные вызовы функций.

Как передать агенту параметры модели?

llm_cfg = {
    # Имя используемой модели:
    'model': 'qwen3-32b',
    # Используемый сервис моделей:
    'model_type': 'qwen_dashscope',
    # Если 'api_key' здесь не задан, по умолчанию читается переменная окружения `DASHSCOPE_API_KEY`:
    'api_key': 'YOUR_DASHSCOPE_API_KEY',

    # Сервис моделей, совместимый с OpenAI API, например vLLM или Ollama:
    # 'model': 'qwen3-32b',
    # 'model_server': 'http://localhost:8000/v1',  # base_url, он же api_base
    # 'api_key': 'EMPTY',

    # (Необязательно) гиперпараметры модели:
    'generate_cfg': {
        # Этот параметр влияет на логику разбора вызовов инструментов. По умолчанию False:
          # True — когда content имеет вид `<think>это рассуждение</think>это ответ`;
          # False — когда ответ состоит из reasoning_content и content.
        # 'thought_in_content': True,

        # Шаблон вызова инструментов: по умолчанию nous (рекомендуется для qwen3):
        # 'fncall_prompt_type': 'nous'

        # Максимальная длина входа; сообщения длиннее будут обрезаны. Настройте под API модели:
        # 'max_input_tokens': 58000

        # Параметры, которые передаются в API модели как есть (top_p, enable_thinking и т. п.) — по спецификации API:
        # 'top_p': 0.8

        # Использовать нативный интерфейс вызова инструментов API:
        # 'use_raw_api': True,
    }
}

Как отвечать на вопросы по сверхдлинным документам — до 1 млн токенов?

Мы выпустили быстрое решение на RAG и дорогого, но сильного агента для вопросов по сверхдлинным документам. На двух сложных бенчмарках они превзошли модели с нативным длинным контекстом, оставаясь при этом эффективнее, и безошибочно прошли стресс-тест «иголка в стоге сена» с одной иголкой в контексте на 1 млн токенов. Технические подробности — в блоге.

(В оригинале здесь график результатов на длинных документах: ссылка на изображение.)

Приложение: BrowserQwen

BrowserQwen — браузерный помощник на основе Qwen-Agent. Подробности — в его документации.

Отказ от ответственности

Интерпретатор кода на основе Docker-контейнера подключает только указанную рабочую папку и реализует базовую изоляцию в песочнице, но в продакшене им всё равно нужно пользоваться с осторожностью.