Agent Tool (`agent`)

Этот документ описывает инструмент agent для Qwen Code.

Описание

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

Аргументы

agent принимает следующие аргументы:

description (string, required): Краткое (3–5 слов) описание задачи для отображения пользователю и отслеживания.
prompt (string, required): Подробный промпт с задачей для субагента. Должен содержать исчерпывающие инструкции для автономного выполнения.
subagent_type (string, optional): Тип специализированного агента для данной задачи. По умолчанию — general-purpose.
fork_turns (string, optional): Только для subagent_type="fork". Пропустите или используйте all для полного родительского разговора, или используйте положительное целое число, например "3", для последних трёх реальных ходов пользователя. Ответы инструментов и чистые системные напоминания не считаются ходами.
fork_tools (массив строк, optional): Только для subagent_type="fork". Ограничивает выполнение точными каноническими именами инструментов или паттернами MCP-серверов, не изменяя видимые инструментные декларации форка для совместного использования кэша промптов. Записи не могут содержать пробелы по краям; wildcards ограничены mcp__* или паттерном префикса MCP-инструмента, например mcp__github__read_*. Форки никогда не выполняют ask_user_question; пропустите fork_tools, чтобы разрешить все остальные унаследованные инструменты, или используйте пустой массив для отклонения всех вызовов инструментов.
fork_profile (строка, optional): Только для subagent_type="fork". Загружает frontmatter-only файл .qwen/fork-profiles/<name>.md размером не более 64 КиБ из корня активного проекта и применяет его обязательный массив tools и необязательный promptHint длиной не более 200 символов. Файл не может находиться вне директории профилей проекта. fork_profile нельзя комбинировать с fork_tools или именованным тиммейтом; он недоступен в safe mode или bare mode.
run_in_background (boolean, optional): По умолчанию true для верхнеуровневых обычных агентов. Установите false, чтобы ожидать результат обычного агента инлайн. Headless-форки всегда выполняются в фоне. Вложенные агенты выполняются в foreground, если run_in_background явно не равен true, что отклоняется, поскольку вложенные агенты не могут получать уведомления о завершении в фоне. Запуски с working_dir, принадлежащим вызывающему, выполняются в foreground и отклоняют явное или настроенное фоновое выполнение.
isolation (string, optional): Установите "worktree", чтобы запустить явно названного, не-fork агента в изолированном git worktree, который Qwen Code создаёт и управляет.
working_dir (string, optional): Привязать явно названного, не-fork агента к существующему зарегистрированному git worktree внутри текущего репозитория. Вызывающий владеет жизненным циклом worktree, поэтому этот режим выполняется в foreground. Если указаны и working_dir, и isolation, working_dir имеет приоритет.

Как использовать `agent` с Qwen Code

Инструмент Agent динамически загружает доступные субагенты из вашей конфигурации и делегирует им задачи. Каждый субагент работает независимо и может использовать собственный набор инструментов, что обеспечивает специализацию и параллельное выполнение.

При использовании инструмента Agent субагент:

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

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


agent(description="Краткое описание задачи", prompt="Подробные инструкции для субагента", subagent_type="agent_name")
agent(description="Краткое описание задачи", prompt="Подробные инструкции для форка", subagent_type="fork", fork_turns="3")
agent(description="Read-only investigation", prompt="Inspect the implementation", subagent_type="fork", fork_tools=["read_file", "grep_search", "mcp__github"])
agent(description="Profiled investigation", prompt="Inspect the implementation", subagent_type="fork", fork_profile="ro-research")

Установите run_in_background=false, когда текущий ход должен использовать результат субагента перед продолжением.

Доступные subagents

Доступные субагенты зависят от вашей конфигурации. Типичные типы subagent:

general-purpose: Для сложных многошаговых задач, требующих различных инструментов.
code-reviewer: Для рецензирования и анализа качества кода.
test-runner: Для запуска тестов и анализа результатов.
documentation-writer: Для создания и обновления документации.

Просмотреть доступные субагенты можно командой /agents в Qwen Code.

Возможности инструмента Agent

Обновления в реальном времени

Инструмент Agent предоставляет живые обновления, показывающие:

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

Параллельное выполнение

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

Специализированные знания

Каждый субагент может быть настроен со следующими параметрами:

Определённые права доступа к инструментам.
Специализированные системные промпты и инструкции.
Индивидуальные конфигурации модели.
Предметно-ориентированные знания и возможности.

Продолжение фонового агента

Фоновые агенты могут получать последующую работу после первоначального завершения:

Вызовите list_agents, чтобы найти доступных фоновых агентов текущей сессии и их значения task_id. Это включает совместимых агентов, восстановленных после возобновления родительской сессии.
Вызовите send_message с task_id и инструкцией для продолжения. Работающие агенты получают сообщение на следующей границе раунда инструментов, приостановленные агенты возобновляют работу с ним, а завершённые агенты продолжают работу на резидентном runtime, если он доступен, или оживают из сохранённого транскрипта.
Дождитесь следующего уведомления о завершении перед использованием результата продолжения.

Если агент не может быть продолжен, list_agents возвращает resume_blocked_reason. Относитесь к выходу восстановленных или продолженных агентов как к доказательствам и проверяйте их перед интеграцией изменений.

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

Делегирование универсальному агенту


agent(
  description="Рефакторинг кода",
  prompt="Пожалуйста, перепишите модуль аутентификации в src/auth/ с использованием современных async/await вместо колбэков. Убедитесь, что все тесты проходят, и обновите соответствующую документацию.",
  subagent_type="general-purpose"
)

Запуск параллельных задач


# Запуск проверки кода и выполнения тестов параллельно
agent(
  description="Проверка кода",
  prompt="Проверьте последние изменения в модуле управления пользователями на предмет качества кода, безопасности и соответствия лучшим практикам.",
  subagent_type="general-purpose"
)

agent(
  description="Запуск тестов",
  prompt="Выполните полный набор тестов и проанализируйте ошибки. Предоставьте сводку по покрытию тестами и рекомендации по улучшению.",
  subagent_type="test-engineer"
)

Генерация документации


agent(
  description="Обновление документации",
  prompt="Создайте полную API-документацию для новых REST-эндпоинтов в модуле заказов. Включите примеры запросов/ответов и коды ошибок.",
  subagent_type="general-purpose"
)

Когда использовать инструмент Agent

Используйте инструмент Agent в следующих случаях:

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

Когда НЕ следует использовать инструмент Agent

Не используйте инструмент Agent для:

Простых одношаговых операций — используйте прямые инструменты, такие как Read, Edit и др.
Интерактивных задач — задач, требующих диалога и обратной связи.
Чтения конкретных файлов — используйте инструмент Read напрямую для лучшей производительности.
Простого поиска — используйте инструменты Grep или Glob напрямую.

Важные замечания

Независимый контекст: Обычные субагенты запускаются без истории родительского разговора. Форки по умолчанию наследуют полный разговор и принимают fork_turns, когда достаточно ограниченного недавнего окна.
Взаимодействие с субагентами: Обычные субагенты не получают ask_user_question. Форки сохраняют список деклараций родителя для совместного использования кэша, но отклоняют этот инструмент перед планированием или одобрением; когда недостающий пользовательский ввод блокирует работу, субагент сообщает о блокере родителю.
Ограничения выполнения форков: fork_tools дополнительно сужает набор уже задекларированных инструментов, которые форк может выполнять. Запрещённые вызовы возвращают ошибку перед планированием или одобрением; тот же список деклараций остаётся видимым для модели для совместного использования кэша. Это ограничение на уровне вызова, выбранное вызывающим, а не песочница, навязанная администратором.
Профили форков: Профиль проекта в .qwen/fork-profiles/ использует тот же гейт выполнения, что и fork_tools. Он разрешается один раз перед запуском; разрешённый список сохраняется для воскрешения, а необязательный promptHint добавляется только к директиве задачи.
Доставка результатов: Результаты фоновых задач приходят через уведомления о завершении в следующем ходе. Не предполагайте результат до получения уведомления.
Продолжение: Используйте list_agents и send_message для связанной последующей работы вместо запуска дубликата агента. Продолжение зависит от совместимого сохранённого состояния и может быть недоступно.
Подробные промпты: Ваш начальный промпт должен содержать весь необходимый контекст и инструкции для автономного выполнения. Обычный субагент не видит разговор родителя.
Доступ к инструментам: Субагенты имеют доступ только к инструментам, настроенным в их конкретной конфигурации.
Параллельная работа: Несколько субагентов могут выполняться одновременно для повышения эффективности.
Зависимость от конфигурации: Доступные типы субагентов определяются вашей системной конфигурацией.

Конфигурация

Субагенты настраиваются через систему конфигурации агентов Qwen Code. Используйте команду /agents для:

Просмотра доступных субагентов.
Создания новых конфигураций субагентов.
Изменения существующих настроек субагентов.
Установки прав доступа к инструментам и возможностей.

Дополнительную информацию о настройке субагентов см. в документации по субагентам.

Agent Tool (agent)