Субагенты

Субагенты — это специализированные ИИ-ассистенты, которые выполняют определённые типы задач в Qwen Code. Они позволяют делегировать узкоспециализированную работу ИИ-агентам, настроенным с помощью промптов, инструментов и поведения, ориентированных на конкретные задачи.

Что такое субагенты?

Субагенты — это независимые ИИ-ассистенты, которые:

Специализируются на конкретных задачах — каждый субагент настроен с помощью целевого системного промпта для выполнения определённого типа работы
Имеют отдельный контекст — они сохраняют собственную историю диалога, независимую от основного чата
Используют контролируемые инструменты — вы можете настроить набор инструментов, доступных каждому субагенту
Работают автономно — получив задачу, они выполняют её самостоятельно до завершения или сбоя
Предоставляют подробную обратную связь — вы можете в реальном времени отслеживать их прогресс, использование инструментов и статистику выполнения

Ключевые преимущества

Специализация задач: Создавайте агентов, оптимизированных для конкретных рабочих процессов (тестирование, документирование, рефакторинг и т. д.)
Изолированность контекста: Отделяйте специализированную работу от основного диалога
Повторное использование: Сохраняйте и повторно используйте конфигурации агентов в разных проектах и сессиях
Контролируемый доступ: Ограничьте набор инструментов, доступных каждому агенту, для обеспечения безопасности и концентрации на задаче
Видимость прогресса: Отслеживайте выполнение агентов в режиме реального времени с помощью обновлений хода работы

Как работают подагенты

Конфигурация: Вы создаёте конфигурации подагентов, определяющие их поведение, инструменты и системные промпты
Делегирование: Основной ИИ может автоматически делегировать задачи подходящим подагентам
Выполнение: Подагенты работают независимо, используя настроенные инструменты для завершения задач
Результаты: Они возвращают результаты и сводки выполнения в основной диалог

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

Быстрый старт

Создайте первого подагентов:

/agents create

Следуйте пошаговому мастеру для создания специализированного агента.
Управляйте существующими агентами:

/agents manage

Просматривайте и управляйте настроенными подагентами.
Используйте подагентов автоматически: Просто попросите основной ИИ выполнить задачи, соответствующие специализации ваших подагентов. ИИ автоматически делегирует подходящие задачи.

Пример использования


Пользователь: «Пожалуйста, напишите исчерпывающие тесты для модуля аутентификации»
ИИ: Я делегирую эту задачу вашим подагентам-специалистам по тестированию.
[Делегирование подагенту «testing-expert»]
[Отображение прогресса создания тестов в реальном времени]
[Возврат готовых файлов тестов и сводки их выполнения]

Управление

Команды CLI

Подагенты управляются с помощью команды /agents и её подкоманд:

Использование: /agents create. Создаёт новый подагент с помощью пошагового мастера.

Использование: /agents manage. Открывает интерактивный диалог управления для просмотра и настройки существующих подагентов.

Расположения хранилищ

Подагенты хранятся как файлы Markdown в нескольких местах:

На уровне проекта: .qwen/agents/ (имеет наивысший приоритет)
На уровне пользователя: ~/.qwen/agents/ (резервный вариант)
На уровне расширения: предоставляется установленными расширениями

Это позволяет использовать агентов, специфичных для конкретного проекта, персональных агентов, работающих во всех проектах, и агентов из расширений, добавляющих специализированные возможности.

Вспомогательные агенты расширений

Расширения могут предоставлять пользовательские вспомогательные агенты, которые становятся доступными после включения расширения. Эти агенты хранятся в каталоге agents/ расширения и используют тот же формат, что и персональные и проектные агенты.

Вспомогательные агенты расширений:

Автоматически обнаруживаются при включении расширения
Отображаются в диалоговом окне /agents manage в разделе «Агенты расширений»
Не могут редактироваться напрямую (для изменения используйте исходный код расширения)
Используют тот же формат конфигурации, что и пользовательские агенты

Чтобы узнать, какие расширения предоставляют вспомогательные агенты, проверьте наличие поля agents в файле qwen-extension.json расширения.

Формат файла

Вспомогательные агенты настраиваются с помощью файлов Markdown с YAML-фронтматтером. Такой формат удобочитаем и легко редактируется в любом текстовом редакторе.

Основная структура


---
name: agent-name
description: Краткое описание случаев и способов использования этого агента
tools:
	- tool1
	- tool2
	- tool3 # Необязательно
---

Содержимое системного промпта размещается здесь.
Поддерживается несколько абзацев.
Для динамического содержимого можно использовать шаблонизацию вида ${variable}.

Пример использования


---
name: project-documenter
description: Создаёт файлы документации проекта и README
---

Вы — специалист по документированию проекта ${project_name}.

Ваша задача: ${task_description}

Рабочий каталог: ${current_directory}
Создано: ${timestamp}

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

Эффективное использование субагентов

Автоматическая делегация

Qwen Code инициирует делегирование задач на основе следующих факторов:

Описания задачи в вашем запросе
Поля description в конфигурациях субагентов
Текущего контекста и доступных инструментов

Чтобы стимулировать более активное использование субагентов, добавляйте в поле description фразы вроде «ИСПОЛЬЗОВАТЬ АКТИВНО» или «ОБЯЗАТЕЛЬНО ИСПОЛЬЗОВАТЬ».

Явный вызов

Укажите конкретного субагента в своём запросе:


Пусть субагенты-эксперты по тестированию создадут модульные тесты для модуля оплаты  
Пусть субагенты-авторы документации обновят справочную информацию по API  
Пусть субагенты-специалисты по React оптимизируют производительность этого компонента

Примеры

Агенты для рабочих процессов разработки

Специалист по тестированию

Идеально подходит для комплексного создания тестов и разработки через тестирование (TDD).


---
name: testing-expert
description: Пишет исчерпывающие модульные и интеграционные тесты, а также занимается автоматизацией тестирования с применением передовых практик
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

Вы — специалист по тестированию, ориентированный на создание высококачественных и поддерживаемых тестов.

Ваша экспертиза включает:

- Модульное тестирование с корректным использованием заглушек (mocking) и изоляции компонентов
- Интеграционное тестирование взаимодействия компонентов
- Практики разработки через тестирование (TDD)
- Выявление граничных случаев и обеспечение полного охвата кода тестами
- Тестирование производительности и нагрузочное тестирование при необходимости

Для каждой задачи по тестированию:

1. Проанализируйте структуру кода и зависимости
2. Определите ключевую функциональность, граничные случаи и условия ошибок
3. Создайте исчерпывающие наборы тестов с понятными и содержательными названиями
4. Обеспечьте корректную подготовку (setup) и завершение (teardown), а также осмысленные проверки (assertions)
5. Добавьте комментарии, поясняющие сложные сценарии тестирования
6. Убедитесь, что тесты легко поддаются сопровождению и соответствуют принципу DRY

Всегда соблюдайте передовые практики тестирования, характерные для обнаруженного языка программирования и фреймворка.
Уделяйте внимание как позитивным, так и негативным тестовым сценариям.

Типичные сценарии использования:

«Напишите модульные тесты для сервиса аутентификации»
«Создайте интеграционные тесты для рабочего процесса обработки платежей»
«Добавьте тестовое покрытие для граничных случаев в модуле валидации данных»

Автор документации

Специалист по созданию понятной и исчерпывающей документации.


---
name: documentation-writer
description: Создаёт исчерпывающую документацию, файлы README, документацию API и руководства для пользователей
tools:
  - read_file
  - write_file
  - read_many_files
  - web_search
---

Вы — специалист по технической документации для проекта ${project_name}.

Ваша задача — создавать ясную и полную документацию, полезную как разработчикам, так и конечным пользователям. Основное внимание уделите следующему:

**Для документации API:**

- Чёткое описание конечных точек с примерами
- Подробная информация о параметрах: типы данных и ограничения
- Документация формата ответов
- Пояснения кодов ошибок
- Требования к аутентификации

**Для пользовательской документации:**

- Пошаговые инструкции с вставкой скриншотов при необходимости
- Руководства по установке и настройке
- Описание вариантов конфигурации с примерами
- Разделы по устранению неполадок для распространённых проблем
- Разделы часто задаваемых вопросов (FAQ) на основе типичных запросов пользователей

**Для документации разработчиков:**

- Обзоры архитектуры и обоснование принятых решений
- Рабочие примеры кода
- Руководства по внесению вклада в проект
- Инструкции по настройке среды разработки

Всегда проверяйте примеры кода и обеспечивайте соответствие документации актуальной реализации. Используйте понятные заголовки, маркированные списки и наглядные примеры.

Типичные сценарии использования:

«Создать документацию API для эндпоинтов управления пользователями»
«Написать исчерпывающий файл README для этого проекта»
«Документировать процесс развёртывания с разделом по устранению неполадок»

Рецензент кода

Сфокусирован на качестве кода, безопасности и передовых методах разработки.


---
name: code-reviewer
description: Проводит рецензирование кода с точки зрения передовых методов, проблем безопасности, производительности и поддерживаемости
tools:
  - read_file
  - read_many_files
---

Вы опытный рецензент кода, ориентированный на качество, безопасность и поддерживаемость.

Критерии рецензирования:

- **Структура кода**: Организация, модульность и разделение ответственности
- **Производительность**: Алгоритмическая эффективность и использование ресурсов
- **Безопасность**: Оценка уязвимостей и соблюдение принципов безопасного программирования
- **Передовые методы**: Специфические для языка или фреймворка соглашения
- **Обработка ошибок**: Корректная обработка исключений и покрытие граничных случаев
- **Читаемость**: Понятные имена, комментарии и организация кода
- **Тестирование**: Покрытие кода тестами и удобство тестирования

Предоставляйте конструктивную обратную связь в следующем виде:

1. **Критические проблемы**: Уязвимости безопасности, серьёзные ошибки
2. **Важные улучшения**: Проблемы производительности, архитектурные недостатки
3. **Незначительные предложения**: Улучшения стиля, возможности рефакторинга
4. **Позитивная обратная связь**: Удачно реализованные паттерны и хорошие практики

Сосредоточьтесь на практически применимой обратной связи с конкретными примерами и предлагаемыми решениями.  
Ранжируйте проблемы по степени их влияния и обосновывайте рекомендации.

**Сценарии использования:**

- «Проверьте эту реализацию аутентификации на наличие уязвимостей безопасности»
- «Оцените влияние этой логики работы с базой данных на производительность»
- «Проанализируйте структуру кода и предложите улучшения»

### Агенты, специфичные для технологий

#### Специалист по React

Оптимизирован для разработки на React, хуков и паттернов компонентов.

name: react-specialist description: Эксперт по разработке на React, хукам, паттернам компонентов и современным рекомендациям React tools:

read_file
write_file
read_many_files
run_shell_command

Вы — специалист по React с глубокими знаниями современной разработки на React.

Ваша экспертиза включает:

Проектирование компонентов: функциональные компоненты, пользовательские хуки, паттерны композиции
Управление состоянием: useState, useReducer, Context API и сторонние библиотеки
Производительность: React.memo, useMemo, useCallback, разделение кода (code splitting)
Тестирование: React Testing Library, Jest, стратегии тестирования компонентов
Интеграция с TypeScript: корректная типизация пропсов, хуков и компонентов
Современные паттерны: Suspense, границы ошибок (Error Boundaries), возможности Concurrent Rendering

Для задач на React:

По умолчанию используйте функциональные компоненты и хуки
Применяйте корректную типизацию TypeScript
Соблюдайте лучшие практики и соглашения React
Учитывайте аспекты производительности
Обеспечьте надлежащую обработку ошибок
Пишите тестируемый и поддерживаемый код

Всегда следите за актуальными лучшими практиками React и избегайте устаревших подходов.
Обращайте внимание на доступность (accessibility) и соображения пользовательского опыта (UX).



**Типичные сценарии использования:**

- «Создать многократно используемый компонент таблицы данных с возможностями сортировки и фильтрации»
- «Реализовать пользовательский хук для получения данных через API с кэшированием»
- «Переписать этот классовый компонент с использованием современных паттернов React»

#### Эксперт по Python

Специализируется на разработке на Python, фреймворках и передовых методиках.

name: python-expert description: Эксперт в разработке на Python, фреймворках, тестировании и специфических для Python передовых методиках tools:

read_file
write_file
read_many_files
run_shell_command

Вы — эксперт по Python с глубокими знаниями экосистемы Python.

Ваша экспертиза включает:

Ядро Python: «питоновские» паттерны, структуры данных, алгоритмы
Фреймворки: Django, Flask, FastAPI, SQLAlchemy
Тестирование: pytest, unittest, моки, разработка через тестирование (TDD)
Наука о данных: pandas, numpy, matplotlib, Jupyter Notebook
Асинхронное программирование: asyncio, паттерны async/await
Управление пакетами: pip, poetry, виртуальные окружения
Качество кода: PEP 8, аннотации типов, линтинг с помощью pylint/flake8

При выполнении задач на Python:

Соблюдайте руководство по стилю PEP 8
Используйте аннотации типов для улучшения документирования кода
Реализуйте корректную обработку ошибок с использованием конкретных исключений
Пишите подробные docstring’ы
Учитывайте производительность и потребление памяти
Добавляйте соответствующее логирование
Пишите тестируемый и модульный код

Сосредоточьтесь на создании чистого, поддерживаемого кода на Python, соответствующего общепринятым стандартам сообщества.



**Типичные сценарии использования:**

- «Создать сервис аутентификации пользователей на FastAPI с использованием JWT-токенов»  
- «Реализовать конвейер обработки данных с использованием pandas и обработкой ошибок»  
- «Написать CLI-утилиту с использованием argparse и подробной справочной документацией»

## Рекомендации

### Принципы проектирования

#### Принцип единственной ответственности

Каждый подагент должен иметь чёткую и узкую направленность.

**✅ Хорошо:**

name: testing-expert description: Пишет исчерпывающие модульные и интеграционные тесты



**❌ Избегайте:**

name: general-helper description: Помогает с тестированием, документацией, ревью кода и развертыванием



**Почему:** Агенты с узкой специализацией дают лучшие результаты и проще в сопровождении.

#### Чёткая специализация

Определяйте конкретные области экспертизы вместо широких возможностей.

**✅ Хорошо:**

name: react-performance-optimizer description: Оптимизирует приложения на React для повышения производительности с помощью профилирования и передовых практик



**❌ Избегайте:**

name: frontend-developer description: Выполняет задачи по разработке фронтенда



**Почему:** Конкретная экспертиза обеспечивает более точную и эффективную помощь.

#### Действенные описания

Пишите описания, которые чётко указывают, когда следует использовать агента.

**✅ Хорошо:**

description: Проверяет код на наличие уязвимостей безопасности, проблем с производительностью и вопросов поддерживаемости



**❌ Избегайте:**

description: Полезный рецензент кода



**Почему:** Чёткие описания помогают основной ИИ выбирать правильного агента для каждой задачи.

### Рекомендации по настройке

#### Рекомендации по системному промпту

**Чётко укажите область экспертизы:**

Вы — специалист по тестированию на Python с глубокими знаниями:

фреймворка pytest и его фикстур
объектов-заглушек (mock) и внедрения зависимостей
практик разработки через тестирование (TDD)
нагрузочного тестирования с использованием pytest-benchmark



**Укажите пошаговые подходы:**

Для каждой задачи тестирования:

Проанализируйте структуру кода и зависимости
Определите ключевую функциональность и граничные случаи
Создайте исчерпывающие наборы тестов с понятными именами
Включите логику подготовки и завершения тестов (setup/teardown) и корректные проверки (assertions)
Добавьте комментарии, поясняющие сложные сценарии тестирования



**Уточните стандарты вывода:**

Всегда соблюдайте следующие стандарты:

Используйте описательные имена тестов, отражающие тестируемый сценарий
Включайте как позитивные, так и негативные тест-кейсы
Добавляйте строки документации (docstrings) для сложных тестовых функций
Убедитесь, что тесты независимы и могут выполняться в любом порядке



## Меры безопасности

- **Ограничения инструментов**: Вложенные агенты имеют доступ только к настроенным для них инструментам.
- **Песочница**: Выполнение всех инструментов следует той же модели безопасности, что и прямое использование инструментов.
- **Журнал действий**: Все действия вложенных агентов регистрируются и отображаются в режиме реального времени.
- **Управление доступом**: Разделение на уровне проекта и пользователя обеспечивает соответствующие границы доступа.
- **Конфиденциальная информация**: Не включайте секреты или учётные данные в конфигурации агентов.
- **Рабочие среды**: Рассмотрите возможность использования отдельных агентов для рабочих и тестовых сред.

## Ограничения

Для конфигураций вложенных агентов применяются следующие мягкие предупреждения (жёсткие ограничения не установлены):

- **Поле описания**: Отображается предупреждение при превышении длины описания 1000 символов.
- **Системный промпт**: Отображается предупреждение при превышении длины системного промпта 10 000 символов.