配置参考

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

配置参考

有关自定义代理配置文件格式、可用字段和语法的完整详细信息，请参阅 Amazon Q Developer CLI 补充文档：

• 代理配置格式-所有配置选项的完整参考

• 内置工具参考-所有内置工具及其配置选项的文档

您还可以通过运行以下命令查看自定义代理配置文件的 JSON 架构：

/agent schema

配置概念

自定义代理配置文件包含几个关键部分，用于控制自定义代理行为的不同方面：

基本元数据

每个定制代理都可以包含用于识别和记录的基本元数据：

• 名称-自定义代理的标识符（如果未指定，则从文件名派生）

• 描述-对自定义代理用途的人类可读解释

工具配置

工具配置控制自定义代理可以使用哪些工具以及它们的行为方式：

工具

列出定制代理可能使用的所有工具，包括内置工具和 MCP 服务器工具

允许的工具

指定无需用户确认即可运行哪些工具，从而提高工作流程效率

工具别名

为工具提供备用名称，可用于解决命名冲突或创建快捷方式

工具设置

为各个工具配置特定行为，例如允许的文件路径或服务权限

MCP 服务器配置

本mcpServers节定义了定制代理可以访问哪些模型上下文协议服务器。每种服务器配置包括：

• 命令-启动 MCP 服务器的可执行命令

• 参数-服务器的命令行参数

• 环境变量-服务器进程的环境设置

• 超时设置-请求超时配置

有关 MCP 集成的更多信息，请参阅在 Amazon Q 开发者中使用 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"
  }
}