總覽

在本實驗室，您將整合 LangChain AI 代理與 Flutter 應用程式。具體做法是以 Flutter 做為用戶端應用程式框架，Gemini Enterprise Agent Platform 的 Agent Search 做為向量資料庫，並透過 Gemini Enterprise Agent Platform 的 Agent Runtime 建構及部署 LangChain 代理。這個代理會運用 Gemini 模型，根據文字和圖片提示詞生成 AI 回覆。Gemini 是一個模型系列，提供多種功能強大的大型語言模型 (LLM)。

本實驗室已預先佈建使用 code-server 的 VS Code IDE，以及執行 Flutter 應用程式所需的 Flutter 和 Dart 擴充功能。此外，實驗室提供 fwr 工具，可以將 Flutter 應用程式做為網頁應用程式執行，並透過瀏覽器存取。

本實驗室適合開發人員 (資歷不限)，尤其是參與應用程式開發，但可能不熟悉雲端應用程式開發的人。如果擁有 Python 使用經驗並熟悉 Flutter 框架，將能更快上手。即使不瞭解 Flutter，也能完成本實驗室，但過程中仍需查看一些 Flutter 應用程式程式碼，並測試應用程式功能。

目標

在本實驗室，您會執行下列工作：

• 在 Google Cloud 控制台，使用 AI Applications 建立搜尋資料儲存庫和搜尋應用程式。

• 使用 Gemini Enterprise Agent Platform Workbench 部署 LangChain 代理。

• 使用整合 Agent Search 和 LangChain 代理的 Python 應用程式。

• 將應用程式部署至 Cloud Run，做為 Flutter 應用程式的後端。

• 建立 Flutter 應用程式，做為前端對話應用程式。

  本實驗室使用的各種元件如下：

  

設定

每個實驗室都會提供新的 Google Cloud 專案和一組資源，讓您在時限內免費使用。

1. 請以無痕視窗登入 Google Skills。

2. 請記下實驗室時間限制 (例如 1:15:00)，務必在時限內完成作業。
   研究室不提供暫停功能。如有需要，您可以重新開始，但原先的進度恕無法保留。

3. 準備就緒後，請按一下「Start lab」。

4. 請記下研究室憑證 (使用者名稱和密碼)，這組資訊將用於登入 Google Cloud 控制台。

5. 按一下「Open Google Console」。

6. 按一下「Use another account」，然後複製這個研究室的憑證，並貼入提示訊息。
   如果使用其他憑證，系統會顯示錯誤或向您收取費用。

7. 接受條款，然後略過資源復原頁面。

工作 1：建立搜尋資料儲存庫和搜尋應用程式

在這項工作，您將在 Google Cloud 控制台，使用 AI Applications 建立搜尋資料儲存庫和搜尋應用程式，為 Flutter 應用程式導入搜尋功能。

建立搜尋資料儲存庫

1. 在 Cloud 控制台，點選「查看所有產品」。接著在「所有產品」頁面，捲動至「人工智慧」專區，然後點選「AI Applications」。

2. 點選「繼續並啟用 API」。

3. 點選左側窗格中的「資料儲存庫」，前往「資料儲存庫」頁面，並按一下「建立資料儲存庫」。

   在這個頁面，您將設定搜尋結果的資料來源。本實驗室預先佈建的 Cloud Storage bucket 有一個 .csv 檔案，其中收錄了 Google 商品商店的品項資料。

4. 接著要選取 Cloud Storage 做為資料來源。請點選「Cloud Storage」下方的「選取」。

5. 對於要匯入的資料類型，請選取「匯入結構化資料」底下的「CSV (適用於常見問題資料)」。

6. 捲動至「選取要匯入的資料夾或檔案」專區，然後點選「檔案」。

7. 點選「瀏覽」，並提供 CSV 檔案的 Cloud Storage 網址。

8. 再來要查看 Cloud Storage bucket 的內容，請點選 。

9. 選取 goog_merch.csv 檔案，然後點選「選取」。

   系統會填入資料夾的 gs:// URI。

   

10. 點選「繼續」。

11. 資料儲存庫名稱請輸入 goog-merch-ds，然後點選「繼續」。

12. 保留預設選取的計費模式，然後點選「建立」。

    系統會隨即建立資料儲存庫，並開始擷取 CSV 檔案中的資料。

13. 在「資料儲存庫」頁面找出剛建立的資料儲存庫，然後點選該儲存庫的名稱。

14. 點選「重新整理」。

    「文件」分頁會列出已匯入的文件。

15. 點選「查看文件」來查看文件相關資料。

點選「Check my progress」，確認目標已達成。 建立 Agent Search 資料儲存庫。

建立搜尋應用程式

將搜尋資料儲存庫與 AI Applications 中的搜尋應用程式連結，開始使用該儲存庫。

1. 在 Cloud 控制台，依序點選「AI Applications」和「應用程式」。

2. 點選「建立新的應用程式」。

3. 在「建立應用程式」頁面中，選擇要建構的應用程式類型時，點選「搜尋與助理」分頁標籤，然後按一下「自訂搜尋 (一般)」底下的「建立」。

4. 在「搜尋應用程式設定」頁面，為「網站」搜尋應用程式指定下列設定，其餘項目則保留預設值：

   屬性	值 (輸入或選取)
   Enterprise 版功能	停用
   應用程式名稱	gms-search-app
   貴公司或組織的外部名稱	gms-company
   應用程式位置	global (全球)

5. 點選「繼續」。

6. 系統會列出現有的資料儲存庫，請選取前一項子工作建立的「goog_merch_ds」資料儲存庫，然後點選「繼續」。

7. 保留預設選取的定價方案，然後點選「建立」。

   系統便會建立搜尋應用程式，並將資料儲存庫連結至該應用程式。

8. 現在要測試搜尋應用程式。請在 AI Applications 導覽選單中點選「預覽」。

9. 在「搜尋」欄位輸入 dino，然後按下 Enter 鍵。

   系統會列出相關搜尋結果，這些結果來自資料儲存庫中匯入的文件。

   

   注意：如果看到「搜尋結果預覽畫面尚未準備就緒」的錯誤訊息，請稍候片刻再重試。不想等待的話，也能繼續進行實驗室的下一項工作。

點選「Check my progress」，確認目標已達成。 建立 Agent Search 應用程式。

工作 2：建構及部署後端

Flutter 應用程式的後端會在 Google Cloud 以 Cloud Run 服務的形式執行。這個後端服務會與您在前一項工作中建立的搜尋應用程式整合，根據商品商店資料生成搜尋回覆。

在後續工作中，您也會將後端應用程式與 LangChain 代理整合，以便透過 Gemini 利用 AI 生成內容，回覆來自 Flutter 應用程式的查詢。

在這項工作，您將建構後端 Python 應用程式並部署至 Cloud Run。

設定及檢查後端應用程式

1. 本實驗室已預先佈建以 VS Code 為基礎的 IDE。現在我們要存取 IDE。請從實驗室的憑證面板複製 IDE 服務網址，然後貼到新的瀏覽器無痕視窗或分頁。

   

   注意：IDE 服務網址是本實驗室預先佈建的 Cloud Run 服務端點，會透過 Proxy 傳送要求到 code-server VM。這個 IDE 是以 Code Server 建構而成，包含 Flutter、Dart 和 Vim 擴充功能。

   

2. 在 IDE 中開啟終端機。點選 IDE 導覽選單圖示 ，然後依序按一下「Terminal」>「New Terminal」。

   注意：請在 IDE 終端機視窗中執行下列步驟中的指令。

3. 本實驗室已預先佈建後端應用程式的初始版本和相關檔案。請從 Cloud Storage 中的封存檔，複製後端應用程式初始版本資料夾及內容：

   gcloud storage cp gs://cloud-training/OCBL453/photo-discovery/ag-web.zip ~ && unzip ~/ag-web -d ~ && rm ~/ag-web.zip 注意：出現提示訊息時，請點選「Allow」，以便貼上剪貼簿中的文字和圖片，然後按下 Enter 鍵。

4. 在 IDE 終端機視窗中執行下列指令，列出資料夾內容：

   ls ~/ag-web/app

   ag-web/app 資料夾包含後端應用程式的原始碼及其他檔案，建構應用程式並部署到 Cloud Run 時，需要使用這些項目。

5. 指定應用程式的 PROJECT_ID 和 LOCATION 設定。

   sed -i 's/GCP_PROJECT_ID/{{{project_0.project_id|set at lab start}}}/' ~/ag-web/app/app.py sed -i 's/GCP_REGION/{{{project_0.default_region|set at lab start}}}/' ~/ag-web/app/app.py

6. 將後端應用程式設為使用先前建立的搜尋資料儲存庫。

   sed -i 's/SEARCH_DATASTORE_ID/{YOUR_SEARCH_DATASTORE_ID}/' ~/ag-web/app/app.py

   將指令中的 {YOUR_SEARCH_DATASTORE_ID} 字串改成搜尋資料儲存庫的 ID，並記得移除 sed 指令中的大括號「{ }」。

   注意：如需搜尋資料儲存庫的 ID，請在 Cloud 控制台依序前往「AI Applications」>「資料儲存庫」，點選先前建立的搜尋資料儲存庫名稱，然後複製資料儲存庫 ID (與搜尋引擎 ID 相同)。

   

7. 接著要在 IDE 中查看程式碼。請點選 IDE 導覽選單中的 ，然後按一下「Open Folder」。

8. 從清單中選取 IDE-DEV/ag-web/ 資料夾，然後點選「Ok」。

9. 點選「Yes, I trust the authors」來表示您信任程式碼的作者。

10. 在「Explorer」窗格中展開 app 資料夾，然後點選 app.py，在編輯器中開啟檔案。

    後端應用程式的程式碼會執行下列作業：

    • 初始化 SearchServiceClient，以便應用程式呼叫 discoveryengine.googleapis.com API。
    • search_gms() 函式會使用 API 的 datastores 端點發起搜尋要求，並在網址中使用您先前建立的資料儲存庫 ID。
    • 該函式會用使用者提供的搜尋查詢，搜尋資料儲存庫中的內容，並將結果轉換成 JSON 格式的回覆。
    • 應用程式會使用 flask 將呼叫轉送至個別函式。/ 端點是預設網頁，用於驗證應用程式是否載入成功；/ask_gms 端點則會叫用使用 Agent Search 的 search_gms() 函式。

建構應用程式並部署至 Cloud Run

您可以運用部署指令碼來建構後端應用程式，並部署至 Cloud Run。

1. 在 IDE 中開啟終端機視窗，並切換至後端應用程式資料夾：

   cd ~/ag-web/app

2. 透過 gcloud CLI 向 Google Cloud 驗證身分：

   gcloud auth login

3. 輸入 Y，以便繼續操作。

4. 啟動登入流程：按下 Control 鍵 (Windows 和 Linux) 或 Command 鍵 (macOS)，並點選終端機中的連結。

5. 如果系統向您確認是否要開啟外部網站，請點選「Open」。

6. 點選實驗室學員的電子郵件地址。

7. 系統提示您繼續操作時，請點選「繼續」。

8. 詳閱並同意相關條款，然後點選「允許」，讓 Google Cloud SDK 存取您的 Google 帳戶。

   瀏覽器分頁會顯示驗證碼。

9. 點選「複製」。

10. 返回 IDE 終端機視窗，在顯示「Enter authorization code」的位置貼上驗證碼，然後按下 Enter 鍵。

    此時，您已登入 Google Cloud。

11. 將 deploy.sh 指令碼設為可執行，然後執行該指令碼，在指定的 Cloud Run 區域部署應用程式：

    chmod a+x deploy.sh; ./deploy.sh {{{project_0.project_id|set at lab start}}} {{{project_0.default_region|set at lab start}}}

    應用程式建構完畢並順利部署至 Cloud Run 後，就能在指令碼輸出內容的結尾看到應用程式的端點網址。這個網址是由指令碼中執行的 gcloud run deploy 指令產生。

    注意：這個指令需要時間執行，請等完成後再繼續下一項工作。

測試後端應用程式

您可以存取應用程式的 Cloud Run 端點，測試功能是否正常。

1. 複製上一步產生的應用程式端點網址，並在新瀏覽器分頁中前往該網址。

2. 應用程式載入後，首頁會顯示「Welcome to the ag-web backend app」。

3. 在瀏覽器網址列中，將下列路徑附加至網址結尾：

   /ask_gms?query=dino

4. 檢查應用程式是否利用先前建立的搜尋資料儲存庫傳回結果。

點選「Check my progress」，確認目標已達成。 建立後端應用程式。

工作 3：建立 LangChain 代理

AI 代理是一種應用程式，會運用大型語言模型 (LLM) 的推論和自動調度管理能力，協調外部工具來達成目標。Gemini Enterprise Agent Platform 是 Google 提供的一套產品和工具，可協助您建構 AI 代理，並將代理連結至值得信賴的資料來源。

Gemini Enterprise Agent Platform 的 Agent Runtime 可協助您在 Agent Platform 建構及部署推論代理。LangChain 是一種熱門的 OSS 工具，常用於建構聊天機器人和 RAG 系統。

Agent Platform 為開發人員提供函式呼叫功能，可將 LLM (Gemini) 的輸出內容對應至 Python 函式。您可以使用 Agent Platform SDK，搭配 LangChain 框架專用範本開發及部署代理。

在這項工作，您將使用 Agent Platform Workbench 和 Jupyter 筆記本，建構及部署具有 Python 函式的 LangChain 代理。本實驗室的下一項工作會在生成式 AI 後端應用程式中使用這個代理。

建立 Agent Platform Workbench 執行個體

Agent Platform Workbench 是以 Jupyter 筆記本為基礎的開發環境，支援完整的資料科學和機器學習工作流程。您可以透過 Workbench 執行個體的 Jupyter 筆記本，與 Agent Platform 和其他 Google Cloud 服務互動。舉例來說，您可以利用 BigQuery 和 Cloud Storage 整合功能，在 Jupyter 筆記本內存取及探索資料。

Agent Platform Workbench 筆記本兼具彈性與擴充性，可讓您在 Google Cloud 開發及部署機器學習模型。

1. 首先來建立 Workbench 執行個體。請在 Cloud 控制台依序點選「導覽選單」圖示 、「Agent Platform」和「Notebooks」。

2. 點選「Notebooks」導覽選單中的「Workbench」。

3. 確認「執行個體」分頁中的「執行個體」已選取，然後點選「建立」。

   

4. 在「建立執行個體」頁面的「名稱」欄位中，輸入 my-instance。

5. 其餘設定請保留預設值，然後點選「建立」。

   這個新執行個體會啟動，並出現在「執行個體」專區，請等待建立程序完成，再繼續下一步。

   注意：執行個體可供使用時，旁邊會顯示綠色勾號。

6. 執行個體就緒後，點選「Open Jupyterlab」。

   

7. 點選「Python 3」筆記本，啟動 Python 3 Jupyter 筆記本。

   

複製筆記本檔案

本實驗室已預先佈建筆記本，用來建構及部署 LangChain 代理。

1. 將下列程式碼複製到新筆記本的第一個儲存格，把筆記本複製到 JupyterLab 執行個體：

   !gcloud storage cp gs://cloud-training/OCBL453/photo-discovery/ag-web/ag_setup_re.ipynb .

   

2. 選取該儲存格，然後點選儲存格選單中的「執行」圖示來執行指令：

   

   這個指令會將 Cloud Storage 中的筆記本複製到 JupyterLab 執行個體。指令執行完畢後，筆記本檔案會列在頂層的根資料夾底下。

   

3. 在資料夾清單中按兩下筆記本檔案，開啟筆記本。系統便會在新分頁顯示筆記本內容。

建構及部署 Reasoning Engine 代理

1. 從頭開始依序執行筆記本中所有的程式碼儲存格。執行儲存格的方式是點選其中任一處，再從儲存格選單或頂端的筆記本選單中按一下「執行」圖示。

   注意：請等待當前儲存格的指令執行完畢，再執行下一個儲存格。指令執行完畢時，儲存格編號欄位中的星號 (*) 會變成儲存格的編號。 注意：執行儲存格前，請先查看下方附註，確認是否有相關說明或需遵循的步驟。這些說明前面會標示 CELL INSTR。

   a. [CELL INSTR] 重新啟動目前的執行階段

   如果出現提示，請在「Kernel Restarting」對話方塊中點選「Ok」。

   b. [CELL INSTR] 設定 Google Cloud 專案資訊並初始化 Agent Platform：

   執行這個儲存格可初始化 Agent Platform。執行前，請先更新實驗室的 project_id、位置和暫存 bucket 設定值：

   PROJECT_ID = "{{{project_0.project_id|set at lab start}}}" LOCATION = "{{{project_0.default_region|set at lab start}}}" STAGING_BUCKET = "gs://{{{project_0.startup_script.lab_bucket_name}}}"

   更新後的儲存格，其中使用範例設定：

   

   c. [CELL INSTR] 定義代理：

   執行這個儲存格前，請將 GEMINI_MODEL_ID 改成這個筆記本使用的最新模型 ID：。

   注意：點選筆記本選單列中的「執行」圖示也能執行儲存格。

2. 執行「Deploy the Agent to the Agent Runtime」儲存格後，請等待指令執行完畢並部署 LangChain 代理，然後再複製代理 ID：

   

   在下一項工作中，您將使用這個 ID 來設定及重新部署後端應用程式。

   注意：這個儲存格最多需要 10 分鐘才能執行完畢，請等待最終輸出內容顯示代理已部署，再繼續下一步。

3. 執行後續兩個儲存格並觀察輸出內容，測試 LangChain 代理是否正常運作。

   LangChain 代理會根據查詢輸入內容，成功叫用維基百科或 Agent Search 資料儲存庫。

點選「Check my progress」，確認目標已達成。 部署 LangChain 代理。

工作 4：強化後端應用程式

接著來強化後端應用程式，讓應用程式叫用您在前一項工作部署的 LangChain 代理。

後端應用程式的初始版本只會直接從 Agent Search 擷取結果，但更新後的版本還會叫用代理。這個代理會根據輸入提示詞，使用自己的工具和 Gemini 的輸出內容，從 Agent Search 或維基百科取得資訊並生成回覆。

在這項工作，您將更新後端應用程式的程式碼，新增額外的進入點，用來接收查詢要求並叫用 LangChain 代理，然後傳回代理的回覆。

更新後端應用程式

1. 在 IDE 終端機視窗執行下列指令，將新進入點的程式碼加到 app.py 檔案中：

   cat << EOF >> ~/ag-web/app/app.py # # Agent Engine # import vertexai from vertexai import agent_engines from google.cloud import resourcemanager_v3 def get_project_number(project_id): client = resourcemanager_v3.ProjectsClient() # 建構專案的資源名稱 name = f"projects/{project_id}" # 取得專案中繼資料 project = client.get_project(name=name) # 回應中的「name」欄位會採用「projects/123456789」格式 project_number = project.name.split('/')[-1] return project_number PROJECT_NUM = get_project_number(PROJECT_ID) LANGCHAIN_AGENT = "LANGCHAIN_AGENT_ID" remote_agent = vertexai.agent_engines.get(f"projects/{PROJECT_NUM}/locations/{LOCATION}/reasoningEngines/{LANGCHAIN_AGENT}") # Flask 應用程式用來呼叫代理的端點 @app.route("/ask_gemini", methods=["GET"]) def ask_gemini(): query = request.args.get("query") log.info("[ask_gemini] query: " + query) retries = 0 resp = None while retries < MAX_RETRIES: try: retries += 1 resp = remote_agent.query(input=query) if (resp == None) or (len(resp["output"].strip()) == 0): raise ValueError("Empty response.") break except Exception as e: log.error("[ask_gemini] error: " + str(e)) if (resp == None) or (len(resp["output"].strip()) == 0): raise ValueError("Too many retries.") return "No response received from Reasoning Engine." else: return resp["output"] EOF

2. 將後端應用程式設為使用先前建立的 LangChain 代理。

   將下方指令中的 {YOUR_LANGCHAIN_AGENT_ID} 字串，改成您在前一項工作中從筆記本儲存格複製的代理 ID，然後在 IDE 終端機視窗執行該指令。

   記得移除 sed 指令中的大括號「{ }」。

   sed -i 's/LANGCHAIN_AGENT_ID/{YOUR_LANGCHAIN_AGENT_ID}/' ~/ag-web/app/app.py

3. 接著要在 IDE 查看程式碼。請點選 IDE 導覽選單中的 ，然後選取「IDE-DEV/ag-web/app/app.py」檔案。

   強化版後端應用程式：

   • 會使用前一項工作中所建立代理的 LANGCHAIN_AGENT_ID，從 Agent Runtime 擷取 remote_agent 的控制代碼。
   • 定義了對應至 ask_gemini() 函式的新 /ask_gemini 端點。
   • 該函式會將使用者在要求中提供的 query 參數傳遞給 LangChain 代理 (remote_agent)，並傳回代理的回覆。

建構後端應用程式並重新部署至 Cloud Run

1. 切換至後端應用程式資料夾：

   cd ~/ag-web/app

2. 執行下列指令碼，在指定的 Cloud Run 區域重新部署應用程式：

   ./deploy.sh {{{project_0.project_id|set at lab start}}} {{{project_0.default_region|set at lab start}}}

測試後端應用程式

您可以存取應用程式的 Cloud Run 端點，測試功能是否正常。

1. 複製上一步產生的應用程式端點網址，並在新瀏覽器分頁中前往該網址。

2. 應用程式載入後，首頁會顯示「Welcome to the ag-web backend app」。

3. 在瀏覽器網址列中，將下列路徑附加至網址結尾：

   /ask_gemini?query=where can I buy the chrome dino pin

   代理會從您先前建立的 Agent Search 資料儲存庫擷取結果，應用程式再使用這些結果回覆您。

   Chrome Dino 琺瑯別針是 Google 商品商店販售的產品，價格為 $7.00 美元。您可以在 Google 商品商店網站購買這項產品：https://shop.merch.google/product/chrome-dino-enamel-pin-ggoegcbb203299/。

4. 在瀏覽器網址列中，將路徑改成：

   /ask_gemini?query=what is fallingwater. Write the answer in plaintext.

   代理會從您在筆記本設定的 Wikipedia API 擷取回覆，應用程式再使用回覆中的結果回答查詢。

   Fallingwater (落水山莊) 由建築師 Frank Lloyd Wright 於 1935 年設計，位於賓夕法尼亞州西南部，距離匹茲堡東南部約 70 英里。這座房子有一部分建立在瀑布上方，因此聞名。 注意：您收到的實際回覆可能會與上方顯示的內容有差異。

工作 5：建立 Flutter 前端應用程式

Flutter 是開放原始碼的跨平台應用程式開發框架。使用這套框架編寫的程式碼集，能在 Android、iOS、網頁、macOS、Windows 和 Linux 平台上運作。Flutter 應用程式是以 Dart 程式設計語言開發。

在本實驗室中，您會使用網頁做為目標平台，以便將 Flutter 應用程式部署為可透過瀏覽器存取的網頁應用程式。

在這項工作，您將使用 Flutter 建立簡單的對話應用程式、更新程式碼，並以網頁應用程式形式建構及執行應用程式。

建立 Flutter 應用程式

1. 在 IDE 終端機前往主目錄，並執行下列指令：

   cd ~; flutter create chat_app

   flutter create 指令會建立所有必要的檔案、資料夾和設定，讓新的 Flutter 專案能夠執行。

2. 前往 IDE-DEV/chat_app 資料夾，在 IDE 查看預設對話應用程式的程式碼。

   您可能需要點選「Refresh」，才能重新整理 IDE 中資料夾導覽窗格的內容。

3. 如果系統詢問您是否要信任資料夾內檔案的作者，請點選「Yes, I trust the authors」。

查看 Flutter 應用程式的程式碼

以下簡單說明 chat_app 資料夾內容：

資料夾/檔案	說明
chat_app	專案的根資料夾，內含構成 Flutter 應用程式的子資料夾和檔案。
android/ios/linux/macos/web/windows	存放各個受支援平台執行 Flutter 應用程式所需的檔案，每個平台有各自適用的檔案。
lib	含有核心應用程式 Dart 檔案，包括功能和使用者介面。
test	含有用於測試應用程式小工具的 Dart 測試檔案。
pubspec.yaml	含有應用程式依附元件、Flutter 版本和其他設定
analysis_options.yaml	含有應用程式靜態分析的設定。

接著來看看 Flutter 應用程式的進入點檔案 main.dart。

• 在「Explorer」選單中，點開 IDE-DEV/chat_app/lib/main.dart 檔案。

  這是 Flutter 應用程式的進入點。完成初始化工作後，這個檔案中的程式碼會使用 Material 元件建構應用程式的 UI，並指定應用程式的標題、主題及其他設定。

  注意：Material 應用程式以 MaterialApp 小工具做為建構起點。這個小工具會在應用程式的根層級建立多個實用小工具，包括用於管理應用程式各畫面切換作業的 Navigator。

  Flutter 運用了小工具的概念，這是用於建構應用程式的宣告式類別。在 Flutter 中，您可以將不同小工具組合成更複雜的小工具，形成小工具樹狀結構，藉此建立版面配置。如要進一步瞭解如何在 Flutter 中建構 UI，請參閱這份說明文件。

  這個檔案包含用於建構應用程式小工具的類別，包括：

  • MyApp 類別：對話應用程式的根層級小工具。
  • MyHomePage 類別：使用 _MyHomePageState 類別建立應用程式的主頁面。
  • _MyHomePageState 類別：建構應用程式的 UI，並負責更新 UI 狀態。

  在接下來的子工作，您會在建構對話應用程式時，更改這些類別中預設產生的程式碼。

更新 Flutter 應用程式的程式碼

1. 首先，請更新應用程式標題。在第 14 行的 MyApp 類別中，變更 title 屬性的值：

   title: 'Gemini Chat App',

   

2. 找到 _MyHomePageState 類別，刪除第 58 行的 int _counter = 0;，以及 _incrementCounter() 函式，然後新增下列屬性：

   final TextEditingController _controller = TextEditingController(); final List<Map<String, String>> _messages = []; String _cloudRunHost = '';

   這些屬性用於接受使用者輸入的文字提示詞，並儲存要顯示的使用者輸入內容與後端應用程式回覆，以及後端應用程式 Cloud Run 服務的主機名稱。

3. 將 initState() 方法新增至 _MyHomePageState 類別：

   @override void initState() { super.initState(); _loadConfig(); }

   這個方法會在建立 State 物件時執行初始化作業。在對話應用程式中，我們會叫用接下來要實作的 _loadConfig() 方法來載入檔案內容。

4. 將 _loadConfig() 方法新增至前述類別：

   Future<void> _loadConfig() async { final configString = await rootBundle.loadString('assets/config.json'); final config = json.decode(configString); setState(() { _cloudRunHost = config['cloudRunHost']; }); }

   這個方法會擷取對話應用程式設定檔的內容。該檔案會將 Cloud Run 後端應用程式的主機名稱值儲存在 JSON 物件中。我們會在本實驗室的後續步驟中建立這個檔案。這個方法會將該值儲存在先前建立的內部 _cloudRunHost 屬性中，並建構小工具 UI。

5. 將 _sendMessage() 方法新增至前述類別：

   Future<void> _sendMessage() async { if (_controller.text.isEmpty) { return; } final message = _controller.text; _controller.clear(); setState(() { _messages.add({'sender': 'user', 'text': message}); }); if (_cloudRunHost.isEmpty || _cloudRunHost == 'YOUR_CLOUD_RUN_ENDPOINT_URL') { setState(() { _messages.add({ 'sender': 'bot', 'text': 'Please configure the Cloud Run endpoint in assets/config.json' }); }); return; } try { var endpoint_query = Uri.https(_cloudRunHost, '/ask_gemini', {'query': message}); final response = await http.get(endpoint_query); if (response.statusCode == 200) { var responseText = utf8.decode(response.bodyBytes); responseText = responseText.replaceAll(RegExp(r'\*'), ''); setState(() { _messages.add({'sender': 'bot', 'text': responseText}); }); } else { setState(() { _messages.add({ 'sender': 'bot', 'text': 'Error: ${response.statusCode}' }); }); } } catch (e) { setState(() { _messages.add({'sender': 'bot', 'text': 'Error: $e'}); }); } }

   這個方法會擷取使用者輸入的提示詞文字，並新增至對話面板中顯示的訊息清單，接著將 HTTP GET 要求連同使用者輸入的提示詞，傳送至 Cloud Run 後端服務端點網址，並顯示該服務的回覆。

   這段程式碼會建構 Cloud Run 後端主機端點的網址，並在查詢參數中加入提示詞文字，然後將 HTTP GET 要求傳送至該端點。收到狀態碼為 200 的回應後，系統會將回應解碼，並將結果新增至訊息清單，以便在對話畫面中顯示。如果收到表示結果不成功的回應，或發生例外狀況，系統會將狀態碼或例外狀況訊息加入訊息清單中並加以顯示。

6. 接著要建構對話應用程式 UI。請在 _MyHomePageState 類別中，將現有的 build 方法改成下列程式碼：

   @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: const Text('Gemini Chat App'), ), body: Column( children: [ Expanded( child: ListView.builder( padding: const EdgeInsets.all(8.0), itemCount: _messages.length, itemBuilder: (context, index) { final message = _messages[index]; final isUserMessage = message['sender'] == 'user'; return Align( alignment: isUserMessage ? Alignment.centerRight : Alignment.centerLeft, child: Container( margin: const EdgeInsets.symmetric(vertical: 4.0), padding: const EdgeInsets.all(12.0), decoration: BoxDecoration( color: isUserMessage ? Colors.blue[100] : Colors.grey[200], borderRadius: BorderRadius.circular(8.0), ), child: Text(message['text']!), ), ); }, ), ), Padding( padding: const EdgeInsets.all(8.0), child: Row( children: [ Expanded( child: TextField( controller: _controller, decoration: const InputDecoration( hintText: 'Enter a message', ), onSubmitted: (text) => _sendMessage(), ), ), IconButton( icon: const Icon(Icons.send), onPressed: _sendMessage, ), ], ), ), ], ), ); }

   build 方法用來描述對話應用程式的 UI。這個方法會根據設定和目前狀態建立小工具樹狀結構，然後 Flutter 框架會在畫面上呈現這個結構。在這個對話應用程式的 UI 中，程式碼會以垂直方式顯示對話訊息，並提供文字欄位和傳送按鈕，供使用者傳送提示詞。使用者輸入的訊息 (提示詞) 會顯示在藍色方塊中，而應用程式 (機器人) 的回覆或錯誤訊息則會顯示在灰色方塊中。

   使用者在對話應用程式中點選「Send」，或在文字欄位輸入提示詞後按下 Enter 鍵時，系統就會叫用 _sendMessage() 回呼方法。

新增匯入項目

新增的程式碼需搭配 Dart 和 Flutter SDK 中的特定程式庫或套件。

1. 在 main.dart 檔案開頭現有的 import 陳述式下方，加入下列 import 陳述式，匯入上述套件：

   import 'package:http/http.dart' as http; import 'dart:convert'; import 'package:flutter/services.dart' show rootBundle;
   • http.dart 套件包含一組高階函式與類別，可讓您輕鬆取用 HTTP 資源。
   • dart:convert 程式庫提供多種函式，可處理常見的資料轉換作業，例如 JSON 序列化和 UTF-8 編碼/解碼。
   • rootBundle 屬性是全域靜態物件，可用來存取 Flutter 應用程式隨附的主要資產套件。

2. 在 IDE 導覽選單中，依序點選「File」>「Save」，儲存應用程式變更。

更新依附元件

pubspec.yaml 檔案用於指定 Flutter 應用程式的專案中繼資料、套件依附元件和資產。

1. 首先來編輯 pubspec.yaml。請在 IDE 的「Explorer」窗格中選取該檔案 (位於 chat_app 資料夾)。

2. 在 dependencies 部分，於 cupertino_icons 字型程式庫下方加入 http 套件依附元件：

   http: ^1.6.0 請務必保留正確的空格縮排。

   

3. 捲動至 pubspec.yaml 檔案的 flutter 部分，將第 63 行取消註解，然後在 assets 下方加入 assets 資料夾，並保留空格縮排：

   assets: - assets/

   

   這麼做可設定 assets 資料夾，用來儲存應用程式的 config.json 檔案。

4. 在 IDE 導覽選單中，依序點選「File」>「Save」，儲存 pubspec.yaml 檔案的變更。

將 Flutter 應用程式與 Cloud Run 後端整合

Flutter 應用程式可與您在本實驗室先前步驟部署的 Reasoning Engine 代理整合。整合方式是將 Flutter 應用程式連結至您建構並部署至 Cloud Run 的後端應用程式端點。

您可能已注意到，_sendMessage() 方法中的某段程式碼會檢查 _cloudRunHost 屬性是否空白，或 assets/config.json 檔案中是否未設定該屬性。在這項子工作，我們會將這個檔案新增至 Flutter 應用程式。

1. 首先，請擷取後端應用程式的 Cloud Run 端點主機名稱，並將該值儲存在環境變數中。

   請在 IDE 終端機視窗執行下列指令：

   BACKEND_APP_HOST=$(gcloud run services describe ag-web --region {{{project_0.default_region|set at lab start}}} --format 'value(status.url)' | cut -d'/' -f3); echo $BACKEND_APP_HOST

2. 在 Flutter 對話應用程式的主目錄中建立 /assets 目錄：

   mkdir ~/chat_app/assets

3. 在 /assets 目錄中建立 config.json 檔案：

   cat <<EOF > ~/chat_app/assets/config.json { "cloudRunHost": "$BACKEND_APP_HOST" } EOF

4. 重新整理 IDE「Explorer」選單中的內容，然後點開 IDE-DEV/chat_app/assets/config.json 檔案來確認變更。請確認 cloudRunHost 設定項目值是否已更新為 Cloud Run 後端應用程式的主機名稱。

   注意：這個值應與先前設定的 BACKEND_APP_HOST 環境變數值一致。

部署 Flutter 應用程式

Flutter 應用程式設定完畢後，您就能建構並部署應用程式。在本實驗室中，為了讓應用程式以網頁應用程式的形式運作，我們將使用 Flutter 的網頁應用程式開發伺服器 Fwr。

1. 確認已進入 Flutter 應用程式資料夾。請在 IDE 終端機視窗執行下列指令：

   cd ~/chat_app

2. 執行下列指令，擷取應用程式專案依附元件：

   flutter pub get

3. 執行下列指令，建構專案並啟動網路伺服器：

   fwr

   等待伺服器啟動並提供 Flutter 應用程式。啟動後，指令輸出內容大致如下：

   

工作 6：測試 Flutter 應用程式

接著來測試 Flutter 應用程式的功能。

測試應用程式

1. 從實驗室憑證面板複製「Live Server」網址，然後在新的瀏覽器無痕分頁中開啟，以便存取 Flutter 應用程式。

   等待對話應用程式載入完畢。

2. 在底部的訊息欄位中輸入下列內容：

   什麼是落水山莊？請以明文格式提供答案。

   幾秒後，應用程式中就會顯示後端代理的回覆。

3. 為了測試應用程式和代理，請在訊息欄位中輸入下列內容：

   哪裡買得到 Chrome Dino 別針？

   幾秒後，應用程式中就會顯示後端代理的回覆。

   對話應用程式會呼叫後端應用程式的 /ask_gemini Cloud Run 端點，接著該端點會叫用 LangChain 代理，而這個代理會使用 Gemini，根據 Agent Search 資料儲存庫中的資訊生成並傳回回覆。

4. 將瀏覽器視窗調整至接近行動裝置的大小，查看 Flutter 應用程式切換為行動裝置版面配置的效果：

   

   這表示 Flutter 應用程式能根據螢幕或視窗大小的變化做出調整。您可以運用 Flutter 提供的小工具和套件，讓應用程式能因應裝置設定變更，滿足不同顯示需求。

點選「Check my progress」，確認目標已達成。 開發及測試 Flutter 對話應用程式。

關閉研究室

完成實驗室後，請按一下「End Lab」。Google Skills 會移除您使用的資源，並清除所用帳戶。

您可以為實驗室的使用體驗評分。請選取合適的星級評等並提供意見，然後按一下「Submit」。

星級評等代表您的滿意程度：

• 1 星 = 非常不滿意
• 2 星 = 不滿意
• 3 星 = 普通
• 4 星 = 滿意
• 5 星 = 非常滿意

如果不想提供意見回饋，您可以直接關閉對話方塊。

如有任何想法、建議或指教，請透過「Support」分頁提交。

恭喜！

您在本實驗室中完成了下列工作：

• 在 Google Cloud 控制台，使用 AI Applications 建立搜尋資料儲存庫和搜尋應用程式。
• 運用 Agent Platform Workbench 部署 LangChain 代理。
• 建構整合 Agent Search 和 LangChain 代理的 Python 應用程式。
• 將應用程式部署至 Cloud Run，做為 Flutter 應用程式的後端。
• 開發 Flutter 對話應用程式，並與後端服務整合，以便與 Gemini 互動。

後續行動/瞭解詳情

• Gemini for Google Cloud 簡介
• Agent Platform Workbench
• Gemini Enterprise Agent Platform Studio
• Flutter
• Dart

Copyright 2026 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。