使用 Foundry 工具箱搭配 LangChain

使用這個 langchain-azure-ai 套件將 Foundry 工具箱中的工具和技能載入你的 LangChain 和 LangGraph 代理程式。 Foundry 工具箱是一種管理型多 MCP 伺服器，將多個已設定的工具整合於單一模型情境協定（MCP）端點之下。

你會學會如何載入工具、辨識需要核准的工具、載入工具箱技能作為資源，並為深度客服人員準備技能。

先決條件

Azure 訂用帳戶。免費創建一個。
Foundry 專案。
在你的專案中部署了一個聊天模型（例如 gpt-4.1）。
一個在你的 Foundry 專案中設定的工具箱。請注意它的名字。
Python 3.10 或更新版本。
Azure CLI已登入（az login），所以 DefaultAzureCredential 可以進行認證。

安裝所需的套件：

pip install -U langchain-azure-ai langchain-mcp-adapters httpx azure-identity

工具箱整合需要 langchain-mcp-adapters 和 httpx。若要為深度代理載入技能，還需安裝 deepagents。

設定您的環境

工具箱需要專案端點和工具箱名稱。將端點設為環境變數，並將工具箱名稱傳給建構子。

設定你的專案終點：

import os

os.environ["FOUNDRY_PROJECT_ENDPOINT"] = (
    "https://<resource>.services.ai.azure.com/api/projects/<project>"
)

整合會讀取 FOUNDRY_PROJECT_ENDPOINT 或 AZURE_AI_PROJECT_ENDPOINT 作為專案端點。沒有任何環境變數提供工具箱名稱，因此必須傳遞 toolbox_name 給建構子。

匯入共用類別並初始化本文中使用的模型：

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage

model = init_chat_model("azure_ai:gpt-4.1")

工具箱會使用 DefaultAzureCredential 進行驗證，並沿用你的 az login 工作階段。你不需要自己建立一個憑證。

連線到工具箱

使用命名空間 AzureAIProjectToolbox 中的 langchain_azure_ai.tools 來連線到工具箱。當你設定 FOUNDRY_PROJECT_ENDPOINT 環境變數時，整合會偵測到專案連線。 Microsoft Entra ID 是預設的認證方式。

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    toolbox_name="my-toolbox",
)

當你在環境中設定端點時，可以省略 project_endpoint。您隨時需要提供 toolbox_name：

toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")

Note

AzureAIProjectToolbox 目前為預覽版，且在您建立一個時，會引發 ExperimentalWarning。其 API 可能會變動。

Reference：AzureAIProjectToolbox

從工具箱裝載工具

呼叫aget_tools()以使用工具箱開啟一個工作階段，並載入它公開為 LangChain BaseTool 執行個體的每個工具。每次呼叫都是無狀態的：它會開啟一個新的 MCP 會話，載入工具，然後返回它們。

async def main():
    toolbox = AzureAIProjectToolbox(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        toolbox_name="my-toolbox",
    )

    tools = await toolbox.aget_tools()

    agent = create_agent(model=model, tools=tools)

    result = await agent.ainvoke(
        {"messages": [HumanMessage("What can you do?")]}
    )
    print(result["messages"][-1].content)

這段程式碼片段的作用：連線到工具箱、載入其中的工具，並將這些工具綁定至代理。當你呼叫代理時，模型可以呼叫工具箱中提供的任何工具來回應請求。

AzureAIProjectToolbox 同時支援非同步上下文管理器協定。此行為相同，因為每個aget_tools()呼叫會管理自己的工作階段：

async with AzureAIProjectToolbox(toolbox_name="my-toolbox") as toolbox:
    tools = await toolbox.aget_tools()

參考資料：create_agent

辨識需要核准的工具

有些工具箱工具設定為執行前需經過核准。呼叫 get_tools_requiring_approval() 以擷取這些工具的名稱，這樣你就能在執行前加入人工介入步驟。

tools_needing_approval = await toolbox.get_tools_requiring_approval()

print("Tools that require approval before execution:")
for name in tools_needing_approval:
    print(f"- {name}")

這段程式碼片段的作用： 檢查工具箱的中繼資料，並回傳其組態將 require_approval 設為 always 的工具名稱。使用此清單，要求敏感操作先經過核准流程。

此功能獨立於 OAuth 同意處理。有關人工參與核准的詳細諮詢，請參閱使用 Foundry Agent Service 搭配 LangGraph。

Microsoft Foundry 中的工具箱可以處理代理者工作流程。你可以在將工具加入工具箱時設定授權要求。

示範如何使用代理者工作流程設定 MCP 伺服器的螢幕截圖。

當工具箱工具連接到尚未授權的服務時，Foundry 閘道器需要 OAuth 同意。 get_tools() / aget_tools() 不會擲回例外，而是會回傳一個備用工具，提供同意網址，讓您的代理程式可將其呈現給使用者。

當你呼叫代理並模型呼叫備援工具時，回應會包含類似以下訊息：

OAuth consent is required before this toolbox can be used. Open the following
URL in a browser to authorize access, then restart the agent:

  https://consent.azure-apim.net/...

在瀏覽器中開啟網址授權存取， 然後重新啟動代理程式。你同意後，工具箱會正常載入工具。

從工具箱載入技能

工具箱會將技能公開為 MCP 資源，其 URI 格式為 skill://{name}。用 get_resources() 來載入它們作為 LangChain Blob 物件。每個 Blob URI 在其 source 屬性中攜帶資源名稱，原始 URI 則在 metadata["uri"]下。

skill_blobs = toolbox.get_resources(scheme="skills")

for blob in skill_blobs:
    print(f"Skill: {blob.source}")
    print(blob.as_string())

Skill: jokes-teller/SKILL.md
{'content': '---\nname: jokes-teller\ndescription: A skill to tell jokes\n---\n\nUse...'}

此程式碼片段的作用：將工具箱中的所有skill://資源載入為Blob。 scheme="skills" 篩選器會將結果限制為技能資源。匹配不區分大小寫，接受單數或複數形式（"skill" 或 "skills"）。

要載入特定資源，請明確傳遞它們的 URI。當你提供 uris時， scheme 過濾器會被忽略：

skill_blobs = toolbox.get_resources(uris="skill://my-skill/SKILL.md")

使用 aget_resources() 作為對應的非同步版本：

skill_blobs = await toolbox.aget_resources(scheme="skills")

為深度 Agent 載入技能

如果您使用deepagents套件，請呼叫get_skills()，將工具箱技能載入為供create_deep_agent使用的現成可用檔案對應。此方法建置在get_resources()之上，並移除將每個Blob轉換為深度 Agent 所預期之檔案配置的樣板程式碼。

安裝套件：

pip install deepagents

以下範例為 a StateBackend （預設值）提供種子。將backend引數保留為未設定，並在files上將傳回的對應作為invoke酬載傳遞：

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
skill_files = toolbox.get_skills()

agent = create_deep_agent(
    model="azure_ai:gpt-4.1",
    backend=StateBackend(),
    skills=["/skills/"],
)

agent.invoke({"messages": [HumanMessage("Use a skill")], "files": skill_files})

這段程式碼的作用：將工具箱技能載入到虛擬 SKILL.md 路徑的對應表中，並透過 files 承載資料將其植入代理程式狀態中。代理人接著可以使用基礎路徑下的 /skills/ 技能。

若要使用獨立儲存體（例如 FilesystemBackend）來設置後端，請將其作為 backend 引數傳遞。技能會寫入後端，且相同的映射也會回傳：

from deepagents.backends import FilesystemBackend

backend = FilesystemBackend(root_dir="./my-project")
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
await toolbox.aget_skills(backend=backend)

agent = create_deep_agent(
    model="azure_ai:gpt-4.1",
    backend=backend,
    skills=["/skills/"],
)

預設情況下，技能檔案會放在基礎路徑下方 /skills/ 。傳入不同的 base_path 以變更位置。該值必須以斜線開頭和結尾，並將相同的值傳給 skills 的 create_deep_agent參數。

後續步驟

將 Foundry Agent Service 與 LangGraph 搭配使用

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-14