Amazon Q Developer × Quick Flows ― Agentic AI で業務フローを自動化し boto3 で API制約を実測する

記事の内容

本記事はAmazon Q Developerを活用しながら、Amazon Quick FlowsのコンソールUIとAPIの両面を実測した内容をまとめています。コンソール操作の手順紹介だけでなく、裏側のAPIでできること・できないことまで踏み込んでお伝えします。

記事の流れ

在庫に関する簡単なサンプルデータを用いて、再注文の閾値を下回っているかを判定して

ログを出力するような簡単なフローを作ってみます

コンソール操作でのデモを行った後、boto3 APIを用いてコンソール操作の裏側（できること・できないこと）を実測で明らかにします。さらに発展形として、AIの精度を高めるデータモデリングの手法についても解説します。

使用するデータ

使用するデータは以下で、在庫に関する簡単なサンプルデータとなります
inventory

inventory.csv

Flows作成手順

1. Quickのトップページ左メニューから「スペースを作成する」を実行し、inventory.csv をアップロードします。スペースはQuickのRAG機能の実体であり、S3のPDFや社内文書など様々なデータソースに対応しています。

1. 左のナビゲーションから「フロー」→「フローを作成」を選択します。対話画面が開くので、「スペースの内容を読み取り、再注文が必要な項目を割り出してログ出力、週1回実行」と自然言語で指示します。

1. 右上でエディタから実行モードに切り替え、デバッグ実行でフローが意図した挙動をするか確認します。

生成されたログが以下となります

# 再注文必要商品 詳細ログ


================================================================================
再注文ログレポート
================================================================================

[実行日時]
2024年12月19日 生成

[サマリー]
- 総商品数: 13商品
- 再注文必要商品数: 3商品
- 正常在庫商品数: 10商品

================================================================================
再注文必要商品詳細
================================================================================

[商品 #1] ⚠️ 緊急
---------------------------------------------------
商品名          : Monitors
現在在庫数      : 2個
ReOrderPoint    : 5個
不足数          : -3個
在庫充足率      : 40.0%
緊急度          : 最高 (在庫ほぼ枯渇)
---------------------------------------------------

[商品 #2] ⚠️ 緊急
---------------------------------------------------
商品名          : Ink Cartridges
現在在庫数      : 5個
ReOrderPoint    : 20個
不足数          : -15個
在庫充足率      : 25.0%
緊急度          : 高 (発注点の1/4以下)
---------------------------------------------------

[商品 #3] ⚠️ 緊急
---------------------------------------------------
商品名          : Masks
現在在庫数      : 50個
ReOrderPoint    : 200個
不足数          : -150個
在庫充足率      : 25.0%
緊急度          : 高 (大量不足)
---------------------------------------------------

================================================================================
推奨アクション
================================================================================

1. 【最優先】Monitors: 即時発注手配が必要
2. 【優先】Ink Cartridges: 早急な補充が必要
3. 【優先】Masks: 大量発注の手配が必要

================================================================================
ログ終了
================================================================================

また、ログのダウンロードもUIで提供されています。

外部コネクタ連携（Slack等）

SlackなどのコネクタはコンソールのConnectorsタブから設定できます。フロー実行結果をそのままSlackチャンネルへ通知することが可能です。なお、コネクタのアクション設定には Quick の管理者権限が必要なため、権限エラーが出た場合はIAMロールの quicksight:* 権限を確認してください。

boto3 APIでコンソール操作の裏側を実測する

ここまでのコンソール操作を実際に試しながら、「この処理はAPIでも実現できるのか？」を Amazon Q Developer と一緒に検証しました。Quick Flowsは比較的新しい機能であり、できること・できないことの境界をAPIレベルで把握しておくことが自動化設計の出発点になります。

Amazon Q Developer による自律的なAPI探索プロセス

Amazon Q Developer は単なるコード補完ではなく、「コード生成 → 実行 → エラー観察 → 原因特定 → 修正案提示」のループを自律的に回す AWS の Agentic AI ツールです。今回の boto3 検証でも、このループが複数回まわりました。以下は describe_data_set の制約を発見・回避するまでの実際のプロセスです。

【ステップ1】Q Developer が初期実装を生成

「CSVデータセットから列情報を取得したい」という指示に対し、Q Developer が以下のコードを提案しました。

response = qs.describe_data_set(
    AwsAccountId=account_id,
    DataSetId=dataset_id
)
columns = response['DataSet']['PhysicalTableMap']

【ステップ2】実行 → エラー観察

実行すると以下のエラーが返りました。

botocore.exceptions.ClientError: An error occurred (InvalidParameterValueException)
when calling the DescribeDataSet operation:
File source type is not supported in Public API

【ステップ3】Q Developer が原因を特定 → 代替アプローチを提案

Q Developer がエラーメッセージを解析し、次のように診断しました。

「コンソールのCSVアップロードで作成したデータセットは File source 扱いとなり、describe_data_set Public API の対象外です。同じデータセットを参照しているトピックが存在する場合、describe_topic 経由で列情報を取得できます。代替実装を生成します。」

【ステップ4】修正コード生成 → 再実行で解決

Q Developer が提案した回避策が動作し、制約の境界線を確定できました。このように Q Developer はエラーを入力として次の判断を自律的に生成するAgentic AIとして機能しています。

ファイルソース系データセットの制約とワークアラウンド

コンソールのCSVアップロードで作ったデータセットは describe_data_set API で列情報を取得できません。

InvalidParameterValueException: File source type is not supported in Public API

代わりに、同じデータセットを参照している既存トピックから describe_topic 経由で列情報を引き回す方法が有効です。

def get_columns_from_existing_topic(aws_account_id, dataset_arn):
    topics = qs.list_topics(AwsAccountId=aws_account_id).get('TopicsSummaries', [])
    for t in topics:
        r = qs.describe_topic(AwsAccountId=aws_account_id, TopicId=t['TopicId'])
        for ds in r['Topic'].get('DataSets', []):
            if ds['DatasetArn'] == dataset_arn and ds.get('Columns'):
                return ds['Columns']
    return []

計算フィールドをAPIで定義する

コンソールの「計算フィールドを追加」操作は create_topic の CalculatedFields に対応します。

calculated_fields = [
    {
        'CalculatedFieldName': 'Shortage',
        'CalculatedFieldDescription': '再注文点を下回っている不足数',
        'Expression': '{Reorder Point} - {Quantity}',
        'CalculatedFieldSynonyms': ['不足数', '足りない数量'],
        'IsIncludedInTopic': True,
        'ColumnDataRole': 'MEASURE',
    }
]

qs.create_topic(
    AwsAccountId=account_id,
    TopicId='inventory-topic',
    Topic={
        'Name': 'Inventory-Topic',
        'UserExperienceVersion': 'NEW_READER_EXPERIENCE',
        'DataSets': [
            {
                'DatasetArn': dataset_arn,
                'DatasetName': 'Inventory Dataset',
                'Columns': columns,
                'CalculatedFields': calculated_fields,
            }
        ]
    }
)

コンソール操作との対応:

Quick Flows API — できること・できないこと

boto3 で Quick Flows を操作できる範囲を実測で確認しました。

利用可能なAPI：

qs = boto3.client('quicksight', region_name='ap-northeast-1')

# フロー一覧の取得
flows = qs.list_flows(AwsAccountId=account_id)['FlowSummaryList']
for flow in flows:
    print(flow['Name'], flow['PublishState'], f"実行回数: {flow['RunCount']}")

# フロー詳細の取得
meta = qs.get_flow_metadata(AwsAccountId=account_id, FlowId=flow_id)

# 権限の確認・変更
perms = qs.get_flow_permissions(AwsAccountId=account_id, FlowId=flow_id)

list_flows で取得できる情報には RunCount（実行回数）や PublishState（PUBLISHED/DRAFT）が含まれており、モニタリング用途に活用できます。

APIでは実行できない操作：

フローの作成・実行はコンソール操作が必要です。一方で一覧取得・権限管理はAPI化可能という境界を把握しておくと、自動化の設計に役立ちます。

なぜフロー作成・実行は Public API で操作できないのか

Quick Flows はQuickSightの中でも新しいAgentic機能であり、フロー実行は認証済みユーザーのブラウザセッションコンテキスト（StartFlowSession）を必要とします。このセッションはコンソールからインタラクティブに確立されるものであり、サービス側がユーザーの意図確認・権限スコープの動的評価を行うため、boto3 SDK の呼び出しだけでは確立できない設計になっています。

IAMポリシー上は quicksight:StartFlowSession アクションが定義されているものの、これはコンソール内部のセッション管理用です。Amazon Q Business など、マネージドAI機能全般で「フロー設計はコンソール、運用監視はAPI」という役割分担になっているパターンと共通します。

実務上の設計方針: フローの作成・実行はコンソール操作として人間が担い、API側では「モニタリング（list_flows の RunCount / PublishState）」と「権限管理（get_flow_permissions）」に集中する設計が現実的です。

一歩進んだデータ加工：Caliculated Field

こちらもお好みですが、さらに精度を高める際には、データ分析の観点を取り入れてあげると
AIの判断やフローをより確実なものとできます。

そういう観点で元データをみると
CSVには Quantity（在庫数） と Reorder Point（発注点） はありますが、
「あと何個足りないか」の列はありません。そこでトピック側に計算フィールドを作ります。

これをFlowsのプロンプト（指示文）だけで「不足している数を計算して出力して」とAIに丸投げすることも可能ですが、AIの解釈のブレによって計算が漏れたり、フォーマットが不安定になったりするリスク（プロダクション環境での課題）が残ります。

そこで、AI側に頑張らせるのではなく、参照元のナレッジベース（トピック）側であらかじめ「計算フィールド」として定義しておくというベストプラクティスをご紹介します。

トピック側での仕込み設定

対象トピックの 「Data（データ）」 タブを開き、右上の 「Add calculated field（計算フィールドの追加）」 をクリックします。

以下のようにビジネスロジックを定義します。

フィールド名（Field name）： Shortage
シノニム（Synonyms）： 不足数, 足りない数量
計算式（Expression）： Reorder Point - Quantity

データの変化（Before / After）と効果

この先回りのデータモデリングを行うことで、出力されるログ（あるいはSlack通知）のクオリティに明確な差が出ます。

Before（設定前）：
AIが「発注点を下回っているか」の判定だけで手一杯になり、ログにはただ対象の商品名が並ぶだけ。担当者は「で、結局それぞれ何個発注すればいいの？」をデータソースに確認しに行く手間が発生する。

After（設定後）：
あらかじめ定義した Shortage をAIが正しく認識し、「どの商品が、あと何個不足しているか」が正確に、かつ「緊急度の高い順（不足数が多い順）」にソートされた、現場がそのまま発注処理に使える極めて実用的なログ・通知が確実に生成されるようになります。

計算フィールドを活用する場合は、単純にスペースにcsvをアップロードする形ではなく、
データセットにcsvをアップロード、トピックにルールを設定する必要があります。
その手法はもう一つのビジュアライズの記事でご確認ください。

計算済みフィールドに以下のように差分の計算式を格納し、プレビューの値（画面下）
もイメージ通りであることを確認します

フロー上で扱うデータをスペースのcsv直接ではなく、トピックにしてあげることが必要です

AIでの解釈もずれづらくなり、表もイメージ通り作成できていることがわかります！

最後にQuickのデータフロー構造おさらい

上記の発展情報では下記のセマンティック・Topic層、及び決定論的ロジックでのフローの補強を行なった形となります。

+-------------------------------------------------------------+
|                     データインジェスト層                    |
|       Space（RAGリポジトリ：CSV等のファイルを格納）          |
+------------------------------+------------------------------+
                               |
                               | データ参照
                               v
+-------------------------------------------------------------+
|                     AIフロー実行・制御層                    |
|      Amazon Quick Flows (自然言語による処理ロジックの定義)    |
+------------------------------+------------------------------+
                               |
                               | 決定論的ロジック（計算フィールド）
                               v
+-------------------------------------------------------------+
|                      セマンティック・Topic層                 |
|             データ層における数式・シノニム定義               |
+------------------------------+------------------------------+
                               |
                               | Slack Webhook / Connector
                               v
+-------------------------------------------------------------+
|                        通知・連携層                         |
|                    外部チャネル（Slack等）                  |
+-------------------------------------------------------------+

データインジェスト層（Spaces）: ナレッジベースの役割を果たす「Space」を定義し、検証データである inventory.csv を格納する 。本番環境では、Amazon S3やSharePoint、Box等の外部エンタープライズシステムと連携したRAG（Retrieval-Augmented Generation）基盤としてスケール可能である 。

AIフロー実行・制御層（Quick Flows）: 自然言語によって定義された「何が発注点を下回っているか」を判定する命令フローを実行する 。週次の実行スケジュールが設定されている 。

セマンティック・Topic層（計算フィールド）: 単なる自然言語命令から、Dataset-to-Topic構造へ移行し、計算フィールドを活用した安定的な意思決定ロジックを構成する 。

通知・連携層（外部コネクタ）: 管理者権限を付与されたSlackコネクタを通じて、最終的な処理結果を運用チャネルに配送する。

boto3 APIで判明した Quick Flows の制約まとめ

本記事では、Amazon Q Quick Flows を boto3 API で実測し、コンソール操作との境界線を明らかにしました。実装に取り組む際のポイントを以下に整理します。

コンソールが必須の操作（APIでは代替不可）
– フローの作成・設計：Public API が存在しないため、コンソールでの人手による設計が前提
– フローの実行：StartFlowSession はブラウザセッション依存のため boto3 からは呼び出し不可
– フロー定義の確認：プロンプト内容などの定義はAPIで取得できないため、コンソールで直接確認する

APIで自動化できる操作
– list_flows による稼働状況のモニタリング（RunCount / PublishState）
– get_flow_permissions による権限管理
– トピックへの計算フィールド追加（CalculatedFields に IsIncludedInTopic: True を明示することが必須）

実装方針として「フローの設計・実行はコンソール（人間が担当）、運用監視と権限管理はAPI（自動化）」という役割分担を採用することが、Quick Flows 自動化の現実的なアーキテクチャです。CI/CD パイプラインや Slack アラート連携を検討している場合は、list_flows の RunCount と PublishState を起点にした監視設計から始めると、段階的な自動化がしやすくなります。

合わせてQuickSight Qのトピック自動作成についても関連記事を執筆しているので、こちらも興味があればご確認ください。
Amazon Quick のAIによるビジュアライズ生成機能