LoginSignup
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@sagochiko

Amazon Q Developer CLIのカスタムエージェントを試してみた

Posted at

Amazon Q Developer CLI のカスタムエージェントって？

目的や環境によって Amazon Q Developer CLI の役割や利用できるツール（MCP、コマンドなど）を切り替えられる機能です。

「Aの調査がしたいからXXXの設定を使おう」、「BのAWS環境のリソース調査がしたいからYYYの設定を使おう」などとAmazon Q Developer CLI の設定を切り替えるようなイメージです。

■参考
Amazon Q Developer CLI のカスタムエージェントは、特定のユースケースやワークフロー用に設定できるカスタマイズ可能な AI アシスタントです。広範なコンテキストとプロンプトエンジニアリングを必要とする汎用アシスタントを使用する代わりに、カスタムエージェントを使用すると、さまざまなシナリオに適したツール、アクセス許可、コンテキストのセットを事前設定できます。

2025年7月頃にリリースされたみたいです。

この記事では上記で紹介した機能を持つAmazon Q Developer CLI のカスタムエージェント機能を利用するための手順を紹介します。

カスタムエージェント機能をうまく使い分けることで、安全かつ効率的に業務を進められると思います。（全部trustにしてヒヤヒヤしたことがある人は自分だけじゃないはず。。）

カスタムエージェントを作ってみよう

事前準備

まずAmazon Q Developer CLI チャットセッションを開始します。

$ q chat

既存のエージェントを一覧表示してみます。q_cli_defaultが表示されるかと思います。

> /agent list

* q_cli_default

カスタムエージェントを作る

では実際にカスタムエージェントを作ってみましょう。
my-agentという名前でカスタムエージェントを作成します。

> /agent create --name my-agent

次の表示になるかと思うので、esc -> : -> q -> Enter でエディタを終了します。（vimエディタ以外の場合は別の閉じ方になるかと思います）

image.png

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "my-agent",
  "description": "",
  "prompt": null,
  "mcpServers": {},
  "tools": [
    "*"
  ],
  "toolAliases": {},
  "allowedTools": [],
  "resources": [
    "file://AmazonQ.md",
    "file://AGENTS.md",
    "file://README.md",
    "file://.amazonq/rules/**/*.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": true,
  "model": null
}

次のような表示が出たらOKです。/agent listを実行すると新たにagentが追加されていることがわかります。
これでカスタムエージェントが完成です！

image.png

カスタムエージェントを使う

カスタムエージェントを使用するには、q chat --agent [agent-name]を実行します。

$ q chat --agent my-agent

いつもと表示が少し違いますね。
チャット部分に[my-agent] >と表示されておりどのエージェントと会話しているのかがわかるようになっています。

image.png

「あなたは何をするエージェントですか？」と聞いてみると一般的なAmazon Q Developer CLIの回答が返ってきます。

お気づきの方も多いかと思いますが、ここまでで設定したカスタムエージェントは全くカスタムできていない状態です。一般的な回答が返ってきたのもそのためです。

image.png

自分なりにエージェントをカスタムする

ここまででカスタムエージェントの作り方の流れはわかったかと思います。
これからは自分なりにエージェントをカスタマイズする方法を紹介します。

まずカスタムエージェントの設定ファイルを確認

次のコマンドでカスタムエージェントの設定ファイルを確認します。

$ vi ~/.aws/amazonq/cli-agents/my-agent.json

※設定ファイルを作業ディレクトリの.amazonq/cli-agents/{agent-name}.jsonなどに作成した方はファイルパスを適宜修正ください

カスタムエージェントを作成した際にも表示されたjsonが表示されます。
この値をカスタマイズすることで自分だけのカスタムエージェントが作成できます。

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "my-agent",
  "description": "",
  "prompt": null,
  "mcpServers": {},
  "tools": [
    "*"
  ],
  "toolAliases": {},
  "allowedTools": [],
  "resources": [
    "file://AmazonQ.md",
    "file://AGENTS.md",
    "file://README.md",
    "file://.amazonq/rules/**/*.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": true,
  "model": null
}

カスタムエージェント設定ファイルで設定できる項目一覧

この次に自分なりにカスタマイズした設定ファイルをお見せします。

ただ、どのような項目か理解していないと設定内容が理解できないかと思いますので、設定できる項目とその説明、値の例などを表形式で記載していますので一度目を通してください。
※下の表はhttps://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.mdをCLAUDEに読ませて表を作成してもらっています。自分でも一応目は通しています。

主にpromptなどでどのような振る舞いをするか決まってくると思いますが、先ほどの設定ファイルではnullになっていたため特に特徴のない回答をしていました。

項目名 必須 データ型 説明 設定例
name × string エージェントの名前（未指定の場合はファイル名から自動取得） "aws-expert"
description × string エージェントの説明文（人間が読むため） "An agent specialized for AWS infrastructure tasks"
prompt × string エージェントへの高レベルな文脈提供（システムプロンプトに相当） "You are an expert AWS infrastructure specialist"
mcpServers × object エージェントがアクセス可能なModel Context Protocol（MCP）サーバーの定義 {"aws-docs": {"command": "uvx", "args": ["awslabs.aws-documentation-mcp-server@latest"]}}<br>
tools × array エージェントが使用可能なツールのリスト ["fs_read", "fs_write", "@git", "*"]
toolAliases × object ツール名の再マッピング（名前の衝突解決用） {"@github-mcp/get_issues": "github_issues"}
allowedTools × array ユーザーの許可なしに使用可能なツール ["fs_read", "fs_*", "@git/git_status"]
toolsSettings × object 特定ツールの設定オプション {"fs_write": {"allowedPaths": ["~/**"]}}
resources × array エージェントがアクセス可能なローカルリソース ["file://README.md", "file://.amazonq/rules/**/*.md"]
hooks × object 特定のトリガーポイントで実行されるコマンド {"agentSpawn": [{"command": "find . -name '*.md'", "description": "レビュー対象ファイルの確認"}]}
useLegacyMcpJson × boolean レガシーMCP設定ファイルを含めるかどうか true
model × string このエージェントで使用するモデルID "claude-sonnet-4"

カスタマイズした設定ファイルでカスタムエージェントを作成する

これまで説明した内容を踏まえて設定ファイルをカスタマイズしたので、自分なりのカスタムエージェントを作成します。

私のAWSアカウントにLambda・DynamoDB・S3があるので、そのリソースを管理してもらうaws-managementというカスタムエージェントを作ることにします。

次のコマンドを実行します。

/agent create --name aws-management

今回設定した設定ファイルは以下です。

※詳細な説明を記載したファイルはこちらに記載しています。（Claudeに手伝ってもらいました） 
{
  // エージェント名（ファイル名と同じ場合は省略可能だが明示的に指定）
  "name": "aws-management",
  
  // エージェントの説明（人間が読むための情報）
  "description": "A specialized agent for AWS and Rust development tasks",
  
  // システムプロンプト：エージェントの役割と責任を定義
  // ap-northeast-1リージョンに特化したAWSアカウント管理者として動作
  "prompt": "あなたはAWSアカウントの管理者です。Lambda・DynamoDB・S3がap-northeast-1にあるのでそのリソースについて管理する役割があります。",
  
  // Model Context Protocol (MCP) サーバーの設定
  "mcpServers": {
    // AWS公式ドキュメントにアクセスするためのMCPサーバー
    "aws-docs": {
      // uvx: Python package runner（pipx の後継）を使用
      "command": "uvx",
      // AWS Labs公式のDocumentation MCPサーバーの最新版を実行
      "args": ["awslabs.aws-documentation-mcp-server@latest"]
    }
  },
  
  // エージェントが利用可能な全ツールのリスト
  "tools": [
    // ファイル読み込みツール
    "fs_read",
    
    // ファイル書き込みツール（toolsSettingsで制限設定あり）
    "fs_write",
    
    // Bashコマンド実行ツール
    "execute_bash",
    
    // AWS CLI実行ツール（toolsSettingsで制限設定あり）
    "use_aws",
    
    // AWS Documentation MCPサーバーの全ツールを利用可能にする
    "@aws-docs"
  ],
  
  // ツール名のエイリアス設定（名前の衝突解決や短縮名作成用）
  // 現在は使用していないが、将来の拡張のために残している
  "toolAliases": {},
  
  // ユーザーの明示的な許可なしに自動実行可能なツール
  "allowedTools": [
    // ファイル読み込みは常に安全なので自動実行を許可
    "fs_read",
    
    // AWS公式ドキュメント検索は情報取得のみなので自動実行を許可
    "@aws-docs"
  ],
  
  // 各ツールの詳細設定とセキュリティ制限
  "toolsSettings": {
    // ファイル書き込みツールの制限設定
    "fs_write": {
      // 書き込み可能なパスを制限（セキュリティのため）
      "allowedPaths": [
        "docs/**",      // docsディレクトリとその配下の全ファイル
        "*.md",         // ルートディレクトリのMarkdownファイル
        "src/**"        // srcディレクトリとその配下の全ファイル
      ]
    },
    
    // AWS CLI実行ツールの制限設定
    "use_aws": {
      // 操作可能なAWSサービスを制限（セキュリティのため）
      "allowedServices": [
        "s3api",           // Amazon S3 - オブジェクトストレージサービス
        "lambda",       // AWS Lambda - サーバーレス関数実行サービス
        "dynamodb",     // Amazon DynamoDB - NoSQLデータベースサービス
        "iam"           // AWS IAM - 権限・アクセス管理サービス
      ]
    }
  },
  
  // エージェントがアクセス可能なローカルリソース
  "resources": [
    // プロジェクトのREADMEファイル
    "file://README.md",
    
    // docsディレクトリ配下の全Markdownファイル
    "file://docs/**/*.md"
  ],
  
  // 特定のタイミングで自動実行されるコマンドフック
  // 現在は使用していないが、将来の拡張のために残している
  "hooks": {},
  
  // レガシーMCP設定ファイルの併用設定
  // true: ~/.aws/amazonq/mcp.json や .amazonq/mcp.json も読み込む
  "useLegacyMcpJson": true,
  
  // 使用するAIモデルの指定
  "model": "claude-sonnet-4"
}

{
  "name": "aws-management",
  "description": "A specialized agent for AWS and Rust development tasks",
  "prompt": "あなたはAWSアカウントの管理者です。Lambda・DynamoDB・S3がap-northeast-1にあるのでそのリソースについて管理する役割があります。",
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"]
    }
  },
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws",
    "@aws-docs"
  ],
  "toolAliases": {},
  "allowedTools": [
    "fs_read",
    "@aws-docs"
  ],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["docs/**", "*.md", "src/**"]
    },
    "use_aws": {
      "allowedServices": ["s3api", "lambda", "dynamodb", "iam"]
    }
  },
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "hooks": {},
  "useLegacyMcpJson": true,
  "model": "claude-sonnet-4"
}

image.png

次ようにagentの作成に成功していればOKです。

image.png

設定ファイルカスタマイズ済のカスタムエージェントを使用する

次のコマンドでカスタムエージェントを呼び出します。（キャプチャは$ AWS_PROFILE=oyaなどついていますが皆さんは不要です）

$ q chat --agent aws-management

カスタムエージェントが呼び出せてそうですね。
image.png

「あなたは何をするエージェントですか？」と聞いてみます。

今回はpromptに記載した内容を理解してAWSアカウントの管理者として振る舞うように理解してくれています。（promptをnullにした場合は一般的なAmazon Q Developer CLIの回答が返ってきました）

image.png

カスタムエージェントを使用してAWSリソース調査

AWSアカウントの調査もしてくれます。まずはLambdaとDynamoDBのことを聞いてみます。

次の場合にUsing tool: use_aws (trusted)となっているのは、設定ファイルのallowedToolsにLambdaとDynamoDBが含まれているからです。

image.png

次にLambdaとEC2のことを聞いてみます。

次の場合は、LambdaはallowedToolsに含まれているが、EC2は含まれていないためにEC2のみ承認を求められます。

image.png

aws documentation mcpの利用もallowedToolsに入れているので調査を自動で進めてくれます。
image.png

このような形でカスタムエージェント機能を活用していくことでより調査が便利で安全に進められます。
基本的な使い方は問題ないかと思うので今回設定したファイルの後片付けをします。

後片付け

これまでの手順に沿って実施した場合は次のコマンドで設定ファイルを削除できます。

$ rm ~/.aws/amazonq/cli-agents/my-agent.json
$ rm ~/.aws/amazonq/cli-agents/aws-management.json

おわりに

Amazon Q Developer CLIのカスタムエージェント機能を使用して特定の仕事や調査に特化したエージェントが簡単に作ることができることがわかりました。
実行してほしくないコマンドや自動実行して進めてほしいコマンドなど環境によって様々あるかと思いますが、このカスタムエージェント機能を利用することで、安全かつ効率的に業務を進められると思います。

皆さんもカスタムエージェントを使ってより楽に仕事を進めましょう！ご覧いただきありがとうございました！

参考

AWSドキュメントよりGithubの方がわかりやすく充実している気がしています（2025年9月26日時点筆者主観）
https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md
https://github.com/aws/amazon-q-developer-cli/blob/main/docs/built-in-tools.md
https://docs.aws.amazon.com/ja_jp/amazonq/latest/qdeveloper-ug/command-line-custom-agents.html

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?