Gunakan Foundry Toolbox dengan LangChain

Gunakan paket langchain-azure-ai untuk memuat alat dan keterampilan dari Foundry Toolbox ke dalam agen LangChain dan LangGraph Anda. Foundry Toolbox adalah server multi-MCP terkelola yang mengagregasikan beberapa alat yang telah dikonfigurasi melalui satu endpoint Model Context Protocol (MCP).

Anda mempelajari cara memuat alat, mengidentifikasi alat yang memerlukan persetujuan, memuat keterampilan kotak alat sebagai sumber daya, dan menyiapkan keterampilan untuk agen mendalam.

Prasyarat

Instal paket yang diperlukan:

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

Integrasi kotak alat memerlukan langchain-mcp-adapters dan httpx. Untuk memuat skill untuk agen deep, instal juga deepagents.

Mengonfigurasi lingkungan Anda

Kotak alat memerlukan titik akhir proyek dan nama kotak alat. Atur titik akhir sebagai variabel lingkungan, dan teruskan nama kotak alat ke konstruktor.

Atur titik akhir proyek Anda:

import os

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

Integrasi membaca baik FOUNDRY_PROJECT_ENDPOINT atau AZURE_AI_PROJECT_ENDPOINT untuk titik akhir proyek. Tidak ada variabel lingkungan yang menyediakan nama kotak alat, jadi selalu berikan toolbox_name ke konstruktor.

Impor kelas umum dan inisialisasi model yang digunakan di seluruh artikel ini:

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")

Toolbox mengautentikasi melalui DefaultAzureCredential, yang menggunakan sesi az login Anda. Anda tidak perlu membuat kredensial sendiri.

Hubungkan ke kotak peralatan

Gunakan AzureAIProjectToolbox dari ruang nama langchain_azure_ai.tools untuk terhubung ke kumpulan alat. Integrasi mendeteksi koneksi proyek saat Anda mengatur FOUNDRY_PROJECT_ENDPOINT variabel lingkungan. Microsoft Entra ID adalah metode autentikasi default.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Saat Anda mengatur titik akhir di lingkungan, Anda dapat menghilangkan project_endpoint. Anda selalu perlu menyediakan toolbox_name:

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

Nota

AzureAIProjectToolbox masih dalam pratinjau dan memunculkan ExperimentalWarning saat Anda membuatnya. API-nya dapat berubah.

Referensi:AzureAIProjectToolbox

Memuat alat dari kotak alat

Panggil aget_tools() untuk membuka sesi dengan toolbox dan memuat setiap alat yang disediakannya sebagai instans LangChain BaseTool. Setiap panggilan tanpa status: ia membuka sesi MCP baru, memuat alat, dan mengembalikannya.

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)

Apa yang dilakukan cuplikan ini: Terhubung ke toolbox, memuat alat-alatnya, dan mengaitkannya ke agen. Saat Anda memanggil agen, model dapat memanggil alat apa pun yang disediakan kotak alat untuk menjawab permintaan.

AzureAIProjectToolbox juga mendukung protokol manajer konteks asinkron. Perilaku ini identik karena setiap aget_tools() panggilan mengelola sesinya sendiri:

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

Referensi:create_agent

Mengidentifikasi alat yang memerlukan persetujuan

Beberapa alat dalam kotak alat dikonfigurasi agar memerlukan persetujuan sebelum dijalankan. Panggil get_tools_requiring_approval() untuk mendapatkan nama-nama alat tersebut sehingga Anda dapat menambahkan langkah dengan campur tangan manusia sebelum eksekusi.

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}")

Apa yang dilakukan cuplikan ini: Memeriksa metadata kotak alat dan mengembalikan nama alat yang konfigurasinya diatur require_approval ke always. Gunakan daftar ini untuk gerbang operasi sensitif di balik alur kerja persetujuan.

Kemampuan ini tidak bergantung pada penanganan persetujuan OAuth. Untuk informasi selengkapnya tentang persetujuan dengan campur tangan manusia, lihat Menggunakan Foundry Agent Service dengan LangGraph.

Kotak alat di Microsoft Foundry dapat menangani alur kerja atas nama. Anda dapat mengonfigurasi persyaratan otorisasi saat menambahkan alat ke kotak alat Anda.

Cuplikan layar tentang cara mengonfigurasi server MCP dengan alur kerja on-behalf-of.

Saat alat dalam toolbox terhubung ke layanan yang belum diberi otorisasi, gateway Foundry memerlukan persetujuan OAuth. Alih-alih meningkatkan pengecualian, get_tools()/aget_tools() mengembalikan alat fallback yang menampilkan URL persetujuan sehingga agen Anda dapat menyajikannya kepada pengguna.

Saat Anda memanggil agen dan model memanggil alat fallback, respons berisi pesan yang mirip dengan yang berikut ini:

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/...

Buka URL di browser untuk mengotorisasi akses, lalu mulai ulang agen. Setelah Anda memberikan izin, toolbox memuat alat-alatnya seperti biasa.

Memuat keahlian dari kotak alat

Kotak peralatan menyediakan keterampilan sebagai sumber daya MCP dengan URI dalam bentuk skill://{name}. Gunakan get_resources() untuk memuatnya sebagai objek LangChain Blob . Masing-masing Blob membawa nama sumber daya dalam propertinya source dan URI mentahnya di bawah 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...'}

Apa yang dilakukan potongan kode ini: Memuat setiap sumber daya skill:// dari toolbox sebagai Blob. Filter scheme="skills" membatasi hasil ke sumber daya keterampilan. Pencocokan tidak membedakan huruf besar/kecil dan menerima bentuk tunggal atau jamak ("skill" atau "skills").

Untuk memuat sumber daya tertentu, berikan URI-nya secara eksplisit. Saat Anda menyediakan uris, scheme filter diabaikan:

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

Gunakan aget_resources() untuk setara asinkron:

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

Memuat keterampilan untuk agen mendalam

Jika Anda menggunakan paket deepagents, panggil get_skills() untuk memuat skill toolbox dalam bentuk pemetaan file siap pakai untuk create_deep_agent. Metode ini dibangun berdasarkan get_resources() dan menghilangkan pekerjaan kode berulang untuk mengonversi setiap Blob ke tata letak file yang diharapkan deep agent.

Instal paket tersebut:

pip install deepagents

Contoh berikut melakukan seed pada StateBackend (default). Biarkan argumen backend kosong dan teruskan pemetaan yang dikembalikan sebagai muatan files pada 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})

Apa yang dilakukan cuplikan ini: Memuat skill toolbox ke dalam pemetaan jalur virtual SKILL.md dan menginisialisasikannya ke dalam status agen melalui payload files. Agen kemudian dapat menggunakan skill di bawah jalur dasar /skills/.

Untuk menginisialisasi backend dengan penyimpanan mandiri, seperti FilesystemBackend, berikan itu sebagai argumen backend. Keahlian disimpan di backend, dan pemetaan yang sama juga dikembalikan:

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/"],
)

Secara bawaan, berkas skill ditempatkan di bawah jalur dasar /skills/. Gunakan base_path yang berbeda untuk mengganti lokasi. Nilai harus diawali dan diakhiri dengan garis miring, dan Anda meneruskan nilai yang sama ke argumen skills dari create_deep_agent.

Langkah selanjutnya

Menggunakan Foundry Agent Service dengan LangGraph

Konten terkait

  • Terakhir diperbarui pada