Konfiguration von benutzerdefinierten Agents

Dieser Referenzartikel enthält ausführliche Konfigurationsinformationen für custom agents. Allgemeine Informationen zum Erstellen custom agentsfinden Sie unter Erstellen von benutzerdefinierten Agents für Copilot cloud agent.

YAML-Frontmattereigenschaften

In der folgenden Tabelle werden die Eigenschaften aufgelistet, die Sie für agent profiles in GitHub.com, Copilot CLI und den unterstützten IDEs konfigurieren können, es sei denn, es wird anders angegeben. Jedes umgebungsspezifische Verhalten wird in der Eigenschaftsbeschreibung angegeben. Der Name der Konfigurationsdatei (minus .md oder .agent.md) wird für die Deduplizierung zwischen Ebenen verwendet, sodass die Konfiguration auf der niedrigsten Ebene Vorrang hat.

Definieren Sie das Verhalten, das Fachwissen und die Anweisungen des Agents im Markdown-Inhalt unter dem YAML-Frontmatter. Die Eingabeaufforderung kann maximal 30.000 Zeichen lang sein.

Tools

Die custom agenttools Eigenschaft steuert, welche Tools für Ihren Agent verfügbar sind, einschließlich der von MCP-Servern.

Ihr custom agent erhält Zugriff auf MCP-Servertools, die sowohl in den agent profile- als auch in den Repositoryeinstellungen konfiguriert wurden. Weitere Informationen zum Konfigurieren von gemeinsam genutzten Repository-MCP-Servern auf GitHub finden Sie unter Konfigurieren von MCP-Servern für Ihr Repository.

Sie können tools mit den folgenden Vorgehensweisen konfigurieren:

• Alle verfügbaren Tools aktivieren: Lassen Sie die tools Eigenschaft vollständig weg oder verwenden Sie tools: ["*"], um alle verfügbaren Tools zu aktivieren. Dazu gehören alle MCP-Server-Tools, die innerhalb der agent profile- und/oder Repository-Einstellungen konfiguriert sind.
• Aktivieren Sie bestimmte Tools: Stellen Sie eine Liste mit bestimmten Toolnamen oder Aliasen bereit (z. B tools: ["read", "edit", "search"]. ), um nur diese Tools zu aktivieren. Verfügbare Toolaliasen finden Sie unten unter Toolaliasen .
  • Beachten Sie, dass Sie, wenn Ihr Repository MCP-Server konfiguriert sind, festlegen können, dass nur bestimmte Tools von diesen Servern für Sie custom agent verfügbar sind. Toolnamen von bestimmten MCP-Servern können dem Servernamen gefolgt von einer /vorangestellt werden. Beispiel: some-mcp-server/some-tool.
  • Sie können auch alle Tools von einem bestimmten MCP-Server mithilfe von some-mcp-server/* explizit aktivieren.
  • Tools aus VS Code Erweiterungen können den Erweiterungsnamen als Proxy verwenden, z. B. azure.some-extension/some-tool.
• Alle Tools deaktivieren: Verwenden Sie eine leere Liste (tools: []), um alle Tools für den Agent zu deaktivieren.

Alle nicht erkannten Toolnamen werden ignoriert, wodurch produktspezifische Tools in einem agent profile angegeben werden können, ohne Probleme zu verursachen.

Tool-Aliasse

Die folgenden Tool-Aliase sind für custom agents verfügbar. Bei allen Aliasen wird die Groß- und Kleinschreibung nicht berücksichtigt:

| Primärer Alias | Kompatible Aliase | Cloud agent Zuordnung | Zweck | | ------------- | -------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | execute | shell, Bash``powershell | Shelltools: bash oder powershell | Führen Sie einen Befehl in der entsprechenden Shell für das Betriebssystem aus. | | read | Read, NotebookRead | view | Dateiinhalte lesen. | | edit | Edit MultiEdit Write NotebookEdit | Bearbeitungstools: z. B. str_replace, str_replace_editor | Dem LLM die Möglichkeit zur Bearbeitung bieten. Genaue Argumente können variieren. | | search | Grep, Glob | search | Suchen Sie nach Dateien oder Text in Dateien. | | agent | custom-agent, Task | Custom agent" Werkzeuge | Ermöglicht das Aufrufen eines anderen custom agent, um eine Aufgabe auszuführen. | | web | WebSearch, WebFetch | Derzeit nicht anwendbar für cloud agent. | Ermöglicht das Abrufen von Inhalten aus URLs und durchführen einer Websuche | | todo | TodoWrite | Derzeit nicht anwendbar für cloud agent. | Erstellt und verwaltet strukturierte Aufgabenlisten. Wird heute in cloud agent nicht unterstützt, aber von VS Code. |

Toolnamen für einsatzbereite MCP-Server

Die folgenden MCP-Server sind sofort einsatzbereit für Copilot cloud agent und können mithilfe von Namespacing referenziert werden.

MCP-Serverkonfigurationsdetails

Das folgende Beispiel agent profile zeigt einen Agenten mit einem MCP-Server und einem Secret. Darüber hinaus wurde nur ein Tool vom MCP-Server in der tools Eigenschaft im YAML-Frontmatter aktiviert:

---
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

Die Eigenschaft mcp-servers in einem agent profile ist eine YAML-Darstellung des JSON-Konfigurationsformats, das zum Konfigurieren von MCP-Servern für Repositorys auf GitHub verwendet wird.

Die meisten Untereigenschaften sind identisch mit der JSON-Darstellung. In den folgenden Abschnitten werden Änderungen gegenüber der ursprünglichen Implementierung der MCP-Konfiguration in Repositories auf GitHub beschrieben, die für custom agents relevant sind. Weitere Informationen zum JSON-Konfigurationsformat finden Sie unter Konfigurieren von MCP-Servern für Ihr Repository.

MCP-Servertyp

Aus Kompatibilitätsgründen wird der von stdio Claude Code verwendete Typ und VS Code dem Typ von cloud agents local zugeordnet.

MCP-Serverumgebungsvariablen und geheime Schlüssel

Custom agent DIE MCP-Konfiguration unterstützt die gleichen Umgebungsvariablen und geheimen Ersatzfunktionen wie vorhandene MCP-Konfigurationen auf Repositoryebene. Ähnlich wie bei Konfigurationen auf Repository-Ebene können Geheimnisse und Variablen aus Agentengeheimnissen und -variablen für Copilot cloud agent bezogen werden, die entweder auf Organisations- oder Repository-Ebene konfiguriert sind. Die Syntax zum Verweisen auf diese Werte wurde erweitert, um allgemeine Muster zu unterstützen, die in GitHub Actions und Claude Code verwendet werden.

Sowohl die MCP-JSON-Konfiguration auf Repositoryebene als auch die custom agent YAML-Konfiguration unterstützen die folgenden Syntaxmuster:

• $COPILOT_MCP_ENV_VAR_VALUE - Umgebungsvariable und Header
• ${COPILOT_MCP_ENV_VAR_VALUE} - Umgebungsvariable und Header (Claude Code-Syntax)
• ${COPILOT_MCP_ENV_VAR_VALUE:-default} - Umgebungsvariable und Header mit Standardeinstellung

Die custom agent YAML-Konfiguration unterstützt die folgenden zusätzlichen Syntaxmuster:

• ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }} - Umgebungsvariable und Header
• ${{ vars.COPILOT_MCP_ENV_VAR_VALUE }} - Umgebungsvariable und Header

Beispielkonfigurationen agent profile

Die folgenden Beispiele veranschaulichen, wie ein agent profile für die gewöhnlichen Aufgaben, Tests zu schreiben oder die Implementierung eines Projekts zu planen, aussehen könnte. Weitere Inspiration finden Sie in den Custom agents Beispielen in der Anpassungsbibliothek. Sie finden auch spezifischere Beispiele in der awesome-copilot Community Collection.

Prüffachmann

In diesem Beispiel werden alle Tools aktiviert, indem die tools Eigenschaft weggelassen wird.

---
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.

Implementierungsplaner

In diesem Beispiel wird nur eine Teilmenge von Tools aktiviert.

---
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.

Verarbeitung von custom agents

Custom agents Namen

Bei Benennungskonflikten überschreibt die Konfiguration auf der niedrigsten Ebene Konfigurationen auf höherer Ebene. Dies bedeutet, dass ein Agent auf Repositoryebene Vorrang vor einem Agent auf Organisationsebene hat und der Agent auf Organisationsebene einen Agent auf Unternehmensebene außer Kraft setzen würde.

Versionsverwaltung

Custom agent Die Versionierung basiert auf den Git-Commit-SHAs für die Datei agent profile. Auf diese Weise können Sie Verzweigungen oder Tags mit unterschiedlichen Versionen von custom agents nach Bedarf erstellen. Wenn Sie einer Aufgabe ein custom agent zuweisen, wird die custom agent mithilfe der neuesten Version des agent profile-Repositorys und der jeweiligen Verzweigung instanziiert. Wenn der Agent einen Pull-Request erstellt, verwenden Interaktionen innerhalb des Pull-Requests dieselbe Version der custom agent zur Konsistenz.

Werkzeugverarbeitung

In tools der Liste werden die Tools gefiltert, die dem Agent zur Verfügung gestellt werden – unabhängig davon, ob sie von MCP-Servern integriert oder stammen. Wenn Sie Tools in Ihrem agent profileDokument konfigurieren, hängt das Verhalten davon ab, was Sie angeben:

• Wenn keine Tools angegeben sind, sind alle verfügbaren Tools aktiviert.
• Eine leere Toolsliste (tools: []) deaktiviert alle Tools.
• Eine bestimmte Liste (tools: [...]) aktiviert nur diese Tools.

MCP-Serverkonfigurationen

Für MCP-Serverkonfigurationen gibt es eine bestimmte Verarbeitungsreihenfolge, die ein ordnungsgemäßes Überschreibungsverhalten gewährleistet: out-of-the-box MCP-Konfigurationen (wie die GitHub MCP) werden zuerst verarbeitet, gefolgt von der custom agent MCP-Konfiguration und schließlich MCP-Konfigurationen, die über Repositoryeinstellungen angegeben wurden. Auf diese Weise kann jede Ebene Einstellungen von der vorherigen Ebene entsprechend außer Kraft setzen.

Weiterführende Lektüre

• GitHub Copilot CLI
• GitHub Copilot CLI-Befehlsreferenz