qwen-native-agents

Гайд и навык для того, чтобы строить и промптить агентов под модели семейства Qwen3.x на их родном диалекте — так, как это делает сама Alibaba.

Скачай папку, дай её своему агенту (Claude Code, Cursor, любой LLM-обвязке) — и он начнёт собирать Qwen-агентов правильно: с нужным форматом tool-calling, тегами, thinking-режимом и системным промптом, под которые модель обучалась.

---

Главный тезис

Qwen3.x обучались в связке с фреймворками Alibaba (qwen-code и Qwen-Agent). Форматы вызова инструментов, thinking-режим, структура системного промпта — не абстрактные «best practices», а конкретные конвенции, зашитые в веса во время обучения.

Исследование Андрея Иванова (NLP-инженер R&D red_mad_robot) показало это эмпирически: если инвертировать директивы оригинального системного промпта Qwen Code, Qwen3.6-35b-a3b держится за свои привычки сильнее, чем контрольная модель (gpt-oss-120b):

Вывод для практики: не переучивай модель — говори на её родном диалекте. Чем ближе твой агент к конвенциям qwen-code / Qwen-Agent, тем предсказуемее и надёжнее ведёт себя Qwen. Этот репозиторий — извлечённый из исходников «родной диалект» плюс правила, как ему следовать.

---

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

Человеку: читай SKILL.md как краткую памятку, а references/ — как справочник по каждой теме.

Агенту (Claude Code и совместимые): файл SKILL.md имеет frontmatter и подхватывается как навык. Положи папку в ~/.claude/skills/ (или укажи путь) — агент загрузит её, когда задача касается построения/промптинга Qwen-агента.

Любой другой LLM-обвязке: скорми SKILL.md + нужный файл из references/ как контекст.

---

Что внутри

---

Бенчмарк

Воспроизведение swing-теста на API neuraldeep.ru: 6 директив × 5 задач × 2 условия (baseline/inverted) × 3 модели — 180 запросов, 0 ошибок. Меряется финальный content, thinking выключен. Код и сырые данные — в benchmark/, полный отчёт с оговорками — benchmark/REPORT.md.

swing = |mean(inverted) − mean(baseline)| — насколько модель меняет поведение при инверсии директивы. Больше swing → слушает системный промпт; меньше → держится за трейн-привычку.

Средние значения метрики (baseline → inverted)

Swing и во сколько раз контроль реагирует сильнее qwen

⚠️ run_tests: qwen и gemma в single-turn вообще не звали shell-тул проактивно → сравнение для них вырождено.

Что показал бенчмарк

• ✅ Привычка «без комментариев» реальна и самая крепкая. Под директиву «комментируй каждую строку» контроли раздули комментарии в ×2.3–2.5 сильнее, чем qwen. Направление совпадает с исследованием Андрея (у него ×26). Это единственная директива, где тезис воспроизвёлся чисто.
• ❌ На длине и markdown qwen слушается не хуже контролей — с выключенным thinking в одиночном запросе стиль легко перебивается. Широкая версия «Qwen держится за всё» здесь не подтвердилась.
• 🔍 Qwen в «голом» single-turn — слабый проактивный тул-caller (не вызвал shell-тул там, где gpt-oss вызвал). Ему нужна более явная инструкция и агент-цикл — ровно то, что даёт родная обвязка qwen-code.

Полный прогон: что подходит каждой модели

Расширенный бенчмарк — 3 модели × 2 конфигурации рассуждения (think_off/think_on) × 4 объективно-проверяемые оси + swing. Агрегировано по 3 независимым прогонам — 1890 записей, 0 ошибок (n=9 повторов на задачу). Код: bench_full.py · analyze_full.py · сырые прогоны: benchmark/runs/ · полный отчёт: REPORT_FULL.md.

Скоркарта (% успеха, лучшая конфигурация каждой модели)

Главное — режим рассуждения зависит от модели

Кто в чём лучший: следование инструкциям — gpt-oss (94%); tool-call, JSON, агент-цикл — qwen3.6 (100%, в режиме thinking on).

v2: сложные задачи + сравнение диалектов tool-calling

Второй бенчмарк проверяет сам тезис скилла («родной диалект лучше») и поднимает сложность. 3 прогона, 1296 записей, 3 ошибки (0.2%). Каждая модель — на своём оптимуме thinking. Код: bench_v2.py · отчёт: REPORT_V2.md · прогоны: benchmark/runs_v2/.

Какой формат tool-calling лучше (% верных вызовов, 8 задач × 6 тулов-дистракторов)

Скоркарта усложнённых задач (% успеха)

Что это значит (честная калибровка тезиса)

• Сильная версия тезиса не подтвердилась: на уровне API нативные OpenAI-tools работают у qwen практически так же (99% vs 100%), как «родной» NOUS. Современный сервинг (vLLM/LiteLLM) уже нормализует диалект под капотом — прикладному разработчику не нужно вручную городить ``.
• Маржинальные предпочтения по моделям всё же есть: gpt-oss заметно лучше в coder_xml (+6 п.п.), qwen/gemma — безразличны к формату.
• «Родной диалект» важен на уровне обучения/сервинга, а не приложения. Знать его надо (для отладки, для vLLM-конфига, для raw-инференса), но не обязательно применять в OpenAI-совместимом вызове.
• Даже усложнённые задачи упёрлись в потолок (JSON/agent ~100%) — модели сильные; различает их сейчас только строгое следование инструкциям.

Полезен ли скилл? (вывод по итогам бенчмарка)

Да — но не по той причине, что «Qwen не слушается». Бенчмарк уточнил ценность:

1. Ядро скилла — фактический «родной диалект» — верно независимо от swing-теста. Форматы tool-calling (NOUS/coder/vl), теги, enable_thinking по бэкендам, структура системного промпта — это извлечённые из исходников факты, а не гипотезы. Мимо них Qwen-агент просто не поедет. Это польза №1.
2. Подтверждённая привычка (комментарии) → конкретное практическое правило: не воюй с «без комментариев», иначе получишь дрейф. Скилл предупреждает об этом в 06-habits-and-antipatterns.md.
3. Находка про слабый проактивный tool-calling — сильнейший аргумент за скилл: Qwen раскрывается в родной обвязке, а в чистом API-вызове ведёт себя слабее контроля. Скилл ровно эту обвязку и воспроизводит.
4. Честная калибровка: тезис «держится за все привычки» переоценён для simple single-turn. Скилл стоит подавать как «собери агента на родном диалекте Qwen», а не «Qwen игнорирует инструкции» — и он это делает.

Итого: скилл полезен как фактический справочник по родному диалекту + агент-обвязке; «привычки» — важный, но узкий подраздел (сильнее всего — комментарии). Чтобы усилить доказательную часть — прогнать тест с thinking on и в реальном агент-цикле (см. TODO в отчёте).

Источники

Всё в этом репозитории извлечено из открытых исходников (с указанием путей file:line в каждом reference-файле):

• QwenLM/qwen-code — CLI-агент (форк Google Gemini CLI v0.8.2, разошёлся с апстримом с v0.1).
• QwenLM/Qwen-Agent — официальный агентный фреймворк Alibaba.
• Исследование: Андрей Иванов, R&D red_mad_robot — «Системный промпт против привычек Qwen».

Лицензия

MIT — см. LICENSE.