Subagentы

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

Что такое Subagentы?

Subagentы — это независимые AI-ассистенты, которые:

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

Fork Subagent

В дополнение к именованным subagent, Qwen Code поддерживает форкинг — явно выбираемый с помощью subagent_type: "fork" (доступен в интерактивных сессиях). Форк наследует полный контекст диалога родителя и работает в фоне. Отсутствие subagent_type не создаёт форк; запускается subagent общего назначения, который выполняется до конца и возвращает результат встроенно.

Чем Fork отличается от именованных Subagent

Когда используется Fork

AI автоматически использует форк, когда ему нужно:

• Выполнять несколько исследовательских задач параллельно (например, «изучить модули A, B и C»)
• Выполнять фоновую работу, продолжая основной диалог
• Делегировать задачи, требующие понимания текущего контекста диалога

Совместное использование кэша промптов

Все форки используют точный префикс API-запроса родителя (системный промпт, инструменты, история диалога), что позволяет получать попадания в кэш промптов DashScope. Когда 3 форка работают параллельно, общий префикс кэшируется один раз и повторно используется — экономия более 80% затрат на токены по сравнению с независимыми subagent.

Предотвращение рекурсивных форков

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

Текущие ограничения

• Нет обратной связи по результатам: Результаты форка отображаются в UI прогресса, но не возвращаются автоматически в основной диалог. Родительский AI видит сообщение-заполнитель и не может действовать на основе вывода форка.
• Нет изоляции рабочей директории: Форки используют рабочую директорию родителя. Одновременные изменения файлов из нескольких форков могут конфликтовать.

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

• Специализация задач: Создавайте агентов, оптимизированных для конкретных рабочих процессов (тестирование, документация, рефакторинг и т.д.)
• Изоляция контекста: Держите специализированную работу отдельно от основного диалога
• Наследование контекста: Форки subagent наследуют полный диалог для контекстно-зависимых параллельных задач
• Совместное использование кэша промптов: Форки subagent разделяют кэш-префикс родителя, снижая затраты на токены
• Многократное использование: Сохраняйте и повторно используйте конфигурации агентов в разных проектах и сессиях
• Контролируемый доступ: Ограничивайте, какие инструменты может использовать каждый агент, для безопасности и фокуса
• Видимость прогресса: Отслеживайте выполнение агента с обновлениями в реальном времени

Как работают Subagentы

1. Конфигурация: Вы создаёте конфигурации Subagent, которые определяют их поведение, инструменты и системные промпты
2. Делегирование: Основной AI может автоматически делегировать задачи подходящим Subagent — или форкать себя (subagent_type: "fork"), когда хочет унаследовать полный контекст диалога и отбросить промежуточный вывод
3. Выполнение: Subagentы работают независимо, используя свои настроенные инструменты для выполнения задач
4. Результаты: Они возвращают результаты и сводки выполнения обратно в основной диалог

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

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

1. Создайте своего первого Subagent:

   /agents create

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

2. Управляйте существующими агентами:

   /agents manage

   Просматривайте и управляйте настроенными Subagent.

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

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

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

Управление

Команды CLI

Subagent управляются через слэш-команду /agents и её подкоманды:

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

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

Места хранения

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

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

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

Subagent расширений

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

Subagent расширений:

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

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

Формат файла

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

Базовая структура

---
name: agent-name
description: Краткое описание того, когда и как использовать этого агента
model: inherit   # Опционально: inherit, fast, modelId или authType:modelId
approvalMode: auto-edit   # Опционально: default, plan, auto-edit, yolo, bubble
tools:           # Опционально: белый список инструментов
  - tool1
  - tool2
disallowedTools: # Опционально: чёрный список инструментов
  - tool3
---

Содержимое системного промпта.
Поддерживаются несколько абзацев.

Выбор модели

Используйте опциональное поле model во фронтматере для управления тем, какую модель использует subagent:

• inherit: Использовать ту же модель, что и в основном диалоге.
• Пропустите поле: То же самое, что inherit.
• fast: Использовать настроенную fastModel. Если корректная быстрая модель не настроена, subagent переключается на inherit.
• glm-5: Использовать указанный ID модели. Qwen Code сначала проверяет тип аутентификации основного диалога; если модель там недоступна, он может разрешить модель у другого настроенного провайдера.
• openai:gpt-4o: Использовать явного провайдера и ID модели. Это полезно, когда subagent должен работать на модели, зарегистрированной под другим типом аутентификации, чем основной диалог.

Например:

---
name: fast-reviewer
description: Просматривает небольшие diff'ы с настроенной быстрой моделью
model: fast
tools:
  - read_file
  - grep_search
---

---
name: openai-researcher
description: Использует совместимого с OpenAI провайдера для исследовательских задач
model: openai:gpt-4o
tools:
  - read_file
  - grep_search
  - glob
---

Селектор fast использует ту же настройку fastModel, настроенную в settings.json или с помощью /model --fast. Эта настройка может сама ссылаться на модель под другим настроенным типом аутентификации, например openai:deepseek-v4-flash. Когда селектор разрешается в другой тип аутентификации, Qwen Code создаёт выделенного провайдера времени выполнения для этого запроса subagent и отправляет провайдеру только голый ID модели.

Режим разрешений

Используйте опциональное поле approvalMode во фронтматере для управления тем, как одобряются вызовы инструментов subagent. Допустимые значения:

• default: Для инструментов требуется интерактивное одобрение (как и по умолчанию в основной сессии)
• plan: Только анализ — агент планирует, но не выполняет изменения
• auto-edit: Инструменты одобряются автоматически без запроса (рекомендуется для большинства агентов)
• yolo: Все инструменты одобряются автоматически, включая потенциально деструктивные
• bubble: Одобрения инструментов фонового агента отображаются в родительской сессии

Если вы опускаете это поле, режим разрешений subagent определяется автоматически:

• Если родительская сессия находится в режиме yolo или auto-edit, subagent наследует этот режим. Разрешительный родитель остаётся разрешительным.
• Если родительская сессия находится в режиме plan, subagent остаётся в режиме plan. Сессия только для анализа не может изменять файлы через делегированного агента.
• Если родительская сессия находится в режиме default (в доверенной папке), subagent получает auto-edit, чтобы он мог работать автономно.

Когда вы устанавливаете approvalMode, разрешительные режимы родителя по-прежнему имеют приоритет. Например, если родитель находится в режиме yolo, subagent с approvalMode: plan всё равно будет работать в режиме yolo.

---
name: cautious-reviewer
description: Просматривает код без внесения изменений
approvalMode: plan
tools:
  - read_file
  - grep_search
  - glob
---

Вы — ревьюер кода. Анализируйте код и сообщайте о результатах.
Не изменяйте никакие файлы.

Настройка инструментов

Используйте tools и disallowedTools для управления тем, к каким инструментам может обращаться subagent.

tools (белый список): При указании subagent может использовать только перечисленные инструменты. Если поле опущено, subagent наследует все доступные инструменты от родительской сессии.

---
name: reader
description: Агент только для чтения для исследования кода
tools:
  - read_file
  - grep_search
  - glob
  - list_directory
---

disallowedTools (чёрный список): При указании перечисленные инструменты удаляются из пула инструментов subagent. Это полезно, когда нужно «всё, кроме X» без перечисления каждого разрешённого инструмента.

---
name: safe-worker
description: Агент, не могущий изменять файлы
disallowedTools:
  - write_file
  - edit
  - run_shell_command
---

Если указаны и tools, и disallowedTools, сначала применяется белый список, затем из этого набора удаляются инструменты из чёрного списка.

Инструменты MCP следуют тем же правилам. Если у subagent нет списка tools, он наследует все инструменты MCP от родительской сессии. Если у subagent есть явный список tools, он получает только те инструменты MCP, которые явно указаны в этом списке.

Поле disallowedTools поддерживает шаблоны на уровне сервера MCP:

• mcp__server__tool_name — блокирует конкретный инструмент MCP
• mcp__server — блокирует все инструменты с этого сервера MCP

---
name: no-slack
description: Агент без доступа к Slack
disallowedTools:
  - mcp__slack
---

Поля совместимости с Claude Code

Qwen Code принимает поля фронтматера Claude Code 2.1.168, перечисленные ниже, так что вы можете поместить файл агента CC в .qwen/agents/, и поддерживаемые поля будут парситься идентично. Опциональные поля с недопустимыми значениями молча отбрасываются во время парсинга, а не отвергаются — та же либеральная позиция, которую использует CC.

Пример со всем вышеперечисленным:

---
name: rigorous-reviewer
description: Глубокий ревью кода с ограничением ходов
permissionMode: plan
maxTurns: 50
color: cyan
tools:
  - read_file
  - grep_search
  - glob
mcpServers:
  filesystem:
    type: stdio
    command: node
    args: [/usr/local/lib/mcp-fs/server.js]
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: echo "review-agent about to run a shell command"
---

Вы — ревьюер кода. Тщательно анализируйте код и сообщайте о результатах,
упорядоченных по серьёзности.

Остальные поля фронтматера CC — effort, skills, initialPrompt, memory, isolation — документированы в дизайн-документе декларативных агентов и появятся в последующих PR, когда будет создана необходимая инфраструктура (effort требует параметра на уровне модели; memory требует подсистему памяти с областью видимости; флаг CLI --agent включает initialPrompt; и т.д.).

Ограничение v1 для hooks. Пока работает subagent, объявивший hooks, его записи хуков срабатывают для каждого подходящего события в сессии, а не только для вызовов инструментов этого subagent. Если два subagent с разными наборами хуков для каждого агента работают одновременно, оба набора срабатывают для обоих агентов. Фильтрация по области видимости агента во время срабатывания хука оставлена на будущее; для v1 предпочитайте хуки для каждого агента, которые безопасно срабатывают глобально на время выполнения агента (например, логирование), вместо хуков, которые изменяют поведение.

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

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

Вы — специалист по документации.

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

Эффективное использование Subagent

Автоматическое делегирование

Qwen Code проактивно делегирует задачи на основе:

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

Чтобы стимулировать более проактивное использование Subagent, включайте фразы типа «использовать ПРОАКТИВНО» или «ДОЛЖЕН БЫТЬ ИСПОЛЬЗОВАН» в поле description.

Явный вызов

Запросите конкретного Subagent, упомянув его в своей команде:

Пусть Subagent testing-expert создаст модульные тесты для модуля оплаты
Поручи Subagent documentation-writer обновить API-справочник
Пусть Subagent react-specialist оптимизирует производительность этого компонента

Примеры

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

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

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

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

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

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

- Модульное тестирование с соответствующим мокингом и изоляцией
- Интеграционное тестирование взаимодействия компонентов
- Практики разработки через тестирование
- Выявление граничных случаев и всестороннее покрытие
- Тестирование производительности и нагрузки, когда это уместно

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

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

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

Варианты использования:

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

Писатель документации

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

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

Вы — специалист по технической документации.

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

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

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

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

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

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

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

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

Варианты использования:

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

Ревьюер кода

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

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

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

Критерии проверки:

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

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

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

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

Варианты использования:

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

Предметно-ориентированные агенты

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

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

---
name: react-specialist
description: Expert in React development, hooks, component patterns, and modern React best practices
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

You are a React specialist with deep expertise in modern React development.

Your expertise covers:

- **Component Design**: Functional components, custom hooks, composition patterns
- **State Management**: useState, useReducer, Context API, and external libraries
- **Performance**: React.memo, useMemo, useCallback, code splitting
- **Testing**: React Testing Library, Jest, component testing strategies
- **TypeScript Integration**: Proper typing for props, hooks, and components
- **Modern Patterns**: Suspense, Error Boundaries, Concurrent Features

For React tasks:

1. Use functional components and hooks by default
2. Implement proper TypeScript typing
3. Follow React best practices and conventions
4. Consider performance implications
5. Include appropriate error handling
6. Write testable, maintainable code

Always stay current with React best practices and avoid deprecated patterns.
Focus on accessibility and user experience considerations.

Варианты использования:

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

Эксперт по Python

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

---
name: python-expert
description: Expert in Python development, frameworks, testing, and Python-specific best practices
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

You are a Python expert with deep knowledge of the Python ecosystem.

Your expertise includes:

- **Core Python**: Pythonic patterns, data structures, algorithms
- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy
- **Testing**: pytest, unittest, mocking, test-driven development
- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
- **Async Programming**: asyncio, async/await patterns
- **Package Management**: pip, poetry, virtual environments
- **Code Quality**: PEP 8, type hints, linting with pylint/flake8

For Python tasks:

1. Follow PEP 8 style guidelines
2. Use type hints for better code documentation
3. Implement proper error handling with specific exceptions
4. Write comprehensive docstrings
5. Consider performance and memory usage
6. Include appropriate logging
7. Write testable, modular code

Focus on writing clean, maintainable Python code that follows community standards.

Варианты использования:

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

Лучшие практики

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

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

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

✅ Хорошо:

---
name: testing-expert
description: Writes comprehensive unit tests and integration tests
---

❌ Избегайте:

---
name: general-helper
description: Helps with testing, documentation, code review, and deployment
---

Почему: Сфокусированные агенты дают лучшие результаты и их проще поддерживать.

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

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

✅ Хорошо:

---
name: react-performance-optimizer
description: Optimizes React applications for performance using profiling and best practices
---

❌ Избегайте:

---
name: frontend-developer
description: Works on frontend development tasks
---

Почему: Конкретная экспертиза ведёт к более целенаправленной и эффективной помощи.

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

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

✅ Хорошо:

description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns

❌ Избегайте:

description: A helpful code reviewer

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

Лучшие практики настройки

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

Указывайте конкретные знания:

You are a Python testing specialist with expertise in:

- pytest framework and fixtures
- Mock objects and dependency injection
- Test-driven development practices
- Performance testing with pytest-benchmark

Включайте пошаговые подходы:

For each testing task:

1. Analyze the code structure and dependencies
2. Identify key functionality and edge cases
3. Create comprehensive test suites with clear naming
4. Include setup/teardown and proper assertions
5. Add comments explaining complex test scenarios

Указывайте стандарты вывода:

Always follow these standards:

- Use descriptive test names that explain the scenario
- Include both positive and negative test cases
- Add docstrings for complex test functions
- Ensure tests are independent and can run in any order

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

• Ограничения инструментов: Используйте tools, чтобы ограничить, к каким инструментам сабагент имеет доступ, или disallowedTools, чтобы заблокировать конкретные инструменты, наследуя все остальные.
• Режим разрешений: Сабагенты по умолчанию наследуют режим разрешений родителя. Сессии в режиме планирования не могут повысить свои права до auto-edit через делегированных агентов. Привилегированные режимы (auto-edit, yolo) заблокированы в ненадёжных папках.
• Выбор провайдера: Сабагент с model: authType:modelId или model: fast (где fastModel разрешается в другой тип аутентификации) отправляет запросы модели этого сабагента выбранному провайдеру. Убедитесь, что этот провайдер подходит для задачи и данных сабагента.
• Изоляция: Все выполнение инструментов следует той же модели безопасности, что и прямое использование инструментов.
• Журнал аудита: Все действия сабагентов логируются и отображаются в реальном времени.
• Контроль доступа: Разделение на уровне проекта и пользователя обеспечивает соответствующие границы.
• Конфиденциальная информация: Избегайте включения секретов или учётных данных в конфигурации агентов.
• Продуктивные среды: Рассмотрите возможность создания отдельных агентов для продуктивной и тестовой сред.

Ограничения

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

• Поле описания: Предупреждение отображается для описаний, превышающих 1 000 символов.
• Системный промпт: Предупреждение отображается для системных промптов, превышающих 10 000 символов.