本頁面概略說明如何在Cloud de Confiance 控制台使用 Agent Studio。
Agent Studio 是 Cloud de Confiance 控制台中的低程式碼視覺化設計工具，可簡化代理開發作業。您可以透過視覺化方式規劃 Agentic Workflows、即時測試回覆，並嘗試不同設定，再著手部署或銜接程式碼。
本文將簡要介紹 Agent Studio，並說明如何設定環境、建立及測試代理程式，以及直接將代理程式部署至正式版執行階段。
設定環境
使用 Agent Studio 前，請先設定Cloud de Confiance by S3NS。
取得必要角色
如要取得使用 Agent Studio 的權限，請要求管理員授予您專案的Agent Platform 使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
建立虛擬服務專員
您可以在 Agent Studio 中使用提示或流程建構工具建立代理。
使用提示詞建立代理
請按照下列步驟，使用提示建立代理程式：
前往 Cloud de Confiance 控制台的「Agents」頁面。
點選「建立代理」，開啟新代理的 Agent Studio 畫布。
在對話方塊中輸入提示詞，描述代理程式的用途和預期行為。
按一下「」。
視提示而定，系統會執行下列其中一項操作：
成功：流程建構工具會立即更新，顯示代理程式的即時預覽畫面，且聊天室會提供所做修改的摘要。系統會自動儲存所有變更。
需要釐清：如果提示不夠明確，助理會在對話中提問，進一步瞭解您想建構的內容。
錯誤：如果助理無法套用提示，系統會顯示錯誤訊息，要求您重新撰寫要求。
您可以繼續使用提示或流程建構工具更新代理。
如要儲存服務專員，請按一下畫布標題中的「儲存」，然後按照提示操作。詳情請參閱「儲存代理程式」。
如要在建構代理時測試代理的功能和回覆，請按一下「預覽」分頁標籤，然後與代理對話。
限制
使用提示建立代理程式時，請注意下列限制：
| 功能 | 限制 |
|---|---|
| 資訊 | 無法將知識新增至代理。您可以使用流程建構工具介面，將知識新增至代理程式。 |
使用流程建構工具建立代理
請按照下列步驟，使用流程建構工具設計及測試代理：
前往 Cloud de Confiance 控制台的「Agents」頁面。
點選「建立代理」，開啟新代理的 Agent Studio 畫布。
在 Agent Studio 畫布設計及儲存代理。您可以建立主要代理，並新增子代理。主要代理程式一律為本機代理程式。 子代理可以是本機代理或 Agent Registry 代理：
- 本機代理：直接在 Agent Studio 畫布中編寫及設定指令、模型和工具的代理。
- Agent Registry 代理：在 Agent Registry 中註冊及發布的代理。您可以在主要代理的流程中，將這些代理當做遠端子代理使用。
設計時，您可以在下列「Flow」和「Preview」分頁之間切換：
Flow
使用代理工作流程和控制邏輯的圖形表示法，建立主要代理和子代理。
- 按一下代理，開啟該代理的「詳細資料」面板。您也可以按一下「新增子代理」 (+)，新增子代理。
在「Details」(詳細資料) 面板中設定主要代理和子代理：
主要代理和當地子代理：
- 名稱：新增名稱，以便識別代理程式。
- 說明：簡要說明代理的用途。
- 指令：新增指令來引導代理。
- 模型：選取要驅動代理的模型。
- 工具：點選「新增工具」 (+) 即可新增工具，讓代理完成工作。詳情請參閱「設定及新增工具」。
子代理 (本機或來自 Agent Registry)：
子代理來源：選取子代理的來源：
選取已註冊的代理人後，系統會從註冊表匯入其名稱和說明，並在畫布上設為唯讀。上層代理會根據子代理的代理卡，將工作轉送給子代理。
如要執行或部署上層代理，上層代理的身分必須具備探索及叫用 A2A 子代理的權限。權限對話方塊會自動處理這項動作。如要手動管理權限，請參閱「授予 Agent-to-Agent (A2A) 委派存取權」。
如要儲存服務專員，請按一下畫布標題中的「儲存」，然後按照提示操作。詳情請參閱「儲存代理程式」。
預覽
在預覽窗格中與代理對話，測試其功能和回覆。
- 如要預覽已儲存的代理程式，Agent Studio 會驗證代理程式的身分權限。如果缺少必要角色，系統會顯示通知。按一下「管理」，開啟權限對話方塊，並管理代理程式身分權限。
- 您可以檢查每個代理執行作業的事件，對代理行為進行偵錯。詳情請參閱「檢查代理程式事件」。
按一下「取得程式碼」，即可查看代理程式碼。如要在其他地方繼續開發代理程式，可以複製程式碼並貼到所選的程式碼編輯器。
如果代理程式使用代理程式登錄中的遠端子代理程式，產生的 Python 程式碼會包含對
AgentRegistry.get_remote_a2a_agent的呼叫，以便在執行階段動態解析子代理程式。
代理完成後，即可直接從 Agent Studio 部署。詳情請參閱「從 Agent Studio 部署代理程式」。
在 Studio 提示詞中使用「代理」模式切換鈕建立代理
切換至「Agents」模式，即可直接從 Agent Studio 歡迎提示詞開始建構代理。啟用後，直接提交提示詞會在代理設計工具畫布中啟動代理建構工具。
請按照下列步驟，從 Studio 提示詞建構代理程式：
前往 Cloud de Confiance 控制台的「Agent Studio」。
在歡迎工作區的主要提示詞輸入區域，找到模式切換鈕。
將切換鈕切換至「代理程式」模式。
輸入提示詞，說明要設計的代理用途、工作流程和行為。
按一下「」。
Agent Studio 會直接在代理設計工具畫布中啟動代理建構工具，並根據提示詞預先填入代理流程和設定。接著，您可以繼續編輯指令、選取模型，以及新增工具或子代理。
檢查代理事件
檢查事件有助於對代理的行為進行偵錯，以及排解問題並追蹤代理的推理過程和模型要求。
您可以在 Agent Studio 的「預覽」分頁中檢查代理程式事件，藉此偵錯代理程式執行作業。這項動作可讓您診斷代理程式在執行期間產生的個別事件問題。
如要檢查代理程式事件，請按照下列步驟操作：
- 在 Agent Studio 畫布中開啟代理，然後開啟「Preview」(預覽) 分頁。
- 在預覽窗格中與代理對話，即可開始執行。
選取對話中的事件，即可開啟詳細資料。可用的詳細資料取決於事件，可能包括：
- 作者：產生事件的代理或子代理。使用作者來識別多代理工作流程中，哪個子代理執行了步驟。
- 要求和回覆：傳送至模型的酬載和傳回的回覆。
- 工具呼叫：代理執行期間傳遞至工具的引數。
- 中繼資料：其他診斷資訊，例如型號名稱、權杖用量和時間戳記。
如果代理在預覽期間傳回錯誤，錯誤會顯示在「Preview」(預覽) 分頁中，方便您診斷問題。
儲存代理
您必須先儲存代理，才能預覽、部署或上傳知識檔案，因為未儲存的代理還沒有身分。這項規定也適用於代理儲存庫子代理。
此外，您也必須先儲存代理，才能將 Agent Registry 中發布的 MCP 伺服器新增為節點層級工具。
首次儲存代理：
在 Agent Studio 畫布中，按一下「儲存」。
在「Save Agent」(儲存代理) 對話方塊中，輸入「Agent name」(代理名稱)。
按一下 [儲存]。
首次儲存後，Agent Studio 會自動儲存後續變更。如果您嘗試在儲存新代理程式前離開畫布，Agent Studio 會提示您先儲存。
更新代理
如要更新代理程式，請按照下列步驟操作：
前往 Cloud de Confiance 控制台的「Agents」頁面。
在要更新的代理上，按一下 ，然後按一下「編輯」。
使用提示或流程建構工具更新代理。
Agent Studio 會自動儲存變更。
在 Agent Studio 設定及新增工具
您可以為代理設定下列工具：
Google 搜尋：允許代理使用 Google 搜尋執行網頁搜尋。 預設為開啟。
網址背景資訊：讓模型分析傳送至代理的提示詞中的網址。預設為開啟。
Agent Registry 中的 MCP 伺服器：將 Agent Registry 中發布的 MCP 伺服器附加為節點層級工具。你必須先儲存代理程式，才能使用這個選項。詳情請參閱「儲存代理」。
- 按一下「Agent Registry 中的 MCP 伺服器」旁的「新增」 (+) 圖示。
- 位置：選取區域，篩選已註冊的工具。
- MCP 伺服器：從清單中選取已註冊的 Google MCP 伺服器。
- 驗證設定：選取「None」(無)，即可使用透過 IAM 繫結解析的標準服務存取權。
- 按一下「新增」。
- 如果是首次儲存代理，請按一下畫布標頭中的「Save」(儲存)。後續變更會自動儲存。
代理可以存取已連結 MCP 伺服器的所有工具。
遷移舊版工具
為協助透過 Agent Registry 強化安全性及標準化工具管理，Agent Studio 將淘汰與 Vertex AI Search 資料儲存庫的直接整合，以及直接 Model Context Protocol (MCP) 伺服器。
對於現有代理，這些已淘汰的工具會變成唯讀狀態。如要維持完整功能，請改用 Agent Registry 中的 MCP 伺服器。
從舊版 Vertex AI Search 資料儲存庫遷移
如果代理使用已淘汰的 Agent Platform Search 資料儲存庫工具，請遷移至 Agent Registry 中的 Agent Search MCP 伺服器。這項工具在 Agent Registry 中顯示為 discoveryengine.googleapis.com。
連結 Agent Search MCP 伺服器時，必須在代理的操作說明中定義目標服務設定。此外，代理身分也需要存取權限。
如要遷移，請按照下列步驟操作：
- 在 Agent Studio 畫布中開啟代理程式。
- 在「工具」面板中找到 Vertex AI Search 資料儲存庫工具。
- 請記下工具的設定，例如專案 ID、位置和資料儲存庫 ID。
- 建立新的代理並儲存。
- 將 Discovery Engine 檢視者 (
roles/discoveryengine.viewer) 角色授予代理身分。建議您直接在目標資料儲存庫或搜尋應用程式中授予這個角色。不過，為了排解問題，您可以授予專案的存取權。如要找出代理程式的身分主體並授予角色，請參閱「手動管理角色」。代理也需要 MCP 工具使用者角色 (roles/mcp.toolUser)，權限對話方塊會自動授予這項角色。 - 在「工具」面板中，按一下「Agent Registry 中的 MCP 伺服器」旁的「新增」 (+)。
- 指定下列資訊：
- 位置：選取工具的註冊區域。
- MCP 伺服器：從已註冊的 MCP 伺服器清單中，選取「代理程式搜尋」或
discoveryengine.googleapis.com。 - 驗證設定：選取「無」。存取權是透過標準 IAM 繫結解決。
- 按一下「新增」。
在新代理的操作說明中，使用步驟 3 記下的值指定目標服務設定。例如：
Use the search tool to answer questions about YOUR_TOPIC. When using the search tool, use this servingConfig: projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search如果是搜尋應用程式，請將
dataStores/DATA_STORE_ID替換為engines/APP_ID。如需支援的格式和引數，請參閱 MCP 工具參考資料：discoveryengine.googleapis.com。
從舊版直接 MCP 伺服器遷移
如果代理使用端點網址直接連線至 MCP 伺服器，您必須先在 Agent Registry 中註冊 MCP 伺服器目錄。
如要遷移工具，請按照下列步驟操作：
- 確認 MCP 伺服器已在 Agent Registry 中註冊。
- 在 Agent Studio 更新代理：
- 在 Agent Studio 畫布中開啟代理。
- 找出並移除舊版直接 MCP 伺服器連線。
- 按一下「Agent Registry 中的 MCP 伺服器」旁的「新增」 (+) 圖示。
- 從清單中選取已註冊的 MCP 伺服器。
- 按一下「新增」。
- 如果是首次儲存代理程式，請按一下畫布標題中的「儲存」。後續變更會自動儲存。
以知識檔案為虛擬服務專員提供資訊
在 Agent Studio 上傳靜態參考文件，讓代理程式的回覆內容有所依據：
- 在畫布上選取要附加參考檔案的上層代理節點。請注意，您無法將知識檔案附加至子代理。
- 在節點的「詳細資料」面板中，找到「知識」部分。只有在首次儲存代理程式後，才會顯示「知識」部分。詳情請參閱「儲存代理」。
- 按一下檔案上傳元件，然後瀏覽並選取參考檔案。
每個代理最多可附加 10 個檔案。檔案大小不得超過 2 MB。上傳畫布支援下列檔案類型：
- 純文字
如果是首次儲存服務專員，請按一下畫布標題中的「儲存」，將檔案儲存在專屬的 Cloud Storage bucket 中，路徑前置字元與上層代理的
AGENT_ID相符。後續變更會自動儲存。權限對話方塊會將 bucket 的 Storage 物件檢視者角色 (
roles/storage.objectViewer) 授予代理的身分。前往「預覽」分頁，提交測試查詢，確認代理會根據檔案內容提供回覆，不會產生幻覺。
選用：您可以點選「Get code」(取得程式碼)，複製生成的 Python 程式碼 (
agent.py)，並檢查基準檔案設定。你可以略過這個步驟。
管理代理程式身分權限
Agent Studio 中的每個代理都有專屬身分，可做為 IAM 主體存取其他 Cloud de Confiance by S3NS 資源。
主要格式為：
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID
更改下列內容：
ORGANIZATION_ID：組織的數字 ID。PROJECT_NUMBER：您Cloud de Confiance by S3NS 專案的專案編號。LOCATION：部署代理的區域。REASONING_ENGINE_ID：推論引擎的資源 ID。
如要進一步瞭解代理程式身分，請參閱「建立具有代理程式身分的代理程式」和「代理程式身分總覽」。
權限對話方塊行為
當您按一下「部署」或開啟已儲存代理程式的「預覽」分頁時，Agent Studio 會自動檢查代理程式的身分是否具備順利執行所需的 IAM 角色。如未正確設定，缺少某些權限可能會導致代理故障。將這些權限授予代理的身分，有助於正常運作。
如果系統偵測到任何權限問題，權限對話方塊會顯示錯誤訊息。
- 缺少角色：如果缺少必要角色，系統會顯示對話方塊，列出詳細角色。在對話方塊中按一下「授予全部」，即可透過單一動作，自動將所有必要角色授予代理程式的身分。如要在不授予角色的情況下預覽或部署代理程式，請按一下「仍要繼續」。
- 已授予所有角色：如果已授予所有必要角色，系統就不會顯示權限對話方塊。
- 未儲存的代理：未儲存的代理尚未有身分。在您儲存代理之前，系統不會顯示權限對話方塊，且「Preview」(預覽) 分頁和「Deploy」(部署) 選項會停用。
必要的角色
權限對話方塊會自動授予下列角色：
roles/storage.objectViewer：如果代理程式使用上傳的檔案，則為必要欄位。您必須在代理程式檔案的特定 Cloud Storage bucket 上授予這個角色 (例如{projectNumber}_{location}_agent_studio_files)。roles/mcp.toolUser：如果代理使用 Agent Registry MCP 工具，則必須提供。roles/agentregistry.viewer：如果代理使用 Agent Registry MCP 工具或子代理，則必須提供。roles/iamconnectors.user：如果 Agent Registry MCP 工具指定authProviderName，則為必要。roles/aiplatform.viewer：如果代理透過 Agent-to-Agent (A2A) 委派叫用遠端子代理，則必須提供。
在 Cloud de Confiance 控制台中手動管理角色
權限對話方塊會自動授予必要角色。不過，如果您偏好手動管理角色，或需要排解權限問題，請按照下列步驟操作：
複製代理的專屬身分主體。在 Agent Studio 畫布標題中，點選代理名稱旁的下拉式選單，然後複製主體字串。
主體格式如下所示：
principal://agents.global.org-ORG_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID前往 Cloud de Confiance 控制台的「IAM」頁面：
在主體清單中搜尋代理身分主體。您可以使用主體字串結尾的特定
REASONING_ENGINE_ID進行搜尋。如要取得代理程式身分主體，請採取下列任一做法：- 如果代理身分主體已列出，請點選代理身分旁的 「編輯主體」。
- 如果未列出代理身分主體，請按一下「Grant access」(授予存取權)，將其新增為新主體。
新增或修改設定所需的角色，例如
roles/storage.objectViewer或roles/mcp.toolUser。按一下 [儲存]。
視設定而定，您可能需要手動授予權限對話方塊未自動處理的其他角色。舉例來說，如果已註冊的 MCP 工具存取其他 Cloud de Confiance by S3NS 資源 (例如查詢 BigQuery 中的資料)，您必須手動將必要角色 (例如 BigQuery 資料檢視者 (roles/bigquery.dataViewer) 角色) 授予代理程式的身分。
從 Agent Studio 部署代理
建立並預覽代理後，即可部署至正式環境。請按照下列步驟，從 Agent Studio 部署代理：
- 在「代理程式」清單頁面中，按一下要部署的代理程式。 系統會顯示所選代理的「代理詳細資料」頁面。
按一下「Deploy」(部署)，開啟「Deploy to an Agent Runtime instance」(部署至 Agent Runtime 執行個體) 對話方塊。
如果代理程式的身分缺少必要權限，系統會顯示權限對話方塊，並自動處理這項操作。如要手動管理權限，請參閱「管理代理程式身分權限」和「授予代理程式對代理程式 (A2A) 委派的存取權」。
在部署設定視窗中，設定下列選項：
- 顯示名稱和說明：編輯顯示名稱，並視需要為代理程式新增說明。
- 部署為 A2A：選取這個核取方塊，將代理部署為 Agent-to-Agent (A2A) 資產，供其他代理重複使用。如果是獨立應用程式，請取消選取核取方塊，將代理程式封裝為標準 ADK 應用程式。
從可用區域清單中選取部署區域，然後按一下「OK」(確定)。
點選「Deploy」(部署)。
部署作業會建立新的執行階段例項，最多可能需要五分鐘才能完成。成功後，Agent Studio 畫布的「Flow」分頁會顯示訊息。代理現已可用於正式環境，並可安全整合外部應用程式。
查看已部署的代理
如何查看已部署的代理：
前往 Cloud de Confiance 控制台的「Agent Platform Deployments」(Agent Platform 部署作業) 頁面。
使用「Region」(區域) 清單，依部署區域篩選。
清單中會顯示所選專案中已部署的代理。
按一下指定代理的名稱。系統會開啟該代理程式的「指標」頁面。
選取「Playground」分頁標籤，測試代理。
在對話窗格中輸入測試查詢，確認代理是否成功執行。
如要進一步瞭解代理程式可用的指標，請參閱「查看已部署代理程式的指標」。