Azure Functions 中 Python 的代理程式繫結

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

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

代理綁定是一種由擴充套件擁有的輸入綁定，提供一個完整建構的Agent物件給 Python 函式。 此擴充功能會從 .agent.md 檔案中以原始文字形式讀取代理程式指示。 您的應用程式程式碼保留客戶端與提供者專屬的工具設定，而函式應用專案則能發現基於檔案的代理技能與遠端 MCP 伺服器。

代理綁定架構透過提供者專屬的擴充套件支援來自不同 SDK 的代理物件。 Microsoft Agent Framework 是目前預覽版中唯一支援的代理 SDK。 要使用它，請安裝套件。azurefunctions-agents-extensions-agent-framework

何時使用代理程式繫結

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

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

當函式的決定性程式碼應繼續擔任協調者時，代理繫結會是很合適的選擇。 代理執行有界推理任務，並將控制權交還給處理者或編排。

為什麼要使用藥劑結合？

許多生產工作流程結合了必須確定性的步驟與受益於模型推理的步驟。 代理人綁定為這些混合工作流程帶來以下好處：

• 在現有函數中加入能動行為。 使用來自 HTTP-、timer-、queue-、Event Grid-、 服務匯流排-及其他觸發函式的 Agent 推理。
• 在程式碼中安全地控制代理的叫用。 決定何時呼叫代理人，檢視其回應，並決定函式輸出。 此延伸模組會在成功、失敗或取消後，關閉該次叫用所擁有的資源。
• 減少代理設定程式碼。 接收已設定好的 Agent 作為具型別的處理常式參數，而不是在每次叫用時都重新建構及設定它。
• 指令與執行時設定分開。 將自然語言指令儲存在.agent.md檔案中，並以 Python 明確配置客戶端及提供者專用工具。
• 使用共用代理能力。 擴充功能會從應用程式根目錄偵測基於檔案的代理程式技能和基於 HTTP 的 MCP 伺服器，並使其可供各個代理程式繫結使用。
• 從持久協調流程呼叫 Agent。 此擴充功能會在隱藏的活動中執行 Agent 工作，讓協調流程重新執行保持確定性。
• 用熟悉的工具在本地除錯。 像其他 Python 函式應用程式一樣，在本地執行和除錯應用程式。 你可以設定斷點，並逐步執行確定性函式邏輯和呼叫代理的程式碼。

劑劑結合的運作原理

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

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

1. 從函式應用程式根目錄或其 .agent.md 目錄解析所要求的 agents/ 檔案。
2. 以原始 UTF-8 指令載入完整檔案。
3. 結合指示與已設定好的用戶端工廠、明確指定的提供者工具，以及已發現的代理程式技能與 MCP 伺服器。
4. 建立新的 Agent，並開啟該叫用所擁有的資源。
5. 將 Agent 注入到處理常式參數中。
6. 在執行結束時關閉由叫用所擁有的資源。

此擴充功能可將提供者探索結果和已編譯的繫結定義快取。 它不會在函式調用間快取或重用即時調用資源。

定義一種藥物結合

以下範例使用目前支援的 Microsoft Agent Framework 提供者，將 Agent 新增至 HTTP 觸發函式。 函式以程式碼構造任務，呼叫代理，並回傳代理回應：

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

該 arg_name 值必須與注入的處理器參數相符。 若要將多個代理注入同一函式，需堆疊 markdown_agent 裝飾器，並為每個代理綁定使用唯一 arg_name 與處理者參數。 該 agent_name 值用來識別指令檔案。 在此範例中，order-fulfillment 必須精確解析為以下位置其中之一：

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

如果兩個檔案都存在，定義就會模糊，應用程式啟動會失敗。 代理名稱不能包含絕對路徑、路徑分隔符或遍歷元件。 不允許解析後位於應用程式根目錄之外的檔案。

設定代理客戶端與工具

在建構 AgentFunctionApp 時設定零引數的 client_factory。 工廠會回傳一個由提供者套件支援的全新用戶端。 你也可以在應用程式層級透過 tools 參數傳遞 Microsoft Agent Framework 工具物件或 Python 可呼叫物件。 綁定可以在需要不同行為時覆蓋應用程式層級的用戶端工廠與工具。

例如，下列由 HTTP 觸發的函式使用代理程式繫結，使 lookup_inventory 僅供 order_agent 作為工具使用：

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

在配置客服客戶端和工具時，請考慮以下幾點：

• 基礎代理的擴展是提供者中立的。 提供者套件整合特定的代理 SDK，並定義支援的客戶端與代理類型。
• 目前支援的 Microsoft Agent Framework 提供者套件不會為您的應用程式選擇或設定模型提供者。 你的客戶端工廠會決定支援哪個 Microsoft Agent Framework 的聊天客戶端，以及代理使用的模型。
• 擴充功能會將整個 .agent.md 檔案以代理指令的形式傳遞給已設定的提供者。 它不會解析模型設定、工具、YAML 前置資料或其他執行時設定。

共用代理技能與 MCP 伺服器

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

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

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

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

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

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

代理綁定透過可選的 Durable Functions 整合，支援混合且長期執行的工作流程。 同步產生器協調器會呼叫 context.call_agent()，並產生所得的任務：

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() 排程隱藏活動，解析代理定義並執行所有模型、檔案系統、憑證、工具及網路操作。 編排器只會建立一個確定性、可 JSON 序列化的 schema-v1 請求。 因此，編排重播不會重複非確定性代理操作。

持久性代理程式呼叫會使用在 AgentFunctionApp 中設定的提供者和共用功能。 輸入與輸出必須可序列化 JSON 格式。

Durable Functions 支援為選配。 不使用 Durable Functions 的應用程式不需要安裝或匯入 Durable Functions。 若要使用 orchestration_trigger 和 context.call_agent()，請安裝支援的提供者套件及其 Durable 額外相依套件。

專案檔案

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

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

驗證與診斷

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

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

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

相關文章

• Azure Functions 的 AI 整合選項
• 在 Python 函式中使用 Microsoft Agent Framework 代理
• 在 Durable 協調流程中使用 Microsoft Agent Framework 代理程式繫結
• Microsoft 代理框架概述