使用連接Agent,讓您的主要Agent將特定工作委派給專門Agent。 本文將說明如何連接透過 Agent2Agent (A2A) 協定可用的遠端代理,讓你的主要代理能將任務交接給它。
Note
用來建置此代理的框架採用基於使用量的計費方式。 使用、建置、測試和評估代理程式可能會消耗 Copilot 點數。 了解更多請參閱 使用量基礎計費概覽。
A2A 協定是代理間通訊與協作的開放標準。 因為它是開放標準,你可以連結那些託管在 Copilot Studio 外、建立在其他框架上的代理程式,只要它們實作 A2A。 Copilot Studio 會透過其代理程式資訊卡探索遠端代理,然後在執行階段使用 A2A 協定將任務委派給它。
你從同一個新增 已連接的代理 對話框新增所有已連接的代理。 關於已連線代理程式的概述及路由運作方式,請參閱 已連線代理程式概述。 若要連接另一位 Copilot Studio 代理,請參見「新增一位 Copilot Studio 代理為已連結代理。 若要連接 Microsoft Foundry 代理程式,請參見「新增 Foundry 代理程式作為已連接代理程式」。
Prerequisites
- 一個使用 Microsoft Copilot 線束創建的代理,作為主要代理。 請參閱建立Agent(預覽版)。
- 一個遠端代理,實作代理對代理協定,並可從 Copilot Studio 透過公用網際網路存取。
- 遠端代理的代理卡網址,通常為
https://<your-agent-host>/.well-known/agent-card.json。 - 遠端代理程式所需的驗證詳細資料(如有)。 Copilot Studio 支援無認證、API 金鑰及 OAuth 2.0。
- 對於 OAuth 2.0,允許遠端代理的身份提供者使用的應用程式註冊中加入一個重定向 URI。 Copilot Studio 會在精靈階段產生重定向 URL,你必須先註冊它才能建立連線。
Note
由於 A2A 連線使用自訂連接器基礎設施,你也可以用它們連接本地或虛擬網路內運行的 A2A 代理。
新增一個 Agent2Agent(A2A)代理程式
設定精靈會根據你選擇的認證方式,引導你完成三到四個步驟:
- 如果你選擇 無 或 API 金鑰:連接 A2A 代理、連接 A2A 代理,然後 檢視並新增。
- 如果你選擇 OAuth 2.0: 連接 A2A 代理, 新增重定向網址, 連接 A2A 代理,然後 檢視並新增。
請登入Copilot Studio。
選擇並開啟你想設為主要代理程式的代理程式。
在代理導覽列中,選擇 「建置 」標籤。
在元件面板中,選取連接的Agent,以開啟新增連接的Agent對話框。
在對話框中,選擇 「新增」,然後選擇 「新增 A2A 代理人」。
在「 連接 A2A 代理 」步驟中,輸入遠端代理的詳細資訊:
-
代理卡 URL:遠端代理的代理卡的網址,例如
https://agent.example.com/.well-known/agent-card.json。 Copilot Studio 會讀取卡片以發現代理的終端點與能力。 - 姓名:顯示給代理人作者的名字。 如果代理程式卡片上有姓名,Copilot Studio 會幫你填補這個欄位。
- 說明:明確說明何時使用該 A2A 代理人,字元介於 30 至 1,000 字元之間。 如果代理程式卡片包含描述,Copilot Studio 會幫你填補這個欄位。 編排器會利用這個描述來決定何時將請求路由給代理,因此請使其具體且避免與其他工具和代理重疊。 了解如何 撰寫有效的元資料。
Note
如果名稱和描述沒有自動填入,遠端代理程式可能沒有代理程式資訊卡,或是該資訊卡的 URL 與你輸入的不一樣,或是 Copilot Studio 無法連線到該資訊卡。 先檢查網址,然後試著在瀏覽器打開 Agent 卡片。 如果卡片無法取得,請手動輸入名稱和說明。
-
代理卡 URL:遠端代理的代理卡的網址,例如
在驗證中,選擇 Copilot Studio 如何向遠端代理程式進行驗證,然後填寫您所選方法的詳細資料:
- 無:遠端代理不需要認證。
- API 金鑰:遠端代理需要 API 金鑰。 請參閱 設定 API 金鑰驗證。
- OAuth 2.0:遠端代理使用 OAuth 2.0。 請參見 「配置 OAuth 2.0 認證」。
在驗證詳細資料完整前,無法繼續。
選取 下一步。
如果你選擇 了 OAuth 2.0,就會顯示 「新增重定向網址 」步驟。 Copilot Studio 會為 A2A 代理建立連接器,平台會為其產生一個重定向 URL。 在建立連線前,請先在你的身分識別提供者中註冊該網址:
- 等 Redirect URL 欄位填好。 連接器必須先存在,URL 才會被產生。
- 選擇欄位旁的複製按鈕以複製網址。
- 在你的 OAuth 應用程式註冊中,將網址加為重定向 URI,並儲存應用程式註冊。
- 選取 下一步。
Important
如果你沒有先註冊重定向網址,第一次嘗試授權連線就會失敗。 重定向 URL 是每個連接器產生的,因此是針對這個 A2A 代理特有的,不能從其他連接器重複使用。 如果你之後需要再次使用該 URL,可以在元件面板的 「已連線代理」 中選擇 A2A 代理,重新開啟該 URL。
在「 連接至A2A代理 」步驟中,選擇該代理用來連接遠端代理的連線:
- 從可用連線清單中選擇一個現有連線。
- 如果沒有連線可用,請建立新的連線。 如果遠端代理使用 API 金鑰認證,您會在建立連線時輸入 API 金鑰值。
選取 下一步。
在 「審查並新增 」步驟中,先檢視姓名、描述和代理人卡片的網址,然後選擇 「加入代理人」。
確認已連線的代理出現在元件面板的 已連接代理 中。
如果你回去更改 Connect to an A2A agent 步驟中的認證設定,Copilot Studio 會丟棄根據先前設定所建立的連接器。 你必須註冊一個新的重定向網址,並重新選擇連線。
Note
你有責任在特定使用情境中仔細審查與測試連接代理,並做出所有適當的決策與客製化。 當您連線到 Copilot Studio 以外的 Agent 時,您必須對這些 Agent 的使用負責。 考量包括確保:
- 資料流、資料處理及代理間資料共享適合您的使用情境,並符合相關要求與法律。
- 代理人符合適當的品質、可靠性、安全性及可信度標準。
- 若對您的使用案例而言合適,系統會配置適當的權限、邊界和核可。
- 適當的可觀察性、身份與可追溯性,以及人工監督功能都已到位。
設定 API 金鑰驗證
選擇 API 金鑰時,請選擇 Copilot Studio 將金鑰傳送到哪裡,方法是選擇參數類型:
-
標頭:金鑰以請求標頭形式傳送。 在 標頭名稱中,輸入遠端代理期望的標頭名稱,例如
x-api-key。 - 查詢字串:金鑰以查詢字串參數形式傳送。 在 參數標籤中,輸入遠端代理所期望的查詢字串參數名稱。
你是在建立連線時輸入 API 金鑰值本身,而不是在這個步驟。 這樣金鑰會隨連線一起儲存,且在代理設定中不會被看見。
設定 OAuth 2.0 驗證
選擇 OAuth 2.0 時,請選擇 設定類型:
動態:Copilot Studio 會幫你向遠端代理的身份提供者註冊客戶。 輸入 授權網址 和 令牌網址。
手續:使用你已建立的應用程式註冊,並使用遠端代理的身份提供者。 輸入下列值:
- 客戶端 ID:你應用程式註冊時的客戶端 ID。
- 用戶端秘密:你應用程式註冊的用戶端秘密。
- 授權網址:身份提供者的授權端點。
- 令牌 URL:身份提供者的令牌端點。
- 刷新令牌網址:用於刷新存取權杖的端點。
- 範圍 (可選):請求範圍,以空格分隔。
當遠端代理的身份提供者支援動態客戶端註冊時,請使用 動態。 當你需要控制應用程式註冊時,例如身份提供者要求預先註冊的重定向 URI 或取得同意時,請使用 手動。
不管是哪種設定類型,都需要您向身分提供者註冊一個重新導向 URL。 選擇「下一步」後,Copilot Studio 會建立連接器,並在「新增重定向 URL」步驟顯示產生的重定向 URL。
稍後尋找重新導向 URL
如果您關閉了向導或遺失了重定向網址,您可以隨時再次查看:
在 建置 標籤中,在元件面板的 「已連接代理」 中選擇 A2A 代理。
在 編輯 A2A 代理 對話框中,複製 Redirect URL 欄位的值。
重定向網址欄位僅顯示於使用 OAuth 2.0 的 A2A 代理程式。
編排者如何路由到A2A代理
加入 A2A 代理後,編排執行時會自動決定何時委派給它。 路由決策基於:
- 已連線的代理程式名稱與說明
- 使用者的訊息與對話上下文
- 您的主要Agent指示
Tip
為 A2A 代理撰寫清晰且具體的描述,讓編排者能準確判斷何時將請求路由到它。 避免已連接的代理程式之間出現描述重疊。
委派測試
加入 A2A 代理人後:
於Agent導覽欄,選取 預覽索引標籤。
發送與 A2A 代理網域相符的訊息。
確認回應是否來自A2A代理人且適當。
發送一則訊息到A2A代理的網域外,確認你的主要代理是否會處理該訊息。
如果你之後需要更改名稱或描述,請從元件面板編輯已連接的代理。 請參閱「在代理程式中管理已連線的代理程式」。
排除連線問題
| Problem | 要檢查的事項 |
|---|---|
| 授權連線時因重新導向 URI 錯誤而失敗 | Copilot Studio 產生的重定向網址並未註冊在你的身份提供者那裡。 從 編輯 A2A 代理 對話方塊複製 URL,將其加入你的應用程式註冊項目,然後再次授權連線。 |
| 在精靈中, 重定向網址 欄位保持空缺 | 連接器仍在建立中。 如果步驟顯示錯誤,請選擇 重試。 |
| 姓名和描述不會從代理人卡自動帶入 | 請確認代理人卡片的網址正確,且 Copilot Studio 能存取該卡片。 如果卡片無法取得,請手動輸入名稱和說明。 |
| 你建立的連線在你編輯了嚮導後就不再正常了 | 更改認證設定後,從之前設定中建立的連接器會被丟棄。 註冊新的重定向網址,並重新選擇連線。 |