Konfiguration von benutzerdefinierten Agents

Dieser Referenzartikel enthält ausführliche Konfigurationsinformationen für Benutzerdefinierte Agenten. Allgemeine Informationen zum Erstellen Benutzerdefinierte Agentenfinden Sie unter Erstellen von benutzerdefinierten Agents für Copilot Cloudagent.

YAML-Frontmattereigenschaften

In der folgenden Tabelle werden die Eigenschaften aufgelistet, die Sie für Agentenprofile 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.

          **Erforderliche** Zeichenfolge     | Beschreibung des Zwecks und der Benutzerdefinierter AgentFunktionen |

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 Benutzerdefinierter Agenttools Eigenschaft steuert, welche Tools für Ihren Agent verfügbar sind, einschließlich der von MCP-Servern.

Ihr Benutzerdefinierter Agent erhält Zugriff auf MCP-Servertools, die sowohl in den Agentprofil- als auch in den Repositoryeinstellungen konfiguriert wurden. Weitere Informationen zum Konfigurieren von MCP-Servern für Cloud-Agent in einem Repository finden Sie unter Das Erweitern des GitHub Copilot Cloud-Agenten mit dem Model Context Protocol (MCP).

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 Agentprofil- 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](#tool-aliases) .
  

  • Beachten Sie, dass Sie, wenn Ihr Repository MCP-Server konfiguriert sind, festlegen können, dass nur bestimmte Tools von diesen Servern für Sie Benutzerdefinierter 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 Agentprofil angegeben werden können, ohne Probleme zu verursachen.

Tool-Aliasse

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

| Primärer Alias | Kompatible Aliase | Cloudagent 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 | Benutzerdefinierter Agent" Werkzeuge | Ermöglicht das Aufrufen eines anderen Benutzerdefinierter 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 Cloudagent und können mithilfe von Namespacing referenziert werden.

          `github/*` enthält alle Elemente, oder Sie können `github/<tool name>` referenzieren, wo `<tool name>` ein Wert aus der MCP-Serverdokumentation ist. |

| playwright | Alle Playwright-Tools sind standardmäßig verfügbar, der Server ist jedoch nur für den Zugriff auf localhost konfiguriert. playwright/* enthält alle Elemente, oder Sie können playwright/<tool name> referenzieren, wo <tool name> ein Wert aus der MCP-Serverdokumentation ist. Standardmäßig ist das Token, auf das es Zugriff hat, auf das Quellcode-Repository festgelegt. |

MCP-Serverkonfigurationsdetails

Das folgende Beispiel Agentprofil 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 mcp-servers Eigenschaft in einer Agentprofil ist eine YAML-Darstellung des JSON-Konfigurationsformats für die Konfiguration von MCP-Servern für Copilot Cloudagent.

Die meisten Untereigenschaften sind identisch mit der JSON-Darstellung. In den folgenden Abschnitten werden Änderungen aus der anfänglichen Implementierung der MCP-Konfiguration in Copilot Cloudagent beschrieben, die für Benutzerdefinierte Agenten relevant sind. Weitere Informationen zum JSON-Konfigurationsformat finden Sie unter Das Erweitern des GitHub Copilot Cloud-Agenten mit dem Model Context Protocol (MCP).

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

          Benutzerdefinierter Agent DIE MCP-Konfiguration unterstützt die gleichen Umgebungsvariablen und geheimen Ersatzfunktionen wie vorhandene MCP-Konfigurationen auf Repositoryebene. Ähnlich wie Konfigurationen auf Repositoryebene können geheime Schlüssel und Variablen aus der "copilot"-Umgebung in den Einstellungen des Repositorys stammen. 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 Benutzerdefinierter 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 Benutzerdefinierter 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 Agentprofil

Die folgenden Beispiele veranschaulichen, wie ein Agentprofil 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 Benutzerdefinierte 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 Benutzerdefinierte Agenten

          Benutzerdefinierte 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

          Benutzerdefinierter Agent Die Versionierung basiert auf den Git-Commit-SHAs für die Datei Agentprofil. Auf diese Weise können Sie Verzweigungen oder Tags mit unterschiedlichen Versionen von Benutzerdefinierte Agenten nach Bedarf erstellen. Wenn Sie einer Aufgabe ein Benutzerdefinierter Agent zuweisen, wird die Benutzerdefinierter Agent mithilfe der neuesten Version des Agentprofil-Repositorys und der jeweiligen Verzweigung instanziiert. Wenn der Agent einen Pull-Request erstellt, verwenden Interaktionen innerhalb des Pull-Requests dieselbe Version der Benutzerdefinierter 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 AgentprofilDokument 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 Benutzerdefinierter 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

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

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