組態參考 - Amazon Q Developer
組態參考組態概念常見的組態模式

組態參考

自訂代理程式組態檔案是定義自訂代理程式行為的 JSON 文件。本節提供組態概念和常見模式的概觀。

組態參考

如需自訂代理程式組態檔案格式、可用欄位和語法的完整詳細資訊，請參閱補充的 Amazon Q Developer CLI 文件：

您也可以執行下列操作來檢視自訂代理程式組態檔案的 JSON 結構描述：

/agent schema

組態概念

自訂代理程式組態檔案包含數個主要區段，可控制自訂代理程式行為的不同層面：

基本中繼資料

每個自訂代理程式都可包含用於識別和文件的基本中繼資料：

  • 名稱 - 自訂代理程式的識別符 (若未指定，則會從檔案名稱衍生)

  • 描述 - 可供人閱讀的自訂代理程式用途說明

  • 提示 - 代理程式的高階內容，類似系統提示

工具組態

工具組態可控制自訂代理程式可用哪些工具及這些工具的行為：

工具

列出自訂代理程式可能會使用的所有工具，包括內建工具和 MCP 伺服器工具

allowedTools

指定哪些工具不需使用者確認即可執行，以提高工作流程效率

toolAliases

提供工具的替代名稱，有助於解決命名衝突或建立捷徑

toolsSettings

設定個別工具的特定行為，例如允許的檔案路徑或服務許可

內建工具設定

內建工具可以透過 toolsSettings 區段進行設定，以控制其行為和許可。每個工具都支援特定組態選項，可讓您預先核准特定操作或限制對特定資源的存取。

execute_bash 工具

控制哪些 bash 命令不需使用者確認即可執行：

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

不需提示即允許的特定命令陣列。支援使用錨點 \A 和 \z 的 regex 格式。

deniedCommands

要拒絕的命令陣列。支援 regex 格式。拒絕規則會在允許規則之前評估。

allowReadOnly

布林值 (預設值：true) - 是否允許唯讀命令而不提示。

fs_read 工具

控制哪些檔案和目錄不需使用者確認即可讀取：

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

不需提示即可讀取的路徑陣列。支援具有 gitignore 樣式行為的 glob 模式。

deniedPaths

要拒絕存取的路徑陣列。支援 glob 模式。拒絕規則會在允許規則之前評估。

fs_write 工具

控制哪些檔案和目錄不需使用者確認即可寫入：

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

不需提示即可寫入的路徑陣列。支援具有 gitignore 樣式行為的 glob 模式。

deniedPaths

要拒絕寫入存取的路徑陣列。支援 glob 模式。拒絕規則會在允許規則之前評估。

use_aws 工具

控制哪些 AWS 服務不需使用者確認即可存取：

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

不需提示即可存取的 AWS 服務陣列。

deniedServices

要拒絕存取的 AWS 服務陣列。拒絕規則會在允許規則之前評估。

工具許可和預設值

內建工具有不同的預設許可行為：

  • 預設受信任：fs_read、report_issue

  • 預設需要許可：execute_bash、fs_write、use_aws

  • 無組態選項：introspect、knowledge、thinking、todo_list

您可以在 allowedTools 區段中明確允許工具，或透過 toolsSettings 設定特定許可。如果工具不在 allowedTools 清單中，除非已設定適當的 toolsSettings 組態，否則將提示使用者提供許可。

MCP 伺服器組態

mcpServers 區段定義自訂代理程式可存取哪些模型上下文協定伺服器。每個伺服器組態都包含：

  • 命令 - 啟動 MCP 伺服器的可執行命令

  • 引數 - 伺服器的命令列引數

  • 環境變數 - 伺服器程序的環境設定

  • 逾時設定 - 請求逾時組態

如需 MCP 整合的詳細資訊，請參閱使用 MCP 搭配 Amazon Q Developer。

資源和內容

自訂代理程式可以透過兩種機制自動包含相關內容：

resources

要包含在自訂代理程式內容中的檔案和目錄，支援 glob 模式以靈活選取檔案

hooks

要在特定觸發點 (例如自訂代理程式啟動或使用者輸入) 執行的命令，內容中會包含輸出

常見的組態模式

最小自訂代理程式組態

簡單的自訂代理程式，提供具有預先核准讀取存取權的基本檔案操作：

{
"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"
  ]
}

專用工作流程自訂代理程式

為具有特定工具許可的 AWS 基礎結構管理所設定的自訂代理程式：

{
"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"
  ]
}

具有關聯的專案特定自訂代理程式

透過靜態檔案和動態命令納入專案內容的自訂代理程式：

{
  "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
      }
    ]
  }
}

與 MCP 伺服器整合的自訂代理程式

透過 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"
  }
}