Konfigurationsreferenz

Benutzerdefinierte Agentenkonfigurationsdateien sind JSON-Dokumente, die definieren, wie sich ein benutzerdefinierter Agent verhält. Dieser Abschnitt bietet einen Überblick über Konfigurationskonzepte und gängige Muster.

Konfigurationsreferenz

Vollständige Informationen zum Format der benutzerdefinierten Agentenkonfiguration, zu den verfügbaren Feldern und zur Syntax finden Sie in der ergänzenden Amazon Q Developer CLI-Dokumentation:

• Format der Agentenkonfiguration — Vollständige Referenz für alle Konfigurationsoptionen

• Referenz zu integrierten Tools — Dokumentation zu allen integrierten Tools und ihren Konfigurationsoptionen

Sie können das JSON-Schema für benutzerdefinierte Agentenkonfigurationsdateien auch anzeigen, indem Sie folgenden Befehl ausführen:

/agent schema

Konfigurationskonzepte

Konfigurationsdateien für benutzerdefinierte Agenten enthalten mehrere wichtige Abschnitte, in denen verschiedene Aspekte des Verhaltens benutzerdefinierter Agenten gesteuert werden:

Grundlegende Metadaten

Jeder benutzerdefinierte Agent kann grundlegende Metadaten zur Identifizierung und Dokumentation enthalten:

• Name — Die ID des benutzerdefinierten Agenten (abgeleitet vom Dateinamen, falls nicht angegeben)

• Beschreibung — Für Menschen lesbare Erklärung des Zwecks des benutzerdefinierten Agenten

Konfiguration der Tools

Die Konfiguration der Tools steuert, welche Tools dem benutzerdefinierten Agenten zur Verfügung stehen und wie sie sich verhalten:

Tools

Listet alle Tools auf, die der benutzerdefinierte Agent potenziell verwenden kann, einschließlich integrierter Tools und MCP-Servertools

Zulässige Tools

Gibt an, welche Tools ohne Benutzerbestätigung ausgeführt werden können, wodurch die Effizienz des Workflows verbessert wird

Tool-Aliase

Stellt alternative Namen für Tools bereit, die nützlich sind, um Namenskonflikte zu lösen oder Abkürzungen zu erstellen

Werkzeuge/Einstellungen

Konfiguriert ein bestimmtes Verhalten für einzelne Tools, z. B. zulässige Dateipfade oder Dienstberechtigungen

Konfiguration der MCP-Server

mcpServersIn diesem Abschnitt wird definiert, auf welche Model Context Protocol-Server der benutzerdefinierte Agent zugreifen kann. Jede Serverkonfiguration umfasst:

• Befehl — Der ausführbare Befehl zum Starten des MCP-Servers

• Argumente — Befehlszeilenargumente für den Server

• Umgebungsvariablen — Umgebungseinstellungen für den Serverprozess

• Timeout-Einstellungen — Timeout-Konfiguration anfordern

Weitere Informationen zur MCP-Integration finden Sie unter Verwenden von MCP mit Amazon Q Developer.

Ressourcen und Kontext

Benutzerdefinierte Agenten können mithilfe von zwei Mechanismen automatisch relevanten Kontext einbeziehen:

Ressourcen

Dateien und Verzeichnisse, die in den Kontext des benutzerdefinierten Agenten aufgenommen werden sollen, wobei Glob-Muster für eine flexible Dateiauswahl unterstützt werden

hooks

Befehle, die an bestimmten Triggerpunkten ausgeführt werden (z. B. beim Start eines benutzerdefinierten Agenten oder bei Benutzereingaben), wobei die Ausgabe im Kontext enthalten ist

Allgemeine Konfigurationsmuster

Minimale benutzerdefinierte Agentenkonfiguration

Ein einfacher benutzerdefinierter Agent, der grundlegende Dateioperationen mit vorab genehmigtem Lesezugriff ermöglicht:

{
"name": "basic-ops",
  "description": "Basic file operations custom agent",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash"
  ],
  "allowedTools": [
    "fs_read"
  ]
}

Spezialisierter benutzerdefinierter Workflow-Agent

Ein benutzerdefinierter Agent, der für das AWS-Infrastrukturmanagement mit bestimmten Toolberechtigungen konfiguriert ist:

{
"name": "infra-manage",
  "description": "AWS infrastructure management custom agent",
  "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"
  ]
}

Projektspezifischer benutzerdefinierter Agent mit Hooks

Ein benutzerdefinierter Agent, der den Projektkontext sowohl über statische Dateien als auch über dynamische Befehle einbezieht:

{
  "name": "project-dev",
  "description": "Project development custom agent with git context",
  "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
      }
    ]
  }
}

Benutzerdefinierter Agent mit MCP-Serverintegration

Ein benutzerdefinierter Agent, der externe Tools über MCP-Server integriert:

{
"name": "custom-dev",
  "description": "Development custom agent with external tool integration",
  "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"
  }
}