カスタムエージェントの構成

このリファレンス記事では、カスタムエージェントの詳細な構成情報を提供します。カスタムエージェントの作成に関する一般的な情報については、AUTOTITLE を参照してください。

メモ

カスタム・エージェントは、JetBrains IDE、Eclipse、Xcode 用パブリックプレビューにあり、変更される可能性があります。

YAML frontmatter プロパティ

次の表は、エージェントプロファイル、GitHub.com、およびサポートされている IDE でCopilot CLI用に構成できるプロパティの概要を示しています (特に明記されていない限り)。環境固有の動作は、プロパティの説明に記載されています。最小レベルの構成が優先されるように、レベル間の重複除去には、構成ファイルの名前 (マイナス .md または .agent.md) が使用されます。

プロパティ	タイプ	目的
`name`	文字列

          カスタム エージェントの表示名。 Optional. |

| description | 必須の文字列 | カスタムエージェントの目的と機能の説明 | | target | 文字列 | カスタムエージェントのターゲット環境またはコンテキスト (vscodeまたはgithub-copilot)。設定を解除すると、既定で両方の環境が使用されます。 | | tools | 文字列の一覧、文字列 | カスタムエージェントが使用できるツール名の一覧。コンマ区切り文字列と yaml 文字列配列の両方をサポートします。設定を解除すると、既定ですべてのツールが使用されます。「ツール」を参照してください。 | | model | 文字列 | このカスタムエージェントの実行時に使用するモデル。設定を解除すると、既定のモデルが継承されます。 | | disable-model-invocation | ブーリアン | タスクコンテキストに基づいて、このCopilot クラウドエージェントを使用するカスタムエージェントを自動的に無効にします。 trueする場合は、エージェントを手動で選択する必要があります。 disable-model-invocation: trueの設定は、infer: falseと同じです。両方が設定されている場合は、 disable-model-invocation が優先されます。未設定の場合、falseが既定値として使用されます。 | | user-invocable | ブーリアン | このカスタムエージェントをユーザーが選択できるかどうかを制御します。 false場合、エージェントを手動で選択することはできず、プログラムでのみアクセスできます。未設定の場合、trueが既定値として使用されます。 | | infer | ブーリアン | ** 廃止 . 代わりに、disable-model-invocation および user-invocable を使用してください。タスクコンテキストに基づいて、 Copilot クラウドエージェントがこのカスタムエージェントを自動的に使用できるようにします。 falseする場合は、エージェントを手動で選択する必要があります。未設定の場合、trueが既定値として使用されます。 | | mcp-servers | オブジェクト | カスタムエージェントで使用する必要がある追加の MCP サーバーとツール。 ** VS Codeおよびその他の IDE カスタムエージェントでは使用されません。 | | metadata | 名前と値のペアで構成されるオブジェクト(両方の文字列) | 有用なデータに基づいたエージェントの注釈を許可します。 ** VS Codeおよびその他の IDE カスタムエージェントでは使用されません。** |

YAML frontmatter の下にある Markdown コンテンツで、エージェントの動作、専門知識、および手順を定義します。プロンプトの最大文字数は 30,000 文字です。

メモ

          `argument-hint`およびその他の IDE `handoffs`のVS Codeプロパティとカスタム エージェントプロパティは、現在、Copilot クラウド エージェントでのGitHub.comではサポートされていません。 互換性を確保するために無視されます。

          カスタム エージェント

          VS Codeファイル構造の詳細については、VS Codeを参照してください。

Tools

          カスタム エージェント
          `tools` プロパティは、MCP サーバーからのツールを含め、エージェントで使用できるツールを制御します。

          カスタム エージェントは、エージェント プロファイルとリポジトリの両方の設定で構成されている MCP サーバー ツールにアクセスできます。 リポジトリ内のクラウド エージェント用に MCP サーバーを構成する方法の詳細については、 [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp) を参照してください。

          `tools`は、次の方法で構成できます。

* 使用可能なすべてのツールを有効にする: tools プロパティを完全に省略するか、 tools: ["*"] を使用して使用可能なすべてのツールを有効にします。これには、エージェントプロファイルまたはリポジトリ設定で構成されているすべての MCP サーバーツールが含まれます。 * 特定のツールを有効にする: 特定のツール名またはエイリアス ( tools: ["read", "edit", "search"]など) の一覧を指定して、それらのツールのみを有効にします。使用可能なツールエイリアスについては、以下のツールエイリアスを参照してください。

リポジトリに MCP サーバーが構成されている場合は、それらのサーバーの特定のツールのみをカスタムエージェントで使用できるようにすることができます。特定の MCP サーバーのツール名の前に、サーバー名の後に /を付けることができます。たとえば、「 some-mcp-server/some-tool 」のように入力します。

      `some-mcp-server/*`を使用して、特定の MCP サーバーからのすべてのツールを明示的に有効にすることもできます。

      VS Code拡張機能のツールでは、拡張機能名をプロキシとして使用できます (`azure.some-extension/some-tool`など)。

        **すべてのツールを無効にする**: 空のリスト (`tools: []`) を使用して、エージェントのすべてのツールを無効にします。

認識できないツール名はすべて無視されるため、製品固有のツールを問題なくエージェントプロファイルで指定できます。

ツールのエイリアス

          カスタム エージェントでは、次のツール エイリアスを使用できます。 すべての別名では、大文字と小文字が区別されません。

| プライマリエイリアス | 互換性のあるエイリアス | クラウドエージェントマッピング | 目的 | | ------------- | -------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | execute | shell、Bash、powershell | シェルツール: bash または powershell | オペレーティングシステムに適したシェルでコマンドを実行します。 | | read | Read、NotebookRead | view | ファイルの内容を読み取ります。 | | edit | Edit、 MultiEdit、 Write、 NotebookEdit | ツールの編集: 例: str_replace, str_replace_editor | LLM の編集を許可します。正確な引数は異なる場合があります。 | | search | Grep、Glob | search | ファイル内のファイルまたはテキストを検索します。 | | agent | custom-agent、Task | "カスタムエージェント" ツール | タスクを実行するために別のカスタムエージェントを呼び出すことができます。 | | web | WebSearch、WebFetch | 現在、クラウドエージェントには適用されません。 | URL からコンテンツをフェッチし、Web 検索を実行できるようにします | | todo | TodoWrite | 現在、クラウドエージェントには適用されません。 | 構造化タスクリストを作成および管理します。現在、クラウドエージェントではサポートされていませんが、 VS Codeでサポートされています。 |

"すぐに使用できる" MCP サーバーのツール名

次の MCP サーバーは、 Copilot クラウドエージェントですぐに使用でき、namespacing を使用して参照できます。

MCP サーバー名	使用可能なツール
`github`	既定では、すべての読み取り専用ツールを使用できますが、サーバーが受け取るトークンのスコープはソースリポジトリになります。

          `github/*`には、それらのすべてが含まれています。または、`github/<tool name>`が MCP サーバードキュメントの値である`<tool name>`を参照できます。 |

| playwright | すべてのプレイライトツールは既定で使用できますが、サーバーは localhost にのみアクセスするように構成されています。 playwright/*には、それらのすべてが含まれています。または、playwright/<tool name>が MCP サーバードキュメントの値である<tool name>を参照できます。デフォルトで、アクセス権を持つトークンのスコープはソースコードリポジトリに限定されています。 |

MCP サーバー構成の詳細

次のサンプルエージェントプロファイルは、MCP サーバーとシークレットが構成されたエージェントを示しています。さらに、YAML frontmatter の tools プロパティで有効にされているのは、MCP サーバーのツールが 1 つだけです。

---
name: my-custom-agent-with-mcp
description: Custom agent description
tools: ['tool-a', 'tool-b', 'custom-mcp/tool-1']
mcp-servers:
  custom-mcp:
    type: 'local'
    command: 'some-command'
    args: ['--arg1', '--arg2']
    tools: ["*"]
    env:
      ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
---

Prompt with suggestions for behavior and output

          `mcp-servers`の エージェント プロファイル プロパティは、Copilot クラウド エージェント用に MCP サーバーを構成するために使用される JSON 構成形式の YAML 表現です。

ほとんどのサブプロパティは、JSON 表現と同じです。次のセクションでは、Copilot クラウドエージェントに関連するカスタムエージェントでの MCP 構成の初期実装からの変更について説明します。 JSON 構成形式の詳細については、モデルコンテキストプロトコル (MCP) を使用した GitHub Copilot クラウドエージェントの拡張を参照してください。

MCP サーバーの種類

互換性のために、Claude Code と stdio で使用されるVS Code型は、クラウドエージェントのlocal型にマップされます。

MCP サーバー環境変数とシークレット

メモ

MCP サーバーにシークレットまたは環境変数が必要な場合は、Copilotが使用される各リポジトリのカスタムエージェント環境で構成する必要があります。環境変数の設定の詳細については、 AUTOTITLE を参照してください。

          カスタム エージェント MCP 構成では、既存のリポジトリ レベルの MCP 構成と同じ環境変数とシークレット置換機能がサポートされます。 リポジトリ レベルの構成と同様に、シークレットと変数はリポジトリの設定の "copilot" 環境から取得できます。 これらの値を参照するための構文は、 GitHub Actions および Claude Code で使用される一般的なパターンをサポートするように拡張されています。

リポジトリレベルの MCP JSON 構成とカスタムエージェント YAML 構成の両方で、次の構文パターンがサポートされます。

        `$COPILOT_MCP_ENV_VAR_VALUE` - 環境変数とヘッダー

        `${COPILOT_MCP_ENV_VAR_VALUE}` - 環境変数とヘッダー (Claude Code 構文)

        `${COPILOT_MCP_ENV_VAR_VALUE:-default}` - 環境変数とヘッダー (既定値)

        カスタム エージェント YAML 構成では、次の追加構文パターンがサポートされています。

        `${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}` - 環境変数とヘッダー

        `${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}` - 環境変数とヘッダー

          エージェント プロファイル構成の例

次の例は、エージェントプロファイルが、テストの記述やプロジェクトの計画に関連する一般的なタスクにおいてどのように見えるかを示しています。その他のヒントについては、カスタマイズライブラリのカスタム・エージェントの例を参照してください。さらに具体的な例については、 awesome-copilot コミュニティコレクションを参照してください。

テストスペシャリスト

この例では、 tools プロパティを省略して、すべてのツールを有効にします。

Text

---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

実装プランナー

この例では、ツールのサブセットのみを有効にします。

Text

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

          カスタム エージェントの処理

          カスタム・エージェント 名前

名前付けの競合が発生した場合、最下位レベルの構成は上位レベルの構成をオーバーライドします。つまり、リポジトリレベルのエージェントは組織レベルのエージェントよりも優先され、組織レベルのエージェントはエンタープライズレベルのエージェントをオーバーライドします。

バージョン管理

          カスタム エージェント バージョン管理は、 エージェント プロファイル ファイルの Git コミット SHA に基づいています。 これにより、必要に応じて異なるバージョンの カスタム エージェント でブランチまたはタグを作成できます。 タスクにカスタム エージェントを割り当てると、そのリポジトリとブランチの最新バージョンのカスタム エージェントを使用してエージェント プロファイルがインスタンス化されます。 エージェントがプル要求を作成すると、プル要求内の対話では、一貫性のために同じバージョンの カスタム エージェント が使用されます。

ツールの処理

          `tools`の一覧では、組み込みまたは MCP サーバーから提供されるかどうかにかかわらず、エージェントで使用できる一連のツールがフィルター処理されます。 
          エージェント プロファイルでツールを構成する場合の動作は、指定した内容によって異なります。

ツールが指定されていない場合、使用可能なすべてのツールが有効になります
空のツールリスト (tools: []) では、すべてのツールが無効になります
特定のリスト (tools: [...]) では、これらのツールのみが有効になります

MCP サーバーの構成

MCP サーバー構成の場合、適切なオーバーライド動作を保証する特定の処理順序があります。既定の MCP 構成 ( GitHub MCP など) は最初に処理され、次にカスタムエージェント MCP 構成、最後にリポジトリ設定で指定された MCP 構成が処理されます。これにより、各レベルは、必要に応じて前のレベルの設定をオーバーライドできます。

詳細については、次を参照してください。

        [AUTOTITLE](/copilot/how-tos/copilot-cli)

        [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference)

カスタム エージェントの構成

この記事で