qwen-native-agents

KO | EN

gitlite — search

#python #ai #typescript #llm #android #rust #deep-learning #java #nodejs #kubernetes #awesome-list #pytorch #security #ios

qwen-native-agents

(★ 39)

Build & prompt Qwen3.x agents in their native dialect — extracted from qwen-code & Qwen-Agent

qwen-native-agents Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# qwen-native-agents

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

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

---

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

Qwen3.x обучались **в связке** с фреймворками Alibaba ([qwen-code](https://github.com/QwenLM/qwen-code) и [Qwen-Agent](https://github.com/QwenLM/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`](./SKILL.md) как краткую памятку, а [`references/`](./references/) — как справочник по каждой теме.

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

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

---

## Что внутри

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

---

## Бенчмарк

Воспроизведение swing-теста на API [neuraldeep.ru](https://neuraldeep.ru): 6 директив × 5 задач × 2 условия (baseline/inverted) × 3 модели — 180 запросов, 0 ошибок. Меряется финальный `content`, thinking выключен. Код и сырые данные — в [`benchmark/`](./benchmark/), полный отчёт с оговорками — [`benchmark/REPORT.md`](./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`](./benchmark/bench_full.py) · [`analyze_full.py`](./benchmark/analyze_full.py) · сырые прогоны: [`benchmark/runs/`](./benchmark/runs/) · полный отчёт: [`REPORT_FULL.md`](./benchmark/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`](./benchmark/bench_v2.py) · отчёт: [`REPORT_V2.md`](./benchmark/REPORT_V2.md) · прогоны: [`benchmark/runs_v2/`](./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`](./references/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](https://github.com/QwenLM/qwen-code)** — CLI-агент (форк Google Gemini CLI v0.8.2, разошёлся с апстримом с v0.1).
- **[QwenLM/Qwen-Agent](https://github.com/QwenLM/Qwen-Agent)** — официальный агентный фреймворк Alibaba.
- Исследование: **Андрей Иванов**, R&D red_mad_robot — «Системный промпт против привычек Qwen».

## Лицензия

MIT — см. [`LICENSE`](./LICENSE).

qwen-native-agents

qwen-native-agents Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

qwen-native-agents

qwen-native-agents Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README