Athena 工具¶
讓 Agent 對 AWS Athena 下查詢，把查到的資料用來回答。可透過連結器連到指定的 AWS 設定，不填則使用平台預設 AWS 設定。
開始前
Athena 可使用 AWS 類型的連結器提供連線設定；若不填，會使用平台預設的 AWS 設定。需要時請先建立連結器，見 連結器資源。
預設唯讀，保護資料
Athena 工具預設為「唯讀」，只允許查詢、不允許寫入。除非你清楚風險，建議保持開啟。
「描述」決定 Agent 會不會用對工具
Agent 是靠每個工具的「描述」（Description）判斷何時、該不該用它。描述寫得越清楚具體，Agent 越能在對的時機正確使用；寫得太籠統，可能該用時沒用、或用錯場合。建議寫明這份資料的內容與查詢時機。
操作步驟¶
- 進入要設定的 Agent，點「編輯」。
- 展開「自訂工具」區塊，點表格中央的「+」圖示鈕。
- 在工具清單中選擇「Athena」。
- 填入「名稱」與「描述」。
- 視需要選擇「連結器」（AWS 類型）與預設「資料庫」。「連結器」的挑選對話框裡請點該列「名稱」以外的任一格（或列前面的選鈕）來選取，再按對話框右上角的「儲存」——點「名稱」會在新分頁開啟該資源的詳細頁，不會選取它（見資源挑選欄位）。
- 在「執行與輸出設定」選「工作群組」或「輸出位置」，選好之後下方才會出現對應的欄位，把值填進去（見下方執行與輸出設定怎麼選）。
- 視需要填「目錄」，並確認「唯讀」保持開啟。
- 點「儲存」，回到 Agent 設定後再按一次「儲存」才會生效。
欄位說明¶
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| 名稱（Name） | 是 | （無） | 工具識別名稱，同一 Agent 內不可重複。 |
| 描述（Description） | 是 | （無） | 說明這份資料的內容與查詢時機。 |
| 連結器（Connector） | 否 | 平台預設 AWS 設定 | AWS 類型的連結器；不填則使用平台預設 AWS 設定。 |
| 資料庫（Database） | 否 | （無） | 預設查詢的資料庫／schema；可在執行時覆寫。 |
| 執行與輸出設定（Execution Setting Type） | 是 | （無） | 一個下拉選單，兩選一：「工作群組」或「輸出位置」。選好之後，下方才會多出一個對應的必填欄位（見下方對照表）。 |
| 工作群組（Workgroup） | 是（選「工作群組」時） | （無） | 上面選「工作群組」時才出現。填 Athena 工作群組名稱，查詢結果會存到該工作群組預設的輸出位置。 |
| 輸出位置（Output Location） | 是（選「輸出位置」時） | （無） | 上面選「輸出位置」時才出現。填一個 S3 路徑（s3://…），查詢結果會存到這裡。 |
| 目錄（Catalog） | 否 | （無） | Athena 的資料目錄名稱。留空就不指定目錄，交由 Athena 使用它自己的預設目錄，所以一般情況不用填；只有當你的資料表登記在另一個自訂目錄裡時才需要指定，值請向工程同事確認。 |
| 唯讀（Read Only） | 否 | 開啟 | 開啟後只允許 SELECT / WITH / SHOW / DESCRIBE / EXPLAIN，並拒絕多語句查詢。 |
| 顯示名稱 / 標籤 | 否 | （無） | 顯示名稱與標籤，位於進階設定。 |
執行與輸出設定怎麼選¶
Athena 每次查詢都要有地方存結果，這個下拉就是在問「結果要存哪」。不確定該選哪個、值是什麼，請工程同事給你其中一個值照填即可。
| 選項 | 適合 | 要填什麼 |
|---|---|---|
| 工作群組（Workgroup） | 公司已經有 Athena 工作群組在管查詢設定（多數情況） | 下方的「工作群組」欄位填工作群組名稱，沿用它預設的輸出位置。 |
| 輸出位置（Output Location） | 要把查詢結果寫到指定的 S3 位置 | 下方的「輸出位置」欄位填一個 s3://… 路徑。 |
換選項會清掉原本填的值
在「執行與輸出設定」改選另一個選項時，原本填的值會被清空，需要重新填——這是為了避免留下兩種設定混在一起。
實際效果¶
設定好之後，當使用者問到 Athena 裡的資料，Agent 會自動把問題轉成查詢語句、透過連結器連到 Athena 執行，再用查回來的資料作答。對話會以可展開的卡片，依序顯示：
- 使用 …查詢相關資訊：Agent 送出的查詢語句（例如一段
SELECT）。 - 接收 …的查詢結果：Athena 回傳的資料列。
- 最後 Agent 根據查到的資料整理出回答。
本頁沒有執行畫面的截圖——請這樣自行判讀
這個工具要接上你自己的 Athena 才會有結果，畫面內容完全取決於你的資料表，所以本頁不放截圖。設定完成後，在 Agent 的對話中問一個相關問題，點開回覆上方的「顯示思考過程」（見與 Agent 對話），用下面三種情況對照，就能判斷是正常還是哪裡沒設好：
- 正常：時間軸會出現一張「使用 <你在「名稱」填的工具名稱>…」卡片，點開看得到 Agent 這次送出的查詢語句；緊接著一張「接收 …的查詢結果」卡片，裡面是查回來的資料列。最後才是整理過的回答。
- 卡片出現了，但結果是空的或紅字錯誤：代表工具有被呼叫，問題在連線或查詢範圍（例如資料庫／目錄填錯、工作群組沒有權限、查詢結果真的是零筆）。把卡片裡的錯誤訊息整段複製給負責這份資料的工程同事看，最快。
- 完全沒有工具卡片：Agent 根本沒想到要用它。這幾乎都是「描述」寫得不夠具體——回到工具設定，把「描述」改成明確寫出「這份資料裝什麼、什麼問題該來這裡查」，再重開一段新對話試一次。