Amazon Quick 本番環境のカスタムエージェントを AWS CLI で開発環境にデプロイしてみた
クラウド事業統括本部の石川です。Amazon Quickのカスタムエージェントは、コンソールの GUI だけでなく、AWS CLI の aws quicksight コマンド群（エージェント管理 API）から作成・管理できます。本記事では、本番環境に既に存在するカスタムエージェント「CM_利益分析エージェント」を開発環境に「CM_利益分析エージェント_dev」として、AWS CLI でデプロイしてみます。エージェント定義をコード管理したい方や、本番環境から検証環境への複製を自動化を試してみます。
Amazon Quick のカスタムエージェントとは
Amazon Quick のカスタムエージェントは、部門や業務ごとにペルソナ・応答スタイル・ナレッジソース（スペース）・アクションを設定できる、対話型のアシスタントです。システム標準のチャットエージェントとは異なり、作成者が共有範囲やアクセス権限を制御できます。
コンソールにはエージェントの複製機能もありますが、AWS CLI を使うと設定の取得から作成までをスクリプト化でき、繰り返しの複製や構成のバージョン管理に応用できます。
エージェント管理 API（AWS CLI コマンド）
AWS CLI（確認バージョン: v2.35.21）の aws quicksight 名前空間には、以下のエージェント関連コマンドが用意されています。
| コマンド | 用途 |
|---|---|
list-agents / search-agents |
エージェントの一覧取得・検索 |
describe-agent |
エージェント設定の取得 |
describe-agent-permissions |
エージェント権限の取得 |
create-agent |
エージェントの作成 |
update-agent / delete-agent |
エージェントの更新・削除 |
update-agent-permissions |
エージェント権限の付与・剥奪 |
複製の流れは「describe-agent で複製元の設定を取得 → jq で create-agent 用の入力 JSON に変換 → create-agent 実行」の 3 ステップです。
前提条件
- AWS CLI v2.35.21 以降
jqインストール済みquicksight:ListAgents/quicksight:DescribeAgent/quicksight:CreateAgentなどを実行できる IAM 権限- リージョン: us-east-1
やってみた
Step 1: 複製元エージェントの AgentId を特定
エージェント名から AgentId を特定します。
% ACCOUNT_ID=123456789012
% REGION=us-east-1
% NEW_NAME="CM_利益分析エージェント_dev"
% SRC_AGENT_ID=$(aws quicksight list-agents \
--aws-account-id "$ACCOUNT_ID" \
--region "$REGION" \
--query "AgentSummaries[?Name=='CM_利益分析エージェント'].AgentId" \
--output text)
% echo "$SRC_AGENT_ID" # => 0ea5f4b1-1ef7-41b2-9e22-b25d1cc51a2c
Step 2: describe-agent で設定を取得
複製元エージェントの設定を JSON ファイルに保存します。
% aws quicksight describe-agent \
--aws-account-id "$ACCOUNT_ID" \
--agent-id "$SRC_AGENT_ID" \
--region "$REGION" \
--output json > src-agent.json
% cat src-agent.json
{
"Agent": {
"Spaces": [
"arn:aws:quicksight:us-east-1:123456789012:space/4d193b47-1e97-479b-816d-b0ccfc485a14"
],
"ActionConnectors": [],
"Description": "営業部向けの利益実績分析・調査アシスタントです。月次・成約単位の利益実績、予算比・前年比、変動要因の調査に回答します。連結情報・見積段階の試算は対象外です。",
"IconId": "id_agent_icon_ai",
"Name": "CM_利益分析エージェント",
"StarterPrompts": [
"先月の部門別利益を前年同月と比較して",
"オーダー番号を指定して利益明細を調べる",
"利益率が予算を下回っている商品群を教えて"
],
"WelcomeMessage": "利益分析・調査エージェントです。月次・成約単位の利益実績、予算比・前年比、変動要因についてお答えします。数値は月次締めデータに基づきます。重要な判断の際は元のダッシュボードで確定値をご確認ください。",
"Arn": "arn:aws:quicksight:us-east-1:123456789012:agent/0ea5f4b1-1ef7-41b2-9e22-b25d1cc51a2c",
"AgentId": "0ea5f4b1-1ef7-41b2-9e22-b25d1cc51a2c",
"AgentLifecycle": "PUBLISHED",
"AgentStatus": "ACTIVE",
"CreatedAt": "2026-06-18T08:14:33.229000+09:00",
"Creator": "arn:aws:ds:us-east-1:123456789012:federated/iam/AROA2VNNGI5TVZM7EZZRO:cm-author",
"CustomPromptInterface": {
"ModelProfileId": "e1113c2b-d9b4-4f04-b927-30903af16e91",
"SubscriptionId": "41b411b50e130ceee66f6937cea1320c",
"QbsAwsAccountId": "QBS123456789012",
"CustomInstructions": "<p>あなたは当社営業部の利益分析を専門に支援するシニア・データアナリストです。リンクされた利益実績データ（成約単位・月次）と利益計算ルールに基づき、営業担当者と部門長が業務判断に使える客観的な分析を提供します。</p><p>- 月次締め前の当月数値を聞かれた場合は「速報値であり確定値と異なる可能性がある」ことを必ず明記する。</p><p>- 連結情報・見積試算を聞かれた場合は回答せず、それぞれ「連結月次分析エージェント」「見積分析エージェント」を案内する。</p>"
},
"UpdatedAt": "2026-07-16T00:00:06.510000+09:00"
},
"RequestId": "a9cb2cd3-0d10-456f-bf10-5325612b2e96"
}
ポイントは、コンソールで設定した「エージェントペルソナ」が、CustomPromptInterface.CustomInstructions に HTML 形式で格納されている点です。
Step 3: jq で create-agent 用の入力 JSON を生成
create-agent の --agent-id は必須で、呼び出し側が採番します（パターン [0-9a-zA-Z-_.+]+）。コンソール作成時と同様に UUID を使うのが無難です。
カスタムプロンプトを指定する CustomPromptInput は Tagged Union で、ExistingPrompt（既存プロンプトプロファイルの参照）か NewPrompt（新規プロンプトの指定）のどちらか一方のみ指定できます。今回は複製元から独立したエージェントにしたいので、NewPrompt 方式で CustomInstructions をそのままコピーします。
もし、AWSアカウントにカスタムエージェントを作成したい場合は、src-agent.json の AwsAccountIdを書き換えてください。
% NEW_AGENT_ID=$(uuidgen | tr 'A-Z' 'a-z')
% jq --arg account "$ACCOUNT_ID" --arg id "$NEW_AGENT_ID" --arg name "$NEW_NAME" '
.Agent
| {
AwsAccountId: $account,
AgentId: $id,
Name: $name,
Description: .Description,
IconId: .IconId,
Spaces: .Spaces,
StarterPrompts: .StarterPrompts,
WelcomeMessage: .WelcomeMessage,
AgentLifecycle: .AgentLifecycle,
CustomPromptInput: {
NewPrompt: {
CustomInstructions: .CustomPromptInterface.CustomInstructions
}
}
}
' src-agent.json > create-agent-input.json
% cat create-agent-input.json
{
"AwsAccountId": "123456789012",
"AgentId": "b0b73d1d-1fa7-4f8d-9cd8-9714cf553ce3",
"Name": "CM_利益分析エージェント_dev",
"Description": "営業部向けの利益実績分析・調査アシスタントです。月次・利益単位の利益実績、予算比・前年比、変動要因の調査に回答します。連結情報・見積段階の試算は対象外です。",
"IconId": "id_agent_icon_ai",
"Spaces": [
"arn:aws:quicksight:us-east-1:123456789012:space/4d193b47-1e97-479b-816d-b0cccc485a14"
],
"StarterPrompts": [
"先月の部門別利益を前年同月と比較して",
"利益番号を指定して利益明細を調べる",
"利益率が予算を下回っている商品群を教えて"
],
"WelcomeMessage": "利益分析・調査エージェントです。月次・利益単位の利益実績、予算比・前年比、変動要因についてお答えします。数値は月次締めデータに基づきます。重要な判断の際は元のダッシュボードで確定値をご確認ください。",
"AgentLifecycle": "PUBLISHED",
"CustomPromptInput": {
"NewPrompt": {
"CustomInstructions": "<p>あなたは当社営業部の利益分析を専門に支援するシニア・データアナリストです。リンクされた利益実績データ（成約単位・月次）と利益計算ルールに基づき、営業担当者と部門長が業務判断に使える客観的な分析を提供します。</p><p>- 月次締め前の当月数値を聞かれた場合は「速報値であり確定値と異なる可能性がある」ことを必ず明記する。</p><p>- 連結情報・見積試算を聞かれた場合は回答せず、それぞれ「連結月次分析エージェント」「見積分析エージェント」を案内する。</p>"
}
}
}
Step 4: create-agent でエージェントを作成
生成した入力 JSON を渡してエージェントを作成します。
% aws quicksight create-agent \
--region "$REGION" \
--cli-input-json file://create-agent-input.json
{
"Arn": "arn:aws:quicksight:us-east-1:123456789012:agent/b0b73d1d-1fa7-4f8d-9cd8-9714cf553ce3",
"AgentId": "b0b73d1d-1fa7-4f8d-9cd8-9714cf553ce3",
"AgentStatus": "UPDATING",
"AgentName": "CM_利益分析エージェント_dev",
"RequestId": "e93e3a51-9b44-47e7-bac1-295c168e5661"
}
成功すると、CreateAgent API リファレンスのレスポンス要素（Arn / AgentId / AgentName / AgentStatus / RequestId）が返ります。
Step 5: 作成結果を検証
describe-agent で新エージェントの設定を取得し、複製元と比較します。
% aws quicksight describe-agent \
--aws-account-id "$ACCOUNT_ID" \
--agent-id "$NEW_AGENT_ID" \
--region "$REGION" > new-agent.json
# Arn / AgentId / 日時 / プロファイル ID 以外が一致すれば OK
% diff <(jq -S .Agent src-agent.json) <(jq -S .Agent new-agent.json)
3c3
< "AgentId": "0ea5f4b1-1ef7-41b2-9e22-b25d1cc51a2c",
---
> "AgentId": "b0b73d1d-1fa7-4f8d-9cd8-9714cf553ce3",
6,8c6,8
< "Arn": "arn:aws:quicksight:us-east-1:123456789012:agent/0ea5f4b1-1ef7-41b2-9e22-b25d1cc51a2c",
< "CreatedAt": "2026-06-18T08:14:33.229000+09:00",
< "Creator": "arn:aws:ds:us-east-1:123456789012:federated/iam/AROA2VNNGI5TVZM7EZZRO:cm-author",
---
> "Arn": "arn:aws:quicksight:us-east-1:123456789012:agent/b0b73d1d-1fa7-4f8d-9cd8-9714cf553ce3",
> "CreatedAt": "2026-07-28T20:54:17.006000+09:00",
> "Creator": "AROA2VNNGI5TVZM7EZZRO:cm-quick",
11c11
< "ModelProfileId": "e0013c2b-d9b4-4f04-b927-30903af16e91",
---
> "ModelProfileId": "a34967bb-1bd0-4dd6-b9f6-9768c00c31e3",
14c14
< "promptSummary": "Act as a senior data analyst who delivers objective gross profit analysis with concise business tone, strict adherence to linked data sources, and structured numerical presentations for executive decision-making."
---
> "promptSummary": "Serve as a senior data analyst who provides objective profit analysis for sales teams with professional precision while clearly noting data limitations and directing specialized inquiries to appropriate agents."
18c18
< "Name": "CM_利益分析エージェント",
---
> "Name": "CM_利益分析エージェント_dev",
27c27
< "UpdatedAt": "2026-07-16T00:00:06.510000+09:00",
---
> "UpdatedAt": "2026-07-28T20:54:22.107000+09:00",
Step 6: 権限を付与
この時点では、所有者はAWSCLIの実行ユーザーであるため、一覧に表示されません。Creatorフィールドを直接変更する AWS CLI は存在しませんが、所有者を自分に変更するのなら update-agent-permissionsを実行することで所有者権限が自動付与されます。複製元と同様に他ユーザーへ管理権限を共有したい場合は、update-agent-permissions を使います。
aws quicksight update-agent-permissions \
--aws-account-id "$ACCOUNT_ID" \
--agent-id "$NEW_AGENT_ID" \
--region "$REGION" \
--grant-permissions '[{
"Principal": "arn:aws:quicksight:us-east-1:123456789012:user/default/cm-quicksuite-admin-role/cm-author",
"Actions": [
"quicksight:DescribeAgent",
"quicksight:DescribeAgentPermissions",
"quicksight:UpdateAgent",
"quicksight:UpdateAgentPermissions",
"quicksight:DeleteAgent"
]
}]'
確認
同じようにデプロイできたのですが、ナレッジソースはナレッジは利用できませんと表示され、手動での再設定が必要でした。この点は今後の課題となります。
利用上の注意
実際に試して分かったポイントをまとめます。
- CustomInstructions は HTML 形式です。コンソールのリッチテキストエディタが HTML でシリアライズしているためで、
NewPrompt.CustomInstructionsにそのまま渡せば表示も同一になります。加工は不要です。 - describe-agent の出力にある
promptSummaryは create-agent に渡せません（サービス側で自動生成される読み取り専用フィールド）。同様にModelProfileId/SubscriptionId/QbsAwsAccountIdはNewPrompt方式では不要です。 NewPromptにはIdentity/Tone/ResponseLength/OutputStyleフィールドもあります。コンソールで作成したエージェントは全指示がCustomInstructionsに一本化されて返るため、複製目的ならそれだけコピーすれば十分です。ExistingPrompt方式で複製元のModelProfileIdを参照した場合に、プロンプトプロファイルが共有扱いになるか（片方の変更が他方へ波及するか）は未検証です。独立させたい場合はNewPrompt方式が安全です。- 主な制約値:
Nameは最大 50 文字、Descriptionは最大 1,000 文字、WelcomeMessageは最大 300 文字、StarterPromptsは最大 3 件・各 100 文字、Spaces/ActionConnectorsは最大 10 件です。 AgentLifecycleはPREVIEWとPUBLISHEDの 2 値です。まず動作確認したい場合はPREVIEWで作成し、update-agentでPUBLISHEDに切り替える運用もできます。
最後に
Amazon Quick のカスタムエージェントは、AWS CLI の describe-agent と create-agent を組み合わせることで、コンソールを操作せずに複製できました。カスタム指示（HTML 形式）やスペースの紐づけ、スターター プロンプトまで含めて設定を引き継げるため、エージェント定義のコード管理や環境間コピーの自動化にも応用できそうです。チャットエージェントの管理を自動化したい方は、エージェント管理 API の活用を検討してみてはいかがでしょうか。
