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):

| Директива (перевёрнута) | Реакция контроля | Реакция Qwen3.6 | |---|---|---| | Длина ответа | ×4 сильнее | слабая | | Комментарии в коде | ×26 больше | не изменилась | | Markdown-разметка | ×1.7 меньше | не изменилась |

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

---

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

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

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

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

---

Что внутри

| Файл | О чём | |---|---| | SKILL.md | Ядро: когда применять, 10 правил, чек-лист | | references/01-system-prompt.md | Как писать системный промпт: структура, тон, «привычки» | | references/02-tools.md | Нейминг инструментов, описания, JSON-schema параметров | | references/03-tool-calling.md | Форматы function-calling (NOUS, ✿, coder-XML, vl-JSON), chat template, стоп-слова | | references/04-thinking.md | Thinking-режим: <think>, reasoning_content, enable_thinking по бэкендам | | references/05-tags-and-markup.md | Теги внутри промптов: <example>, <tools>, <tool_response>, <system-reminder>, компрессия | | references/06-habits-and-antipatterns.md | Тезис исследования: за что модель держится и что НЕ навязывать | | examples/ | Готовые образцы: системный промпт, определение тула, минимальный агент |

---

Бенчмарк

Воспроизведение 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)

| Директива | Метрика | qwen3.6-35b-a3b | gpt-oss-120b | gemma-4-31b | |---|---|---|---|---| | length | слов | 10 → 1116 | 18 → 1041 | 8 → 556 | | comments | комм.строк | 1 → 10 | 0 → 22 | 0 → 23 | | markdown | md-маркеров | 89 → 1 | 87 → 12 | 77 → 0 | | run_tests | доля | 0 → 0 ⚠️ | 1.0 → 0.2 | 0 → 0 ⚠️ | | parallel_tools | tool-calls | 3 → 1 | 1 → 1 | 3 → 1 | | preamble | доля | 1 → 0 | 0 → 0 | 1 → 0 |

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

| Директива | qwen | gpt-oss | gemma | gpt-oss/qwen | gemma/qwen | |---|---|---|---|---|---| | length | 1106 | 1023 | 548 | ×0.9 | ×0.5 | | comments | 9.4 | 21.6 | 23.2 | ×2.3 | ×2.5 | | markdown | 88 | 75 | 77 | ×0.9 | ×0.9 | | run_tests | 0 ⚠️ | 0.8 | 0 ⚠️ | — | — | | parallel_tools | 2.0 | 0.0 | 2.0 | ×0.0 | ×1.0 | | preamble | 1.0 | 0.0 | 1.0 | ×0.0 | ×1.0 |

⚠️ 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.

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

| Ось | qwen3.6-35b-a3b | gpt-oss-120b | gemma-4-31b | |---|---|---|---| | Следование инструкциям | 85 (on) | 94 (off) | 83 | | Корректность tool-call | 100 (on) | 78 (off) | 100 | | Structured JSON | 100 | 100 | 100 | | Агент-цикл (task done) | 100 (on) | 100 (off) | 100 | | Средний скор | 96 (on) | 93 (off) | 96 |

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

| Модель | Оптимум | Что показал прогон (среднее по 3 запускам) | |---|---|---| | qwen3.6-35b-a3b | thinking ON | Резкий рост с рассуждениями: tool-call 75→100%, инструкции 69→85%, средний 86→96%. Без thinking Qwen недожимает — это ровно то, что даёт родная обвязка qwen-code. | | gpt-oss-120b | thinking OFF (low effort) | High effort вредит: tool-call 78→61%, агент 100→94%, инструкции 94→83%. Силён в следовании инструкциям, но хуже всех в корректности tool-call. | | gemma-4-31b | (тумблера нет) | Ровный универсал ~96%, tool-call и JSON на 100%, слабее в строгих инструкциях (83%). |

Кто в чём лучший: следование инструкциям — 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 тулов-дистракторов)

| Модель | native (OpenAI tools) | nous (<tool_call>{json}) | coder_xml (<function=..>) | лучший | |---|---|---|---|---| | qwen3.6-35b-a3b | 99 | 100 | 100 | nous (+1) | | gpt-oss-120b | 90 | 90 | 96 | coder_xml (+6) | | gemma-4-31b | 100 | 100 | 100 | native |

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

| Ось | qwen3.6 | gpt-oss | gemma | |---|---|---|---| | Следование инструкциям (12 задач) | 91 | 93 | 94 | | Structured JSON (вложенность/массивы/enum) | 100 | 100 | 98 | | Агент-цикл (мультифайл/ошибки/дистракторы, ср. 2.7–3.0 хода) | 100 | 100 | 100 |

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

• Сильная версия тезиса не подтвердилась: на уровне API нативные OpenAI-tools работают у qwen практически так же (99% vs 100%), как «родной» NOUS. Современный сервинг (vLLM/LiteLLM) уже нормализует диалект под капотом — прикладному разработчику не нужно вручную городить <tool_call>.
• Маржинальные предпочтения по моделям всё же есть: 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.