Référence de configuration

Les fichiers de configuration des agents personnalisés sont des documents JSON qui définissent le comportement de ces agents. Cette section fournit une vue d’ensemble des concepts de configuration et des modèles courants.

Référence de configuration

Pour obtenir des informations complètes sur le format, les champs disponibles et la syntaxe du fichier de configuration des agents personnalisés, consultez la documentation complémentaire de l’interface de ligne de commande d’Amazon Q Developer :

Vous pouvez également afficher le schéma JSON des fichiers de configuration des agents personnalisés en exécutant :

/agent schema

Concepts de configuration

Les fichiers de configuration des agents personnalisés contiennent plusieurs sections clés qui contrôlent différents aspects du comportement de ces agents :

Métadonnées de base

Chaque agent personnalisé peut inclure des métadonnées de base à des fins d’identification et de documentation :

Configuration des outils

La configuration des outils contrôle les outils mis à la disposition de l’agent personnalisé et leur comportement :

Paramètres des outils intégrés

Le comportement et les autorisations des outils intégrés peuvent être configurés via la section toolsSettings. Chaque outil prend en charge des options de configuration spécifiques qui vous permettent de pré-approuver certaines opérations ou de restreindre l’accès à des ressources spécifiques.

Outil execute_bash

Contrôle les commandes bash qui peuvent être exécutées sans confirmation de l’utilisateur :

{
  "toolsSettings": {
    "execute_bash": {
      "allowedCommands": ["git status", "git fetch"],
      "deniedCommands": ["git commit .*", "git push .*"],
      "allowReadOnly": true
    }
  }
}

Outil fs_read

Contrôle les fichiers et répertoires qui peuvent être lus sans confirmation de l’utilisateur :

{
  "toolsSettings": {
    "fs_read": {
      "allowedPaths": ["~/projects", "./src/**"],
      "deniedPaths": ["/some/denied/path/", "/another/denied/path/**/file.txt"]
    }
  }
}

Outil fs_write

Contrôle les fichiers et les répertoires dans lesquels il est possible d’écrire sans confirmation de l’utilisateur :

{
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["~/projects/output.txt", "./src/**"],
      "deniedPaths": ["/some/denied/path/", "/another/denied/path/**/file.txt"]
    }
  }
}

Outil use_aws

Contrôle les services AWS accessibles sans confirmation de l’utilisateur :

{
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "ec2"],
      "deniedServices": ["eks", "rds"]
    }
  }
}

Autorisations et paramètres par défaut des outils

Les outils intégrés ont différents comportements d’autorisation par défaut :

Les outils peuvent être explicitement autorisés dans la section allowedTools ou configurés avec des autorisations spécifiques via toolsSettings. Si un outil ne figure pas dans la liste allowedTools, les utilisateurs sont invités à fournir une autorisation à moins qu’une configuration toolsSettings appropriée ne soit définie.

Configuration des serveurs MCP

La section mcpServers définit les serveurs Model Context Protocol (MCP) auxquels l’agent personnalisé peut accéder. Chaque configuration de serveur inclut les éléments suivants :

Pour plus d’informations sur l’intégration des serveurs MCP, consultez Utilisation de serveurs MCP avec Amazon Q Developer.

Ressources et contexte

Les agents personnalisés peuvent inclure automatiquement le contexte pertinent grâce à deux mécanismes :

Modèles de configuration courants

Configuration minimale des agents personnalisés

Agent personnalisé simple qui exécute des opérations de base sur des fichiers avec un accès en lecture préapprouvé :

{
"name": "basic-ops",
  "description": "Basic file operations custom agent",
  "prompt": "You are a helpful assistant specialized in basic file operations",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash"
  ],
  "allowedTools": [
    "fs_read"
  ]
}

Agent personnalisé spécialisé pour les flux de travail

Agent personnalisé configuré pour la gestion de l’infrastructure AWS avec des autorisations d’outils spécifiques :

{
"name": "infra-manage",
  "description": "AWS infrastructure management custom agent",
  "prompt": "You are an expert AWS infrastructure specialist",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws"
  ],
  "allowedTools": [
    "fs_read",
    "use_aws"
  ],
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "cloudformation"]
    }
  },
  "resources": [
    "file://README.md",
    "file://infrastructure/**/*.yaml",
    "file://docs/deployment.md"
  ]
}

Agent personnalisé spécifique à un projet avec des hooks

Agent personnalisé qui inclut le contexte du projet par le biais de fichiers statiques et de commandes dynamiques :

{
  "name": "project-dev",
  "description": "Project development custom agent with git context",
  "prompt": "You are a project development assistant with access to git information",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "@git"
  ],
  "allowedTools": [
    "fs_read",
    "@git/git_status"
  ],
  "resources": [
    "file://README.md",
    "file://CONTRIBUTING.md",
    "file://src/**/*.md"
  ],
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status --porcelain",
        "timeout_ms": 10000
      }
    ]
  }
}

Agent personnalisé avec intégration des serveurs MCP

Agent personnalisé qui intègre des outils externes via des serveurs MCP :

{
"name": "custom-dev",
  "description": "Development custom agent with external tool integration",
  "prompt": "You are a development assistant with access to git and web fetching capabilities",
  "mcpServers": {
    "git": {
      "command": "git-mcp-server",
      "args": [],
      "timeout": 30000
    },
    "fetch": {
      "command": "fetch-mcp-server",
      "args": ["--timeout", "10"]
    }
  },
  "tools": [
    "fs_read",
    "fs_write",
    "@git",
    "@fetch/fetch_url"
  ],
  "allowedTools": [
    "fs_read",
    "@git/git_status",
    "@fetch/fetch_url"
  ],
  "toolAliases": {
    "@git/git_status": "status",
    "@fetch/fetch_url": "get"
  }
}