組態參考

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

組態參考

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

• 客服人員組態格式 - 所有組態選項的完整參考

• 內建工具參考 - 所有內建工具的文件及其組態選項

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

/agent schema

組態概念

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

基本中繼資料

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

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

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

工具組態

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

工具

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

allowedTools

指定哪些工具可在使用者未確認的情況下執行，從而提高工作流程效率

toolAliases

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

toolsSettings

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

MCP 伺服器組態

mcpServers 本節定義自訂代理程式可存取的模型內容通訊協定伺服器。每個伺服器組態包括：

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

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

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

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

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

資源和內容

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

resources

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

hooks

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

常見的組態模式

最低自訂代理程式組態

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

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

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

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

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

具有勾點的專案特定自訂代理程式

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

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

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

透過 MCP 伺服器整合外部工具的自訂代理程式：

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