Erstellen und Verwenden von benutzerdefinierten Agenten für GitHub Copilot CLI

Erstellen Sie spezialisierte Agenten mit maßgeschneiderter Expertise für spezifische Entwicklungsaufgaben.

In diesem Artikel

Einleitung

Custom agents ermöglicht es Ihnen, die Expertise von Copilot auf bestimmte Aufgaben zuzuschneiden.

Wenn Sie Copilot dazu auffordern, eine Aufgabe auszuführen, kann es sich entscheiden, eine Ihrer custom agents zu nutzen, wenn Copilot feststellt, dass das Fachwissen des Agenten gut für die Aufgabe geeignet ist.

Wenn der Haupt-Agent Arbeit an einen custom agent delegiert, wird diese Arbeit von einem Subagenten mit einem eigenen Kontextfenster ausgeführt. Dadurch kann sich der Spezialist auf seine zugewiesene Aufgabe konzentrieren, ohne den Kontext des Hauptagenten zu überladen. Sie können auch eine custom agent für die Sitzung direkt auswählen.

Weitere Informationen finden Sie unter Benutzerdefinierte Agents.

Erstellen einer custom agent

Jede custom agent wird durch eine Markdown-Datei mit einer .agent.md Erweiterung definiert. Sie können diese Dateien selbst erstellen oder sie aus der CLI hinzufügen, wie in den folgenden Schritten beschrieben.

  1. Geben Sie /agentim interaktiven Modus ein.

  2. Drücken Sie N, um einen neuen Agent zu erstellen.

  3. Wählen Sie zwischen den Optionen, ob Sie das custom agent im Repository oder im Heimverzeichnis erstellen möchten:

    • Project (.github/agents/)

    • Benutzer (~/.copilot/agents/)

    Hinweis

    Wenn die persönliche und die Repository-custom agents dieselbe ID haben, wird der persönliche Agent verwendet. Für einen Agenten im Stammverzeichnis eines agents-Verzeichnisses ist die ID der Dateiname ohne die Erweiterung .agent.md oder .md. Das optionale name Feld wirkt sich nicht auf die Deduplizierung aus. Agents mit demselben name, aber unterschiedlichen IDs werden beide geladen; wenn ein --agent-Wert jedoch mit mehr als einer ID oder name übereinstimmt, verwendet die CLI den Treffer mit der höchsten Priorität.

  4. Wählen Sie aus, ob Copilot die custom agent-Datei erstellen soll oder ob Sie sie selbst erstellen möchten.

Option 1: Verwenden Copilot

Geben Sie Details des Agents ein, den Sie erstellen möchten. Beschreiben Sie das Know-how des Agenten und wann der Agent verwendet werden soll. Copilot wird die von Ihnen eingegebene Beschreibung übernehmen und zum Schreiben eines Agentprofils für Sie verwenden.

Sie könnten beispielsweise eingeben:

I am a security expert. I check code files thoroughly for potential security issues. Use me whenever a security review/check/audit is requested for one or more code files, or when the word "seccheck" is used in a prompt in reference to code files.

I will identify potential problems, such as code that:

- Exposes secrets or credentials
- Allows cross-site scripting
- Allows SQL injection
- Contains vulnerable dependencies
- Allows authentication to be bypassed

If any problems are identified, create a single GitHub issue in this repository on GitHub.com with details of problems, giving full details of each issue, including, but not limited to, risk level and recommended fix.

Nach Copilot Abschluss des Generierens des ersten Agentprofils werden die folgenden Optionen angezeigt:

  • Weiter
  • Inhalt überprüfen
  • Noch mal versuchen
  • Beenden

Wenn Sie den Inhalt überprüfen möchten, wird die Agentdatei in Ihrem Standard-Editor geöffnet. Sie können ggf. Änderungen überprüfen und vornehmen, bevor Sie den Agenterstellungsprozess in der CLI fortsetzen.

Um den Erstellungsprozess abzuschließen, wählen Sie "Weiter" aus.

Option 2: Manuelles Erstellen des Agentprofils

Wenn Sie sich dafür entscheiden, die Agentdatei selbst zu erstellen, werden Sie durch eine Reihe von Eingabeaufforderungen geführt, um die erforderlichen Informationen auszufüllen, um das Agentprofil zu erstellen.

  1. Geben Sie einen Namen für den Agent ein. Der eingegebene Name ist der Name, der angezeigt wird, wenn Sie die verfügbaren Agents auflisten. Eine Version davon wird als Name der Agentdatei verwendet, z. B. wenn Sie "Sicherheitsexperte" eingeben, wird die Agentdatei benannt security-expert.agent.md.

    Tipp

    Für eine einfache Nutzung eines custom agent empfiehlt es sich, einen Namen auszuwählen, der nur aus Kleinbuchstaben und Bindestrichen besteht.

  2. Geben Sie eine Beschreibung ein, die angibt, welche Expertise dieser Agent hat und wann es verwendet werden soll.

  3. Geben Sie Anweisungen für das Verhalten des Agents ein, einschließlich aller spezifischen Richtlinien, Aktionen, die er ergreifen sollte, oder Einschränkungen, die er befolgen sollte.

  4. Wählen Sie, auf welche Werkzeuge Ihr custom agent Zugriff haben sollte.

    Standardmäßig haben Sie, custom agents, Zugriff auf alle Tools. Wenn Sie den Zugriff eines Agents einschränken, wird der Agentdatei eine tools Spezifikation hinzugefügt.

  5. Starten Sie die CLI neu, um das neue custom agentzu laden.

Verwenden eines custom agent

Custom agents kann auf folgende Weise verwendet werden:

  • Slash-Befehl

    Geben Sie /agent im interaktiven Modus ein, und wählen Sie aus der Liste der verfügbaren custom agents. Geben Sie dann eine Eingabeaufforderung ein, die an den ausgewählten Agent übergeben wird.

    Hinweis

    Die Standard-Agents der CLI sind in dieser Liste nicht enthalten. Weitere Informationen zu den Standard-Agents finden Sie unter Benutzerdefinierte Agents.

  • Explizite Anweisung

    Weisen Sie Copilot an, einen bestimmten Agent zu verwenden. Beispiel:

    Use the security-auditor agent on all files in the /src/app directory

  • Nach Rückschlüssen

    Verwenden Sie eine Eingabeaufforderung, die die Verwendung eines bestimmten Agents basierend auf der Beschreibung in der Agentdatei auslöst. Beispiel:

    Check all TypeScript files in or under the src directory for potential security problems

    oder (wobei "seccheck" als Triggerwort im Agentprofil definiert ist):

    seccheck /src/app/validator.go

Copilot leitet automatisch den Agent ab, den Sie verwenden möchten.

  • Programmgesteuert

    Geben Sie custom agent an, das Sie mit der Befehlszeilenoption verwenden möchten. Beispiel:

    copilot --agent security-auditor --prompt "Check /src/app/validator.go"

    In diesem Beispiel security-auditor ist die ID der custom agent. Die ID wird aus dem Dateinamen abgeleitet, ohne die Erweiterung .md oder .agent.md. In diesem Fall ist der Pfad zu der Datei entweder agents/security-auditor.md oder agents/security-auditor.agent.md. Wenn sich die Datei in einem Unterverzeichnis von agentsbefindet, ist der Unterverzeichnisname in der ID enthalten, wobei das Verzeichnistrennzeichen durch --ersetzt wird. Daher hätte eine Agentendatei unter agents/security/security-auditor.agent.md die ID security--security-auditor. Alternativ können Sie den Wert des name Felds anstelle der ID verwenden und in Anführungszeichen setzen. Beispiel: --agent "Security Auditor"

Delegieren von fokussierten Aufgaben an ein bestimmtes Modell

Sie können eine custom agent für die Verwendung eines bestimmten Modells konfigurieren.

Dies kann besonders hilfreich sein, wenn Sie kleine, gut definierte Aufgaben an einen custom agent delegieren möchten, der ein lokal gehostetes Modell verwendet, während Sie ein cloudbasiertes Modell für Ihre Hauptsitzung verwenden. Mit diesem Ansatz können Sie z. B. eine Einzeldateiänderung oder eine fokussierte Testkorrektur an ein custom agent, das ein lokales Modell verwendet, delegieren und dann den Haupt-Agenten das Ergebnis überprüfen lassen.

Fügen Sie zunächst der CLI ein lokal gehostetes Modell hinzu. Siehe Hinzufügen von LLM-Modellen zu GitHub Copilot CLI.

  1. Erstellen Sie ~/.copilot/agents/local-coder.agent.md mit dem folgenden Inhalt:

    ---
name: local-coder
description: >
  Use for small, well-defined coding tasks, such as a
  single-file change or a focused test fix.
model: LOCAL-PROVIDER/LOCAL-MODEL
model-policy: required
tools: ["read", "grep", "glob", "edit", "execute"]
strict-tools-list: true
include-custom-instructions: true
---

Complete only the requested task. Inspect the relevant
code, make the smallest correct change, and run focused
checks. Report what changed and any remaining issues.

  2. Ersetzen Sie LOCAL-PROVIDER/LOCAL-MODEL durch die anbieterqualifizierte ID Ihres lokalen Modells, nicht durch den Anzeigenamen. Kombinieren Sie bei einem Modell in providers.json die Werte id und provider des Modelleintrags, getrennt durch einen Schrägstrich. Zum Beispiel ergeben local/qwen3:8b und "provider": "local"``"id": "qwen3:8b".

model-policy: required erfordert das konfigurierte Modell, anstatt es als Einstellung zu behandeln.

strict-tools-list: true beschränkt den Agent auf die aufgeführten Toolgruppen, ohne die üblichen Standardtools hinzuzufügen.

include-custom-instructions: true hält die Anweisungen Ihres Repositorys für den Subagenten wirksam.

  1. Starten Sie die CLI neu, um den Agent zu laden. Delegieren Sie in einer Sitzung mit einem Cloudmodell explizit eine abgegrenzte Aufgabe:

    Use the local-coder agent to add an empty-input test for
parseConfig in src/config.test.ts. Do not change other
files. Then review the result in the main session.

    Das lokale Modell führt die delegierte Aufgabe aus, aber der Haupt-Agent empfängt weiterhin das Ergebnis. Das bedeutet nicht, dass die gesamte Sitzung lokal oder offline ist.

Benutzerdefinierte Anweisungen Ihres Repositorys auf ein custom agent anwenden

Dateien mit benutzerdefinierten Anweisungen – wie .github/copilot-instructions.md, AGENTS.md und CLAUDE.md – teilen Copilot mit, wie es in Ihrem Repository vorgehen soll. Weitere Informationen finden Sie unter Hinzufügen von benutzerdefinierten Repositoryanweisungen für GitHub Copilot.

Wenn Copilot Ihr custom agent als Subagent ausführt, um einen Teil einer größeren Aufgabe zu übernehmen, befolgt der Subagent standardmäßig nicht die benutzerdefinierten Anweisungen Ihres Repositorys. Dadurch bleibt der Subagent auf die spezifische Aufgabe konzentriert, die ihm zugewiesen wurde.

Wenn Sie möchten, dass ein Unteragent den Konventionen Ihres Repositorys folgt – zum Beispiel ein Agent, der Code überprüft oder bearbeitet –, fügen Sie include-custom-instructions: true zum Frontmatter der Agentdatei hinzu:

---
name: RepoAwareReviewer
description: Reviews a change against this repository's conventions
tools: ["*"]
include-custom-instructions: true
---

Review the change and flag anything that violates the repository's conventions.

Hinweis

Diese Einstellung wirkt sich nur auf den Agent aus, wenn er als Subagent ausgeführt wird. Ein custom agent, das Sie selbst auswählen – mit --agent, /agent oder per Inferenz –, folgt bereits den benutzerdefinierten Anweisungen Ihres Repositorys, daher hat die Einstellung in diesem Fall keine Wirkung.

Weitere Informationen, einschließlich der Interaktion dieser Einstellung mit der --no-custom-instructions Option, finden Sie unter GitHub Copilot CLI-Befehlsreferenz.

Weiterführende Lektüre