구성 참조

사용자 지정 에이전트 구성 파일은 사용자 지정 에이전트의 동작 방식을 정의하는 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를 사용한 정규식 형식을 지원합니다.
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 통합에 대한 자세한 내용은 Amazon Q Developer로 MCP 사용을 참조하세요.

리소스 및 컨텍스트

사용자 지정 에이전트는 다음 두 가지 메커니즘을 통해 관련 컨텍스트를 자동으로 포함할 수 있습니다.

리소스: 사용자 지정 에이전트의 컨텍스트에 포함할 파일 및 디렉터리로, 유연한 파일 선택을 위한 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"
  }
}

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

사용자 지정 에이전트 관리

예시