Skip to Content
ユーザーガイド機能サブエージェント

サブエージェント

サブエージェントは、Qwen Code 内で特定の種類のタスクを処理する専門の AI アシスタントです。タスク固有のプロンプト、ツール、および動作が設定された AI エージェントに集中した作業を委任できます。

サブエージェントとは?

サブエージェントは独立した AI アシスタントであり、以下の特徴を持っています:

  • 特定のタスクに特化 - 各サブエージェントは、特定の種類の作業に焦点を当てたシステムプロンプトで構成されています
  • 個別のコンテキストを持つ - メインチャットとは別に、独自の会話履歴を保持します
  • 制御されたツールの使用 - 各サブエージェントがアクセスできるツールを設定できます
  • 自律的に作業 - タスクが与えられると、完了または失敗するまで独立して作業を進めます
  • 詳細なフィードバックを提供 - 進行状況、ツールの使用状況、実行統計をリアルタイムで確認できます

主な利点

  • タスクの専門化: 特定のワークフロー(テスト、ドキュメンテーション、リファクタリングなど)に最適化されたエージェントを作成
  • コンテキストの分離: 専門的な作業をメインの会話から分離して管理
  • 再利用性: エージェント構成をプロジェクトやセッション間で保存・再利用可能
  • 制御されたアクセス: 各エージェントが使用できるツールを制限し、セキュリティと焦点を維持
  • 進行状況の可視性: 実行状況をリアルタイムで監視可能

サブエージェントの仕組み

  1. 設定: サブエージェントの動作、ツール、システムプロンプトを定義する構成を作成します
  2. 委任: メインAIは適切なサブエージェントに自動的にタスクを委任できます
  3. 実行: サブエージェントは独立して作業し、構成されたツールを使用してタスクを完了します
  4. 結果: 完了した結果と実行サマリーをメインの会話に戻します

はじめ方

クイックスタート

  1. 最初の Subagent を作成する:

    /agents create

    ガイド付きウィザードに従って、専門的なエージェントを作成します。

  2. 既存のエージェントを管理する:

    /agents manage

    設定した Subagent を表示および管理します。

  3. Subagent を自動的に使用する: メインの AI に、Subagent の専門分野に一致するタスクを実行するよう単純に依頼してください。AI は適切な作業を自動的に委任します。

使用例

ユーザー: "認証モジュールの包括的なテストを書いてください" AI: これをテストの専門家である Subagent に委任します。 ["testing-expert" Subagent に委任] [テスト作成のリアルタイム進捗を表示] [完成したテストファイルと実行サマリーを返却]

管理

CLI コマンド

サブエージェントは /agents スラッシュコマンドとそのサブコマンドを通じて管理されます。

使用方法:/agents create。ガイド付きのステップウィザードを使用して新しいサブエージェントを作成します。

使用方法:/agents manage。既存のサブエージェントを表示および管理するための対話型管理ダイアログを開きます。

ストレージロケーション

サブエージェントは、複数の場所に Markdown ファイルとして保存されます。

  • プロジェクトレベル: .qwen/agents/ (最も優先度が高い)
  • ユーザーレベル: ~/.qwen/agents/ (フォールバック)
  • 拡張機能レベル: インストールされた拡張機能によって提供される

これにより、プロジェクト固有のエージェント、すべてのプロジェクトで動作する個人用エージェント、および専門的な機能を追加する拡張機能提供のエージェントを持つことができます。

拡張機能サブエージェント

拡張機能は、有効化された際に利用可能になるカスタムサブエージェントを提供できます。これらのエージェントは拡張機能の agents/ ディレクトリに格納され、パーソナルエージェントやプロジェクトエージェントと同じ形式に従います。

拡張機能サブエージェントは:

  • 拡張機能が有効化された際に自動的に検出されます
  • /agents manage ダイアログの「Extension Agents」セクションに表示されます
  • 直接編集することはできません(代わりに拡張機能のソースを編集してください)
  • ユーザー定義エージェントと同じ設定フォーマットに従います

どの拡張機能がサブエージェントを提供しているかを確認するには、拡張機能の qwen-extension.json ファイルに agents フィールドがあるかを確認してください。

ファイルフォーマット

サブエージェントは、YAMLフロントマター付きのMarkdownファイルを使用して設定されます。このフォーマットは人間が読みやすく、任意のテキストエディタで簡単に編集できます。

基本構造

--- name: エージェント名 description: このエージェントを使用するタイミングと方法の簡単な説明 tools: - ツール1 - ツール2 - ツール3 # 省略可 --- システムプロンプトの内容はここに記述します。 複数段落もサポートされています。 動的なコンテンツのために ${variable} テンプレートを使用できます。

使用例

--- name: プロジェクトドキュメンター description: プロジェクトのドキュメントとREADMEファイルを作成する --- あなたは ${project_name} プロジェクトのドキュメンテーション担当者です。 タスク: ${task_description} 作業ディレクトリ: ${current_directory} 生成日時: ${timestamp} 新規貢献者とエンドユーザーがプロジェクトを理解できるように、 明確で包括的なドキュメントを作成することに集中してください。

サブエージェントを効果的に使用する

自動委任

Qwen Code は以下の要素に基づいて、積極的にタスクを委任します。

  • リクエスト内のタスク説明
  • サブエージェント構成の説明フィールド
  • 現在のコンテキストと利用可能なツール

より積極的なサブエージェントの使用を促進するには、「PROACTIVELY 使用してください」や「必ず使用してください(MUST BE USED)」などの表現を説明フィールドに含めてください。

明示的呼び出し

コマンド内で特定のサブエージェントに言及して、それを要求します。

testing-expert サブエージェントに支払いモジュールのユニットテストを作成させる documentation-writer サブエージェントに API リファレンスを更新させる react-specialist サブエージェントにこのコンポーネントのパフォーマンスを最適化させる

開発ワークフロー エージェント

テストの専門家

包括的なテスト作成およびテスト駆動開発に最適です。

--- name: testing-expert description: 高品質なユニットテスト、インテグレーションテストを作成し、ベストプラクティスに基づいてテスト自動化を実施します tools: - read_file - write_file - read_many_files - run_shell_command --- あなたは高品質で保守性の高いテスト作成に特化したテストの専門家です。 あなたの専門知識には以下が含まれます: - 適切なモックと分離によるユニットテスト - コンポーネント間の相互作用のためのインテグレーションテスト - テスト駆動開発(TDD)の実践 - エッジケースの特定と網羅的なカバレッジ - 必要に応じたパフォーマンスおよび負荷テスト 各テストタスクでは以下の手順を実行してください: 1. コード構造と依存関係を分析する 2. 主要機能、エッジケース、エラー条件を特定する 3. 説明的な名前を持つ包括的なテストスイートを作成する 4. 適切なセットアップ/ティアダウンと意味のあるアサーションを含める 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、コード分割 - **テスト**: React Testing Library、Jest、コンポーネントテスト戦略 - **TypeScript 統合**: props、フック、コンポーネントの適切な型付け - **モダンパターン**: Suspense、Error Boundaries、Concurrent Features React タスクでは: 1. デフォルトで関数型コンポーネントとフックを使用する 2. 適切な TypeScript 型付けを実装する 3. React のベストプラクティスと規約に従う 4. パフォーマンスへの影響を考慮する 5. 適切なエラーハンドリングを含める 6. テスト可能で保守しやすいコードを書く 常に React のベストプラクティスを最新のものに保ち、非推奨のパターンを避けてください。 アクセシビリティとユーザーエクスペリエンスの考慮事項に焦点を当ててください。

利用例:

  • 「ソートとフィルタリング機能付きの再利用可能なデータテーブルコンポーネントを作成する」
  • 「キャッシング機能付きの API データ取得用カスタムフックを実装する」
  • 「このクラスコンポーネントをモダンな React パターンを使ってリファクタリングする」

Python エキスパート

Python 開発、フレームワーク、およびベストプラクティスに特化しています。

--- name: python-expert description: Python 開発、フレームワーク、テスト、および Python 固有のベストプラクティスに関するエキスパート tools: - read_file - write_file - read_many_files - run_shell_command --- あなたは Python エコシステムについて深い知識を持つ Python のエキスパートです。 あなたの専門知識には以下が含まれます: - **Core Python**: Pythonic パターン、データ構造、アルゴリズム - **フレームワーク**: Django、Flask、FastAPI、SQLAlchemy - **テスト**: pytest、unittest、モック、テスト駆動開発 - **データサイエンス**: pandas、numpy、matplotlib、jupyter ノートブック - **非同期プログラミング**: asyncio、async/await パターン - **パッケージ管理**: pip、poetry、仮想環境 - **コード品質**: PEP 8、型ヒント、pylint/flake8 によるリンティング Python タスクでは: 1. PEP 8 スタイルガイドラインに従う 2. 型ヒントを使用してコードドキュメントを改善する 3. 特定の例外を使用した適切なエラーハンドリングを実装する 4. 包括的な docstring を書く 5. パフォーマンスとメモリ使用量を考慮する 6. 適切なロギングを含める 7. テスト可能でモジュール化されたコードを書く コミュニティ標準に従ったクリーンで保守可能な Python コードを書くことに集中してください。

利用例:

  • 「JWT トークンを使用したユーザー認証のための FastAPI サービスを作成する」
  • 「pandas とエラーハンドリングを使用したデータ処理パイプラインを実装する」
  • 「argparse を使用した包括的なヘルプドキュメント付きの CLI ツールを書く」

ベストプラクティス

設計原則

単一責任の原則

各サブエージェントは、明確で焦点を絞った目的を持つべきです。

✅ 良い例:

--- name: testing-expert description: 包括的なユニットテストとインテグレーションテストを作成する ---

❌ 避けるべき:

--- name: general-helper description: テスト、ドキュメンテーション、コードレビュー、デプロイメントを支援する ---

理由: 焦点が明確なエージェントの方が優れた結果を出し、保守も容易になります。

明確な専門性

広範な能力ではなく、特定の専門分野を定義してください。

✅ 良い例:

--- name: react-performance-optimizer description: プロファイリングとベストプラクティスを使用してReactアプリケーションのパフォーマンスを最適化する ---

❌ 避けるべき:

--- name: frontend-developer description: フロントエンド開発タスクに取り組む ---

理由: 特定の専門知識により、より的確で効果的な支援が可能になります。

アクショナブルな説明

エージェントを使用するタイミングを明確に示す説明を書きましょう。

✅ 良い例:

description: セキュリティ脆弱性、パフォーマンスの問題、保守性に関する懸念事項についてコードをレビューします

❌ 避けるべき例:

description: 役立つコードレビュアー

理由: 明確な説明により、メインのAIが各タスクに適したエージェントを選択しやすくなります。

設定のベストプラクティス

システムプロンプトのガイドライン

専門知識について具体的に記述する:

あなたはPythonテストの専門家であり、以下の分野に精通しています。 - pytestフレームワークとフィクスチャ - モックオブジェクトと依存性注入 - テスト駆動開発の実践 - pytest-benchmarkを利用したパフォーマンステスト

段階的なアプローチを含める:

各テストタスクに対して以下を実施してください。 1. コード構造と依存関係を分析する 2. 主要な機能とエッジケースを特定する 3. 明確な命名規則に基づいた包括的なテストスイートを作成する 4. セットアップ/ティアダウンと適切なアサーションを含める 5. 複雑なテストシナリオを説明するコメントを追加する

出力基準を明確にする:

常に以下の基準に従ってください。 - シナリオを説明する記述的なテスト名を使用する - 正常系と異常系の両方のテストケースを含める - 複雑なテスト関数にはドキュメント文字列を追加する - テストが独立しており、任意の順序で実行できるようにする

セキュリティに関する考慮事項

  • ツール制限: サブエージェントは設定されたツールのみにアクセスできます
  • サンドボックス化: すべてのツール実行は、直接ツールを使用する場合と同じセキュリティモデルに従います
  • 監査ログ: すべてのサブエージェントのアクションは記録され、リアルタイムで表示されます
  • アクセス制御: プロジェクトおよびユーザーごとの分離により、適切な境界線が提供されます
  • 機密情報: エージェント構成にシークレットや認証情報を含めないでください
  • 本番環境: 本番環境と開発環境では、別々のエージェントを検討してください
Last updated on