配置参考 - Amazon Q 开发者版
配置参考配置概念常见配置模式

配置参考

自定义代理配置文件是定义自定义代理的行为方式的 JSON 文档。本节概述了配置概念和常见模式。

配置参考

有关自定义代理配置文件格式、可用字段和语法的完整详细信息，请参阅 Amazon Q 开发者版 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 的正则表达式格式。

deniedCommands

一系列要拒绝的命令。支持正则表达式格式。先评估拒绝规则，然后再评估允许规则。

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 开发者版结合使用。

资源和上下文

自定义代理可以通过两种机制自动包含相关上下文：

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