Configuration des agents personnalisés

Cet article de référence fournit des informations de configuration détaillées pour agents personnalisés. Pour obtenir des informations générales sur la création agents personnalisés, consultez Création d’agents personnalisés pour agent Copilot de cloud.

Propriétés frontmatter YAML

Le tableau suivant présente les propriétés que vous pouvez configurer pour profils d’agent dans GitHub.com, le CLI Copilot, et les IDEs pris en charge (sauf indication contraire). Tout comportement spécifique à l’environnement est noté dans la description de la propriété. Le nom du fichier de configuration (moins .md ou .agent.md) est utilisé pour la déduplication entre les niveaux afin que la configuration de niveau le plus bas soit prioritaire.

          **Chaîne requise**     | Description de l’objectif assistant personnaliséet des fonctionnalités |

Définissez le comportement, l’expertise et les instructions de l’agent dans le contenu Markdown sous le frontmatter YAML. L’invite peut comporter au maximum 30 000 caractères.

Tools

La assistant personnalisétools propriété contrôle les outils disponibles pour votre agent, y compris ceux des serveurs MCP.

Vous assistant personnalisé aurez accès aux outils serveur MCP qui ont été configurés à la fois dans ses profil d’agent paramètres et/ou dans le référentiel. Pour plus d’informations sur la configuration des serveurs MCP pour l’agent cloud dans un référentiel, consultez Extension GitHub Copilot agent cloud avec le protocole MCP (Model Context Protocol).

Vous pouvez configurer tools à l’aide des approches suivantes :

•         **Activez tous les outils disponibles** : omettez entièrement la `tools` propriété ou utilisez `tools: ["*"]` pour activer tous les outils disponibles. Cela inclut tous les outils serveur MCP configurés dans les paramètres de profil d’agent et/ou du référentiel.
  

•         **Activer des outils spécifiques** : fournissez une liste de noms d’outils ou d’alias spécifiques (par exemple `tools: ["read", "edit", "search"]`) pour activer uniquement ces outils. Pour connaître les alias d’outils disponibles, voir [Alias d’outil](#tool-aliases) ci-dessous.
  

  • Notez que si votre référentiel dispose de serveurs MCP configurés, vous pouvez choisir de rendre uniquement des outils spécifiques à partir de ces serveurs disponibles pour votre assistant personnalisé. Les noms d’outils provenant de serveurs MCP spécifiques peuvent être précédés du nom du serveur suivi d’un /. Par exemple : some-mcp-server/some-tool.
  • Vous pouvez également activer explicitement tous les outils d’un serveur MCP spécifique en utilisant some-mcp-server/*.
  • Les outils des extensions peuvent utiliser le nom de l’extension VS Code comme un proxy, comme azure.some-extension/some-tool.

•         **Désactivez tous les outils** : utilisez une liste vide (`tools: []`) pour désactiver tous les outils de l’agent.
  

Tous les noms d’outils non reconnus sont ignorés, ce qui permet aux outils spécifiques au produit d’être spécifiés dans un profil d’agent outil sans provoquer de problèmes.

Alias d’outil

Les alias d’outil suivants sont disponibles pour agents personnalisés. Tous les alias sont insensibles à la casse :

| Alias principal | Alias compatibles | Agent de cloud Cartographie | Objectif | | ------------- | -------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | execute | shell Bash powershell | Outils Shell : bash ou powershell | Exécutez une commande dans l’interpréteur de commandes approprié pour le système d’exploitation. | | read | Read, NotebookRead | view | Lire le contenu du fichier. | | edit | Edit MultiEdit Write NotebookEdit | Modifier les outils : par exemple str_replace, str_replace_editor | Autoriser LLM à modifier. Les arguments exacts peuvent varier. | | search | Grep, Glob | search | Recherchez des fichiers ou du texte dans des fichiers. | | agent | custom-agent, Task | « Agent personnalisé » outils | Permet à une autre assistant personnalisé d’être appelée pour accomplir une tâche. | | web | WebSearch, WebFetch | Actuellement non applicable pour agent de cloud. | Permet d’extraire du contenu à partir d’URL et d’effectuer une recherche web | | todo | TodoWrite | Actuellement non applicable pour agent de cloud. | Crée et gère des listes de tâches structurées. Non pris en charge dans agent de cloud aujourd’hui, mais pris en charge par VS Code. |

Noms d’outils pour les serveurs MCP « clé en main »

Les serveurs MCP suivants sont disponibles prêts à agent Copilot de cloud l'emploi et peuvent être référencés à l'aide de l'utilisation de namespaces :

          `github/*` inclut tous ces éléments, ou vous pouvez référencer `github/<tool name>` où `<tool name>` est une valeur provenant de la documentation du serveur MCP. |

| playwright | Tous les outils playwright sont disponibles par défaut, mais le serveur est configuré pour accéder uniquement à localhost. playwright/* inclut tous ces éléments, ou vous pouvez référencer playwright/<tool name> où <tool name> est une valeur provenant de la documentation du serveur MCP. Par défaut, le jeton dont il a accès est limité au référentiel de code source. |

Détails de la configuration du serveur MCP

L’exemple profil d’agent suivant montre un agent avec un serveur MCP et un secret configuré. En outre, un seul outil du serveur MCP a été activé dans la tools propriété dans le frontmatter YAML :

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

La mcp-servers propriété dans un profil d’agent est une représentation YAML du format de configuration JSON utilisé pour configurer des serveurs MCP pour agent Copilot de cloud.

La plupart des sous-propriétés sont identiques à la représentation JSON. Les sections suivantes décrivent les modifications de l’implémentation initiale de la configuration MCP dans agent Copilot de cloud qui sont pertinentes pour agents personnalisés. Pour plus d’informations sur le format de configuration JSON, consultez Extension GitHub Copilot agent cloud avec le protocole MCP (Model Context Protocol).

Type de serveur MCP

Pour la compatibilité, le stdio type utilisé par Claude Code et VS Code est associé au type agent de cloud de local.

Variables et secrets d’environnement de serveur MCP

          Agent personnalisé La configuration MCP prend en charge les mêmes fonctionnalités de remplacement de variable d’environnement et de secret que les configurations MCP au niveau du référentiel existantes. Comme pour les configurations au niveau du référentiel, les secrets et les variables peuvent être sources à partir de l’environnement « copilot » dans les paramètres du référentiel. La syntaxe de référencement de ces valeurs a été développée pour prendre en charge les modèles courants utilisés dans GitHub Actions et Claude Code.

La configuration JSON MCP au niveau du référentiel et la assistant personnalisé configuration YAML prennent en charge les modèles de syntaxe suivants :

•         `$COPILOT_MCP_ENV_VAR_VALUE` - Variable et en-tête d’environnement
  

•         `${COPILOT_MCP_ENV_VAR_VALUE}` - Variable et en-tête d’environnement (syntaxe Claude Code)
  

•         `${COPILOT_MCP_ENV_VAR_VALUE:-default}` - Variable d’environnement et en-tête par défaut
  

La assistant personnalisé configuration YAML prend en charge les modèles de syntaxe supplémentaires suivants :

•         `${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}` - Variable et en-tête d’environnement
  

•         `${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}` - Variable et en-tête d’environnement
  

Exemples de profil d’agent configurations

Les exemples suivants montrent ce qu’un profil d’agent pourrait ressembler aux tâches courantes d’écriture de tests ou de planification de l’implémentation d’un projet. Pour vous inspirer davantage, consultez les exemples Agents personnalisés dans la bibliothèque de personnalisation. Vous trouverez également des exemples plus spécifiques dans la collection awesome-copilot de la communauté.

Spécialiste des tests

Cet exemple active tous les outils en omettant la tools propriété.

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

Planificateur d’implémentation

Cet exemple active uniquement un sous-ensemble d’outils.

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

Traitement de agents personnalisés

          Agents personnalisés prénoms

En cas de conflits d’affectation de noms, la configuration de niveau le plus bas remplace les configurations de niveau supérieur. Cela signifie qu’un agent au niveau du référentiel est prioritaire sur un agent au niveau de l’organisation et que l’agent au niveau de l’organisation remplace un agent au niveau de l’entreprise.

Gestion des versions

          Agent personnalisé Le versionnage est basé sur les SHA de commit Git pour le fichier profil d’agent. Cela vous permet de créer des branches ou des balises avec différentes versions de agents personnalisés si nécessaire. Lorsque vous affectez à une assistant personnalisé tâche, la création assistant personnalisé sera effectuée à l'aide de la dernière version de profil d’agent pour ce référentiel et cette branche. Lorsque l’agent crée une requête de tirage, les interactions au sein de cette requête utilisent la même version de la assistant personnalisé pour cohérence.

Traitement des outils

La tools liste filtre l’ensemble d’outils mis à la disposition de l’agent , qu’ils soient intégrés ou sources à partir de serveurs MCP. Lorsque vous configurez des outils dans votre profil d’agent, le comportement dépend de ce que vous spécifiez :

• Si aucun outil n’est spécifié, tous les outils disponibles sont activés
• Une liste d’outils vide (tools: []) désactive tous les outils
• Une liste spécifique (tools: [...]) active uniquement ces outils

Configurations du serveur MCP

Pour les configurations de serveur MCP, il existe un ordre de traitement spécifique qui garantit un comportement de remplacement approprié : les configurations MCP prêtes à l’emploi (comme mcP GitHub ) sont traitées en premier, suivies de la assistant personnalisé configuration MCP et enfin des configurations MCP spécifiées par le biais des paramètres de référentiel. Cela permet à chaque niveau de remplacer les paramètres du niveau précédent selon les besoins.

Lectures complémentaires

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

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