VS Code のカスタムエージェント

カスタムエージェントを使用すると、特定の開発ロールやタスクに合わせて調整されたペルソナを採用するように AI を構成できます。たとえば、セキュリティレビュー担当者、プランナー、ソリューションアーキテクト、その他の専門的な役割のためのエージェントを作成できます。各ペルソナは、独自の動作、利用可能なツール、指示を持つことができます。

ハンドオフを使用して、エージェント間のガイド付きワークフローを作成することもできます。一度の選択で、専門エージェントから別のエージェントへシームレスに移行できます。たとえば、プランニングエージェントから実装エージェントへ直接移動したり、関連するコンテキストと共にコードレビュー担当者へ引き継いだりすることが可能です。

この記事では、VS Code でカスタムエージェントを作成および管理する方法について説明します。

カスタムエージェントとは？

組み込みエージェントは、VS Code でのチャット用に汎用的な構成を提供します。より調整されたチャット体験のために、独自のカスタムエージェントを作成できます。

カスタムエージェントは、そのエージェントに切り替えたときに適用される一連の指示とツールで構成されます。たとえば、「プラン（Plan）」エージェントには、実装計画を生成するための指示を含め、読み取り専用ツールのみを使用させることができます。カスタムエージェントを作成することで、毎回関連するツールや指示を手動で選択することなく、特定の構成にすばやく切り替えることができます。

カスタムエージェントは .agent.md マークダウンファイルで定義されます。これをワークスペースに保存して他のユーザーと共有したり、ユーザープロファイルに保存して異なるワークスペース間で再利用したりできます。

カスタムエージェントはバックグラウンドエージェントやクラウドエージェントでも再利用でき、同じ専門的な構成で自律的なタスクを実行できます。

なぜカスタムエージェントを使うのか？

タスクによって必要な機能は異なります。プランニングエージェントには、誤ったコード変更を防ぐために調査および分析用の読み取り専用ツールのみが必要な場合がありますが、実装エージェントには完全な編集機能が必要です。カスタムエージェントを使用すると、タスクごとにどのツールが利用可能かを正確に指定でき、AI がその仕事に適した機能を確実に持つようにできます。

また、カスタムエージェントでは、AI がどのように動作すべきかを定義する専門的な指示を提供できます。たとえば、プランニングエージェントはプロジェクトのコンテキストを収集して詳細な実装計画を作成するよう指示し、コードレビューエージェントはセキュリティ脆弱性の特定や改善の提案に集中させることができます。これらの専門的な指示により、エージェントを切り替えるたびに、タスクに適した一貫性のある応答が保証されます。

ハンドオフ

ハンドオフを使用すると、推奨される次のステップを備えた、エージェント間を遷移するガイド付きの順次ワークフローを作成できます。チャットの応答が完了すると、ユーザーが関連するコンテキストと事前入力されたプロンプトを使用して次のエージェントに移動できるハンドオフボタンが表示されます。

ハンドオフは、開発者が次のステップに進む前に各ステップを確認および承認できるような、多段階のワークフローを調整するのに役立ちます。例：

• 計画 → 実装: プランニングエージェントで計画を生成し、実装エージェントにハンドオフしてコーディングを開始します。
• 実装 → レビュー: 実装を完了し、コードレビューエージェントに切り替えて品質やセキュリティの問題をチェックします。
• 失敗するテストの作成 → パスするテストの作成: 大規模な実装よりもレビューしやすい失敗するテストを生成し、ハンドオフして必要なコード変更を実装し、テストをパスさせます。

エージェントファイルでハンドオフを定義するには、フロントマターに追加します。各ハンドオフは、ターゲットエージェント、ボタンラベル、および送信するオプションのプロンプトを指定します。

---
description: Generate an implementation plan
tools: ['search', 'web']
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Now implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)
---

ユーザーがハンドオフボタンを選択すると、プロンプトが事前入力された状態でターゲットエージェントに切り替わります。send: true の場合、プロンプトが自動的に送信され、次のワークフローステップが開始されます。

カスタムエージェントのファイル場所

カスタムエージェントは特定のワークスペース、またはすべてのワークスペースで使用可能なユーザーレベルで定義できます。次の表に、スコープに基づくカスタムエージェントのデフォルトのファイル場所を一覧表示します。ワークスペースのカスタムエージェントファイルに対して追加のファイル場所を構成するには、 chat.agentFilesLocations ... 設定を使用します。

ユーザーデータ内にカスタムエージェントを作成するには、エージェントカスタマイズエディターを使用するか、Chat: New Custom Agent コマンドを使用してください。

カスタムエージェントのファイル構造

カスタムエージェントファイルはマークダウンファイルで、.agent.md 拡張子を使用し、次の構造を持ちます。

ヘッダー (オプション)

ヘッダーは YAML フロントマターとしてフォーマットされ、次のフィールドがあります

本文

カスタムエージェントファイル本文には、マークダウン形式で実装が含まれます。ここで、このカスタムエージェントを使用する際に AI に従わせたい具体的なプロンプト、ガイドライン、またはその他の関連情報を記述します。

マークダウンリンクを使用して他のファイルを参照し、たとえば指示ファイルを再利用することができます。

本文でエージェントツールを参照するには、#tool:<tool-name> 構文を使用します。たとえば、fetch ツールを参照するには #tool:web/fetch を使用します。

チャットビューでカスタムエージェントを選択すると、カスタムエージェントファイルの本文にあるガイドラインがユーザーのチャットプロンプトの前に付加されます。

例

---
description: Generate an implementation plan for new features or refactoring existing code.
name: Planner
tools: ['web/fetch', 'search/codebase', 'search/usages']
model: ['Claude Opus 4.5', 'GPT-5.2']  # Tries models in order
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---
# Planning instructions
You are in planning mode. Your task is to generate an implementation plan for a new feature or for refactoring existing code.
Don't make any code edits, just generate a plan.

The plan consists of a Markdown document that describes the implementation plan, including the following sections:

* Overview: A brief description of the feature or refactoring task.
* Requirements: A list of requirements for the feature or refactoring task.
* Implementation Steps: A detailed list of steps to implement the feature or refactoring task.
* Testing: A list of tests that need to be implemented to verify the feature or refactoring task.

---
name: Feature Builder
description: Build features by researching first, then implementing
tools: ['agent']
agents: ['Researcher', 'Implementer']
---
You are a feature builder. For each task:
1. Use the Researcher agent to gather context and find relevant patterns in the codebase
2. Use the Implementer agent to make the actual code changes based on research findings

---
name: Researcher
description: Research codebase patterns and gather context
tools: ['search/codebase', 'web/fetch', 'search/usages']
---
Research thoroughly using read-only tools. Return a summary of findings.

---
name: Implementer
description: Implement code changes based on provided context
tools: ['edit', 'read/terminalLastCommand']
---
Implement changes following existing code patterns. Make minimal, focused edits.

---
name: "Strict Formatter"
description: "Agent that auto-formats code after every edit"
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-changed-files.sh"
---

You are a code editing agent. After making changes, files are automatically formatted.

Claude エージェント形式

.claude/agents フォルダー内のエージェントファイルは通常の .md ファイルを使用し、Claude 特有のフロントマタープロパティをサポートしています。

VS Code は Claude 特有のツール名を対応する VS Code ツールにマッピングします。VS Code の .agent.md 形式（ツールに YAML 配列を使用）と Claude 形式（カンマ区切り文字列を使用）の両方がサポートされています。

カスタムエージェントを作成する

ワークスペースまたはユーザープロファイルにカスタムエージェントファイルを作成できます。

1. チャットビューで Configure Chat（歯車アイコン）を選択してエージェントカスタマイズエディターを開き、Agents タブを選択します。

2. エージェントファイルを保存したい場所に応じて、ドロップダウンから New Agent (Workspace) または New Agent (User) を選択します。

   

   または、コマンドパレットから Chat: New Custom Agent コマンドを実行します（⇧⌘P（Windows, Linux Ctrl+Shift+P））。

   ヒント

   VS Code がカスタムエージェントファイルを検索する場所を追加するには、 chat.agentFilesLocations ... 設定を使用します。これは、プロジェクト間でエージェントを共有したり、ワークスペース外の中央の場所に保持したりする場合に便利です。

3. 場所を選択し、カスタムエージェントのファイル名を入力します。これがエージェントのドロップダウンに表示されるデフォルト名になります。

4. 新しく作成された .agent.md ファイルにカスタムエージェントの詳細を入力します。

   • ファイル上部の YAML フロントマターを埋めて、カスタムエージェントの名前、説明、ツール、およびその他の設定を構成します。
   • ファイルの本文にカスタムエージェントの指示を追加します。

既存のカスタムエージェントは、エージェントカスタマイズエディターで開いて変更できます。

AI でカスタムエージェントを生成する

役割の説明に基づいて AI にカスタムエージェントを生成させることができます。エージェントモードのチャットで /create-agent と入力し、必要なペルソナ（例：「セキュリティレビューエージェント」）を説明してください。エージェントが確認の質問を行い、適切なツール、指示、フロントマターを備えた .agent.md ファイルを生成します。

進行中の会話からカスタムエージェントを抽出することもできます。たとえば、数回にわたるデバッグセッションの後、「この種のタスクのためのエージェントを作って」と依頼すると、そのワークフローを再利用可能なカスタムエージェントとしてキャプチャできます。

エージェントカスタマイズエディターのドロップダウンから Generate Agent を選択して、カスタムエージェントを生成することもできます。

エージェントのドロップダウンリストをカスタマイズする

複数のカスタムエージェントがある場合、どれをエージェントドロップダウンに表示するかをカスタマイズできます。特定のカスタムエージェントを表示または非表示にするには：

1. エージェントのドロップダウンから Configure Custom Agents を選択します。

2. リスト内のカスタムエージェントの上にマウスを置き、目のアイコンを選択してドロップダウンから表示または非表示にします。

ツールリストの優先順位

カスタムエージェントとプロンプトファイルの両方で tools を使用する場合、プロンプトファイルのツールが優先されます。完全な優先順位については、プロンプトファイルのドキュメントにある Tool list priority を参照してください。

チーム間でカスタムエージェントを共有する

チーム間でカスタムエージェントを共有するには、ワークスペースレベルのカスタムエージェント（.github/agents フォルダー）を作成します。組織内の複数のワークスペース間でカスタムエージェントを共有したい場合は、GitHub 組織レベルで定義できます。

VS Code は、アカウントがアクセス権を持つ組織レベルで定義されたカスタムエージェントを自動的に検出します。これらのエージェントは、組み込みエージェントや、個人の、またはワークスペースのカスタムエージェントと一緒にチャットのエージェントドロップダウンに表示されます。

組織レベルのカスタムエージェントの検出を有効にするには、 github.copilot.chat.organizationCustomAgents.enabled ... を true に設定します。

GitHub ドキュメントで組織用のカスタムエージェントを作成する方法を確認してください。

よくある質問

カスタムエージェントはチャットモードと異なりますか？

カスタムエージェントは以前「カスタムチャットモード」と呼ばれていました。機能は同じですが、特定のタスクに対する AI の動作をカスタマイズするという目的をより適切に反映するように用語が更新されました。

既存の .chatmode.md ファイルがある場合は、.agent.md に名前を変更して新しいカスタムエージェント形式に変換し、適切な場所（ chat.agentFilesLocations ... ）に配置して引き続き使用してください。

カスタムエージェントを削除するには？

VS Code からカスタムエージェントを完全に削除するには：

• ワークスペースまたはユーザープロファイルから対応する .agent.md ファイルを削除します。
• エージェントドロップダウンから Configure Custom Agents を選択し、リスト内のカスタムエージェントにマウスを合わせて、ゴミ箱アイコンを選択します。

拡張機能によって提供されたカスタムエージェントを削除するには、その拡張機能をアンインストールする必要があります。拡張機能をアンインストールしたくない場合は、代わりにエージェントドロップダウンからカスタムエージェントを非表示にできます。エージェントのドロップダウンリストをカスタマイズするの手順に従ってください。

カスタムエージェントの由来を知るには？

カスタムエージェントは、組み込みエージェント、プロファイル内のユーザー定義エージェント、現在のワークスペースのワークスペース定義エージェント、組織定義エージェント、または拡張機能提供エージェントなど、さまざまなソースから由来する可能性があります。

カスタムエージェントのソースを特定するには：

1. エージェントのドロップダウンから Configure Custom Agents を選択します。
2. リスト内のカスタムエージェントにマウスを合わせます。ソースの場所がツールチップに表示されます。

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

カスタムエージェントは利用可能なツールを制限できるため、AI が何を実行できるかを制御できます。セキュリティに敏感なワークフローでは、予期しない変更を防ぐために読み取り専用ツールを備えたエージェントを作成してください。リポジトリでエージェントを共有する場合は、最小権限の原則に従っていることを確認するために、ツールリストと指示を確認してください。

関連リソース

• エージェントによる計画
• カスタム指示で AI をカスタマイズする
• 再利用可能なプロンプト ファイルを作成する
• チャットでツールを使用する