Azure Functions 中 Python 的代理程式繫結

Python 函式應用程式的代理綁定可以讓你在現有函式上加入代理行為。 當函式執行時，擴充套件會根據 Markdown 指令建構一個 SDK 專屬的代理程式或會話，並將其以具型別的參數注入你的處理器。 你的程式碼決定何時以及如何調用代理，並搭配你的確定性應用邏輯。

若要將代理綁定與其他 AI 相關功能（如 Azure Functions 託管技能及模型情境協議（MCP）工具比較，請參閱 Azure Functions 的 AI 整合選項。

什麼是代理程式繫結？

代理綁定是一種輸入綁定，提供已設定的代理或工作階段作為 Python 函式的具型別參數。 這個擴充功能結合了 Markdown 指令與應用程式的提供者設定和工具，讓你的處理器不需要為每次呼叫建構並串接代理程式。

綁定不會取代你的函式或觸發程序。 你的程式碼仍然會驗證輸入、決定何時呼叫代理、處理錯誤並產生輸出。 指令位於 .agent.md 檔案中，而用戶端、模型與工具設定則保留在應用程式程式碼與設定中。 提供者套件將此共享綁定模型連結到不同的代理 SDK。

何時使用代理程式繫結

當 Azure 函式需要代理推理來處理工作流程的一部分，但你的應用程式必須保留對觸發器、驗證、分支、錯誤處理和回應的控制權時，可以使用代理綁定。 常見情況包括：

• 評估一個 HTTP 請求。 用確定性程式碼驗證訂單，請代理評估履行風險，並用結果構建 HTTP 回應。
• 擴充或分類事件。 先接收佇列訊息、事件網格事件或其他觸發有效載荷，並使用代理程式對資料進行分類、摘要或豐富，然後函式才寫入結果。
• 為持久的工作流程加入理性。 透過 replay-safe context.call_agent() API 呼叫 Durable Functions 編排器的代理，然後在後續的編排步驟中使用結果。

功能仍然是協調者：它準備任務、呼叫代理人，並決定如何處理結果。 綁定可減少設定程式碼，將 Markdown 指令與執行時設定分離，並可搭配熟悉的 Azure Functions 觸發器及本地除錯工具。

如果你偏好主要透過 Markdown 和宣告式設定來定義行為和觸發程序，而不是使用 Python 處理常式，可以考慮 Azure Functions 託管技能。

可用套件

提供者專屬的擴充套件將共享綁定模型與代理程式 SDK 連接起來。 以下套件目前為預覽版，且需要 Python 3.13 或更新版本：

每個套件定義其支援的類型、認證、模型設定及呼叫 API。 請參考其快速入門或範例，了解 SDK 特定的設定與部署需求。

劑劑結合的運作原理

AgentFunctionApp 延伸自 azure.functions.FunctionApp，因此具有與 FunctionApp 相同的功能。 markdown_agent 裝飾器會將代理程式輸入加入至函式中。

對於每個代理程式繫結，擴充功能都會執行下列操作：

1. 從函式應用程式根目錄或其 .agent.md 目錄解析所要求的 agents/ 檔案。
2. 以原始 UTF-8 指令載入完整檔案。
3. 結合說明與提供者設定、明確工具，以及發現的代理技能與 MCP 伺服器。
4. 建立一個全新的 SDK 專用代理程式或工作階段，並開啟由此次叫用所擁有的資源。
5. 將代理或會話注入處理者參數。
6. 在執行結束時關閉由叫用所擁有的資源。

提供者負責管理其用戶端生命週期。 由呼叫擁有的資源會在成功、失敗或取消後關閉。

定義一種藥物結合

要為 Python v2 函式應用程式新增綁定：

1. 安裝一個提供者套件並匯入其 AgentFunctionApp 模組。
2. 依照該套件的需求配置客戶端、模型、認證和工具。
3. 在應用程式根目錄或 .agent.md 目錄中新增 agents/ 說明檔案。 該檔案為原始 UTF-8 文字;系統不會解析 YAML 前置內容或執行時設定。
4. 加入 markdown_agent 至已觸發的函式。 設定 arg_name 以符合已輸入的處理常式參數，並設定 agent_name 以識別指令檔案。
5. 透過其 SDK API 呼叫注入的物件，並在函式程式碼中處理結果。

例如，agent_name="order-fulfillment" 可以識別任一支援的目錄中的 order-fulfillment.agent.md，但不能同時識別兩者。 名稱必須在應用程式根目錄內明確解析，且不得包含路徑分隔符或遍歷元件。 若要注入多個代理，請堆疊具有不同 arg_name 值與相符處理常式參數的裝飾器。

完整程式碼範例請參閱 套件快速啟動與範例。

共用代理技能與 MCP 伺服器

擴充功能會自動從應用程式根節點發現共享代理能力：

使用共享代理能力時請考慮以下事項：

• 函式應用程式中的每個代理程式繫結，都會收到所有已探索到的代理程式技能和 MCP 伺服器。
• 以檔案為基礎的代理技能，是代理可載入的能力。 它們不是 Azure Functions 託管的技能，後者使用獨立的執行模型。
• 目前的代理程式擴充功能預覽版不支援為應用程式或個別繫結選取部分功能。
• 代理技能與 MCP 工具可執行特權操作。 只放置應用程式中每個代理都能使用的能力，當代理需要不同能力邊界時，則使用不同的功能應用程式。

MCP 設定可參考 URL、標頭、認證範圍及用戶端 ID 的環境變數。 系統會在擴充功能連線至伺服器之前，為每次叫用解析參照。 不要直接把秘密存進來源控制 mcp.json 檔案裡。

不支援本地程序及標準輸入/輸出（stdio）MCP 伺服器。 MCP 支援功能是選用相依項，即使未安裝，正常的套件匯入仍可安全進行。

搭配 Durable Functions 使用代理程式繫結

當你安裝供應商可選的 Durable Functions 整合時，同步產生器協調器會產生 context.call_agent(agent_name, input_)。 該擴充功能在隱藏活動中執行代理工作，將模型呼叫、工具及其他非確定性操作保留在編排器重播之外。

輸入與輸出必須可序列化 JSON 格式。 通話會使用應用程式設定的供應商及共享功能。 請參閱套件快速入門與範例，了解安裝與協調流程範例。

專案檔案

啟用代理的應用程式是標準的 Python v2 函式應用程式，具有代理副檔相依關係及一個或多個指令檔：

關於標準Python專案結構，請參閱Azure Functions Python開發者指南。

驗證與診斷

此擴充功能會在綁定編譯之前或期間驗證 Agent 定義，讓設定問題以可操作的錯誤形式失敗。 驗證涵蓋：

• 遺失或不明確的 .agent.md 檔案。
• 無效的處理器簽章，包括缺少或不匹配的注入參數。
• 不支援的提供者選項或功能。
• 技能目錄無效且 MCP 配置錯誤。
• 不支援的 MCP 傳輸與缺少的環境值。
• 無效的 Durable 承載資料或無法序列化為 JSON 的值。

在可用時，擴充功能會保留 Azure 函式名稱、調用 ID 及 Durable 實例 ID 於提供者邊界，以支援關聯與診斷。

相關文章

• Azure Functions 的 AI 整合選項
• 在 Python 函式中使用 Microsoft Agent Framework 代理
• 在 Python 函式中使用 GitHub Copilot SDK 代理
• 在 Durable 協調流程中使用 Microsoft Agent Framework 代理程式繫結
• Azure Functions agents runtimes （AFAR） repository 中的混合 hosted-skill 範例 — 一個用於從普通函數代碼調用託管技能的獨立模型。