2025.11.12 ｜ Writer：NTT東日本　白鳥翔太

Amazon Q Developer CLIを使った作業をカスタムエージェントで効率的に管理しよう

	こんにちは、白鳥です。

過去数回にわたってAmazon Q Developer CLIを使ってAWS環境の構築～運用保守を簡易に行う記事を投稿してきました。

Amazon Q Developer CLIに任せる作業が増えてきた場合、その都度MCPの設定変更を行ったり、プロンプトで”***.mdを読んで作業して”と毎回入力したりするのは入力漏れのミスが発生するなど、品質面の管理が煩雑となります。

そこで今回はAmazon Q Developerのカスタムエージェント機能を使って、これまでの作業のとりまとめを行っていきたいと思います。

想定する読者

AWSで構築されたシステム管理をAIでアシストしたい方
複数の用途でAmazon Q Developer CLIを使用している方

AWSの構築/運用のお悩みにNTT東日本のエンジニアがおこたえします。お気軽にご相談ください。

カスタムエージェントの仕様解説: name セクション; descriptionセクション; promptセクション; modelセクション; toolsセクション; allowedToolsセクション; toolsSettingsセクション; mcpServersセクション; resourcesセクション; hooksセクション
設定例
起動と停止
カスタムエージェント作成のベストプラクティス
まとめ

カスタムエージェントの仕様解説

Amazon Q Developerのカスタムエージェント機能は、特定のユースケースや用途に特化させるためにコンテキストやプロンプトを事前に入力できるほか、Amazon Q Developerが使用できるツールやアクセス制御を事前に定義することができます。

コンフィグファイルはJSON形式で保存されて、次のような形式となります。

{
        “name”: [],
        “description”: [],
        “prompt”: [],
        “model”: [],
        “tools”: [],
        “allowedTools”: [],
        “toolsSettings": [],
        “mcpServers”: [],
        “resources”: [],
        “hooks”: []
}

MCP Serverの設定と同様、JSONファイルの保存場所によって、利用できる範囲が変わります。Windows環境の場合ですと、このような仕様になります。

C:\Users\${User}\.aws\amazonq/cli-agents/ディレクトリの場合、PCすべてに適用
プロジェクトの.amazonq/cli-agents/ディレクトリの場合、対象のプロジェクトにのみ適用

使い分けとしては、ローカルPCでのみ使う場合は/.aws/ディレクトリ、プロジェクトメンバーで共有して使う場合はプロジェクトのディレクトリにおくのが良いと思います。同名のエージェントが両方に存在する場合にはプロジェクト側の設定が優先されます。

続いて、各セクションの解説をしていきます。

nameセクション

文字通りカスタムエージェントの名前になります。こちらの値を起動時に使用します。

descriptionセクション

カスタムエージェントの目的を記述します。Amazon Q Developer CLIを起動した後、/agent listコマンドでカスタムエージェントの一覧を表示した際に説明文として記載されます。

promptセクション

カスタムエージェントに与えるハイレベルなコンテキストになります。システムプロンプトに近いものになります。したがって、ここに前提条件や期待する成果物などを記載していきます。

modelセクション

Amazon Q Developerが使用するLLMのモデルを指定します。とくに指定がなければデフォルトのモデルが使用されます。2025年10月現在では、下記のモデルが使用可能です。

claude-3.5-sonnet
claude-3.7-sonnet
claude-4-sonnet
claude-4.5-sonnet

toolsセクション

Amazon Q Developerでは、ビルトインのツールがあります。

fs_read – ファイルやディレクトリの読み込み
fs_write – ファイルの作成
execute_bash – Shellコマンドの実行
use_aws – AWS CLIコマンドの作成と実行
knowledge – チャットセッション間の引継ぎ
introspect – Amazon Q Developer CLIのケイパビリティについての情報提供

toolsセクションではビルトインツールとMCP Serverで提供されたツールをそもそも使用するか否かの指定を行います。許可するビルトイン名を記載します。また、MCP Serverで提供されたツールのうち一部のみを許可する場合は@以下でツール名を指定します。

すべて許可する場合は、”*”を使用します。

allowedToolsセクション

allowedToolsセクションでは、toolsセクションで許可したツールのうち、ユーザーの確認無しで実行するツールを指定します。例えば、ファイルの読み込み（fs_read）は許可するといった場合に使用します。ここに指定のないツールについては、ツール実行時にユーザーの許可が必要になります。

toolsSettingsセクション

toolsセクションで許可されたツールのうち、細かい許可を与える場合に使用します。ツールごとに違いますが例えばこのようになります。

fs_readツールとfs_writeの場合

allowedPath：許可するパスを指定します。ディレクトリだけではなく、ファイル単位での指定も可能です
deniedPaths：拒否するパスを指定します

記載例

{
  "toolsSettings": {
    "fs_read": {
      "allowedPaths": ["~/projects", "./src/**"],
      "deniedPaths": ["/some/denied/path/", "/another/denied/path/**/file.txt"]
    }
  }
}

execute_bashツールの場合

allowedCommands：使用を許可するコマンドを指定します
deniedCommands：使用を拒否するコマンドを指定します。例えばファイルの削除やAmazon Q Developerに使用させたくないツールを指定します
allowReadOnly：読み込み関連のコマンドを許可するかを選択します。デフォルトはtrueです

記載例

{
  "toolsSettings": {
    "execute_bash": {
      "allowedCommands": ["git status", "git fetch"],
      "deniedCommands": ["git commit .*", "git push .*"],
      "allowReadOnly": true
    }
  }
}

use_awsツールの場合

allowedServices：AWS CLIのサービス単位で許可するサービスを指定します。ec2やs3などを個別に指定します
deniedServices：AWS CLIのサービス単位で拒否するサービスを指定します

AWS CLIに許可するIAMポリシーでも使用可能なサービスを指定できますが、toolSettingsで使用するサービスを絞っておくと、そもそも不許可のサービスのコマンドを打たなくなる、万が一大きな権限をIAM側で保持していたとしても使用しないで済むという2つのメリットがあります。

記載例

{
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "ec2"],
      "deniedServices": ["eks", "rds"]
    }
  }
}

mcpServersセクション

ビルトインのツールだけでは足りない場合、こちらのmcpServersセクションを使用します。記載方法はほかのMCP Serverとおなじなので、こちらは省略します。

resourcesセクション

resourcesセクションでは、追加するコンテキストを指定します。手順書や設計書、コーディング規約、アーキテクチャガイドなどがこれにあたります。ファイルのパスを指定します。

記載例

{
  "resources": [
    "file://README.md",
    "file://infrastructure/**/*.yaml",
    "file://docs/deployment.md"
  ]
}

hooksセクション

hooksセクションでは、カスタムエージェントの起動時またはプロンプトの入力時に実行するコマンド類を指定します。

agentSpawn：カスタムエージェントの起動時に実行され、実行結果はセッションを通じてコンテキストに追加されます
userPromptSubmit：ユーザーのプロンプト入力時に実行され、実行結果はそのプロンプトだけで使用可能です

各サブセクションではこのような指定が可能です

command：実行時のシェルコマンド※必須
timeout_ms：コマンドがタイムアウトするまでの時間(デフォルトは30000ms)
max_output_size：出力結果の最大サイズ(単位：bytes)
cache_ttl_seconds：キャッシュの保持期間(デフォルトは0、キャッシュしない)

AWSの構築/運用のお悩みにNTT東日本のエンジニアがおこたえします。お気軽にご相談ください。

設定例

前々回の記事のネットワーク構築用のカスタムエージェントを作る場合は、例えばこのような設定となります。

{
        "name": "networkadmin",
        "description": "ネットワーク構築用",
        "prompt": "あなたはエンタープライズネットワークにおけるAWSネットワーク管理者です。aws_vpc_management_guide.mdの手順を参照して、VPCの作成と、Transit Gatewayへの接続を行ってください",
        "mcpServers": {
                "awslabs.core-mcp-server": {
                        "command": "uvx",
                        "args": [
                                awslabs.core-mcp-server@latest
                        ],
                        "env": {
                        "FASTMCP_LOG_LEVEL": "ERROR"
                        },
                        "autoApprove": [],
                        "disabled": false
                },
                "aws-knowledge-mcp-server": {
                        "command": "npx",
                        "args": [
                        "mcp-remote",
                        "https://knowledge-mcp.global.api.aws"
                        ]
                }
        },
        "tools": ["*"],
        "allowedTools": [
                "fs_read",
                ],
        "resources": [
                "file://./home/shiratori/aws_vpc_management_guide.md",
                ],
        "hooks": {
                "agentSpawn": [
                        {
                                "command": "cat aws_vpc_management_guide.md"
                        }
                ]
        }
}

AWSの構築/運用のお悩みにNTT東日本のエンジニアがおこたえします。お気軽にご相談ください。

起動と停止

ここまで完成したら、Amazon Q Developer CLIの起動を行います。

起動コマンド

q chat --agent ${name}

nameのところはnameセクションで指定したエージェントの名前を指定します。

起動すると、デフォルトのエージェントとは異なり、MCP Serverが2つだけ起動します。

起動例

参考：前回記事の起動時はデフォルトで起動していました

停止は、通常と同じく/quitコマンドとなります。

AWSの構築/運用のお悩みにNTT東日本のエンジニアがおこたえします。お気軽にご相談ください。

カスタムエージェント作成のベストプラクティス

これまでの経験を踏まえて、カスタムエージェントを作成するうえでの現時点の仕様におけるベストプラクティスを3つほどご紹介したいと思います。

1タスク1カスタムエージェントを作成する
繰り返しの調査や作業においてカスタムエージェントが使えると考えています。しかしながら、現時点ではマルチエージェント機能を有していないため、複合的なカスタムエージェントが絡むタスクは難しいと思いますので、取りまとめ役は人間が代行することになります。したがってサブエージェントしての稼働が中心となりますので、小さなタスクを実行する用に特化するのが好ましいと考えています。
MCPやツールは最小限に
前のベストプラクティスとも共通しますが、カスタムエージェントにMCPやツールを詰め込むことができますが、多数のツールを入れてしまうと実行時に人間が意図したツールを使わない、逆に意図しないツールを使用して意図しない結果を呼ぶこともあります。したがって、タスクを小さくしたうえで、ツールも最小限として運用することをおすすめします。
プロンプトよりもコンテキストを優先する
カスタムエージェントを実行する際、プロンプトでの入力量が増えると、入力ミスや入力漏れが発生し、意図した結果を得られないことがあります。したがって、期待する出力形式や手順などについては、resourceセクションでファイルを指定し、システムプロンプトでresourceや使用すべきツールを指示したほうが良いでしょう。そのうえで、指示ごとに可変するパラメータについてはプロンプトで入力するような形式がおすすめです。

AWSの構築/運用のお悩みにNTT東日本のエンジニアがおこたえします。お気軽にご相談ください。

まとめ

さまざまな作業をAmazon Q Developer CLIに代行してもらってきましたが、ちょうどそろそろ管理機能が欲しいと思っていたところに、このカスタムエージェント機能は助かる機能でした。カスタムエージェント機能を使って、自分だけのAWS AIエンジニアチームを作ることで、AWS上の作業をもっと効率的に行えればと思います。

NTT東日本では、AWSの構築保守だけではなく、ネットワーク設計なども含めたエンドツーエンドでのソリューション提供をおこなっております。

経験値豊かなメンバーがご担当させていただきますので、是非お気軽にお問い合わせください！