LangChain ile Döküm Araç Kutusu'nu kullanma

LangChain ve LangGraph ajanlarınıza bir Foundry Toolbox'tan araçlar ve beceriler yüklemek için langchain-azure-ai paketini kullanın. Foundry Toolbox, tek bir Model Bağlam Protokolü (MCP) uç noktasının arkasında yapılandırılmış birden çok aracı toplayan, yönetilen bir çoklu MCP sunucusudur.

Araçları yüklemeyi, onay gerektiren araçları tanımlamayı, araç kutusu becerilerini kaynak olarak yüklemeyi ve derin aracılar için beceriler hazırlamayı öğreneceksiniz.

Prerequisites

• Azure aboneliği. Ücretsiz bir tane oluşturun.
• Dökümhane projesi.
• Projenizde dağıtılan bir sohbet modeli (örneğin, gpt-4.1) .
• Foundry projenizde yapılandırılmış bir araç kutusu. Adını not edin.
• Python 3.10 veya üzeri.
• Azure CLI oturum açtı (az login) böylece DefaultAzureCredential kimlik doğrulaması yapabilir.

Gerekli paketleri yükleyin:

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

Araç kutusu tümleştirmesi için langchain-mcp-adapters ve httpx gereklidir. Derin ajanlar için becerileri yüklemek üzere deepagents bileşenini de yükleyin.

Ortamınızı yapılandırma

Araç kutusunun bir proje uç noktası ve araç kutusu adı gerekir. Uç noktayı ortam değişkeni olarak ayarlayın ve araç kutusu adını oluşturucuya geçirin.

Proje uç noktanızı ayarlayın:

import os

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

Entegrasyon, proje uç noktası için AZURE_AI_PROJECT_ENDPOINT veya FOUNDRY_PROJECT_ENDPOINT değerini okur. Araç kutusu adını hiçbir ortam değişkeni sağlamaz, bu nedenle her zaman oluşturucuya geçirin toolbox_name .

Ortak sınıfları içeri aktarın ve bu makale boyunca kullanılan modeli başlatın:

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

Araç kutusu, DefaultAzureCredential ile kimlik doğrulaması yapar ve az login oturumunuzu kullanır. Kimlik bilgilerini kendiniz oluşturmanız gerekmez.

Araç kutusuna bağlanma

Araç kutusuna bağlanmak için ad alanından AzureAIProjectToolbox kullanınlangchain_azure_ai.tools. Ortam değişkenini ayarladığınızda FOUNDRY_PROJECT_ENDPOINT tümleştirme proje bağlantısını algılar. Microsoft Entra ID varsayılan kimlik doğrulama yöntemidir.

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Uç noktayı ortamda ayarladığınızda, project_endpoint belirtmeyebilirsiniz. Her zaman toolbox_namesunmanız gerekir:

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

Note

AzureAIProjectToolbox önizleme aşamasındadır ve bir tane oluşturduğunuzda bir ExperimentalWarning oluşturur. API'sinde değişiklik yapılır.

Başvuru:AzureAIProjectToolbox

Araç kutusundan araçları yükleme

Araç kutusuyla bir oturum açmak ve sunduğu tüm araçları LangChain aget_tools() örnekleri olarak yüklemek için BaseTool çağrısını yapın. Her çağrı durumsuzdur: yeni bir MCP oturumu açar, araçları yükler ve bunları döndürür.

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)

Bu kod parçacığının yaptığı iş: Araç kutusuna bağlanır, araç kutusundaki araçları yükler ve bunları bir ajana bağlar. Aracıyı çağırdığınızda, model araç kutusunun isteği yanıtlamak için sağladığı herhangi bir aracı çağırabilir.

AzureAIProjectToolbox ayrıca zaman uyumsuz bağlam yöneticisi protokolünü de destekler. Her aget_tools() çağrı kendi oturumunu yönettiğinden davranış aynıdır:

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

Referans:create_agent

Onay gerektiren araçları tanımlama

Bazı araç kutusu araçları, çalışmadan önce onay gerektirecek şekilde yapılandırılır. Çalıştırmadan önce insan denetimli bir adım ekleyebilmeniz için bu araçların adlarını almak üzere get_tools_requiring_approval() çağrısını yapın.

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

Bu kod parçacığının yaptığı iş: Araç kutusu meta verilerini inceler ve yapılandırmasında require_approval değeri always olarak ayarlanmış araçların adlarını döndürür. Hassas işlemleri bir onay iş akışıyla denetlemek için bu listeyi kullanın.

Bu özellik, OAuth onayı işlemeden bağımsızdır. İnsan denetimli onaylar hakkında daha fazla bilgi için bkz: LangGraph ile Foundry Agent Service’i kullanma.

OAuth onayını işleme

Microsoft Foundry'deki araç kutusu, iş akışlarını adına işleyebilir. Araçları araç kutunuza eklerken yetkilendirme gereksinimlerini yapılandırabilirsiniz.

Bir araç kutusu aracı henüz yetkilendirilmemiş bir hizmete bağlandığında, Foundry ağ geçidi OAuth onayı gerektirir. Özel durum oluşturmak yerine, get_tools()/aget_tools() aracınızın kullanıcıya sunabilmesi için onay URL'sini gösteren bir geri dönüş aracı döndürür.

Bir aracı çağırdığınızda ve model geri dönüş aracını çağırdığında, yanıt aşağıdakine benzer bir ileti içerir:

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

Erişimi yetkilendirmek için TARAYıCıDA URL'yi açın, ardından aracıyı yeniden başlatın. Onay verdikten sonra araç kutusu araçlarını normal şekilde yükler.

Araç kutusundan becerileri yükleyin

Bir araç kutusu, becerileri skill://{name} biçimindeki URI’lerle MCP kaynakları olarak sunar. Bunları LangChain get_resources() nesneleri olarak yüklemek için Blob kullanın. Her Blob, kaynak adını source özelliğinde, ham URI'sini ise metadata["uri"] altında taşır.

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...'}

Bu kod parçacığının yaptığı: Araç kutusundaki her skill:// kaynağını bir Blob olarak yükler. scheme="skills" filtresi, sonuçları beceri kaynaklarıyla sınırlandırır. Eşleşme büyük/küçük harfe duyarlı değildir ve tekil ya da çoğul biçimi ("skill" veya "skills") kabul eder.

Belirli kaynakları yüklemek için URI'lerini açıkça geçirin. uris sağladığınızda, scheme filtresi yok sayılır:

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

Eşzamansız eşdeğeri için aget_resources() kullanın:

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

Derin ajanlar için becerileri yükle

deepagents paketini kullanıyorsanız, araç kutusu becerilerini get_skills() için kullanıma hazır bir dosya eşlemesi olarak yüklemek üzere create_deep_agent çağrısını yapın. Bu yöntem, get_resources() üzerine kuruludur ve her bir Blob’i deep agent’ların beklediği dosya düzenine dönüştürmek için gereken tekrarlayan kodu ortadan kaldırır.

Paketi yükleyin:

pip install deepagents

Aşağıdaki örnek, StateBackend öğesini (varsayılan olanı) başlatır. backend bağımsız değişkenini ayarlamadan bırakın ve döndürülen eşlemeyi files üzerinde invoke yükü olarak geçirin:

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

Bu kod parçacığının yaptığı iş: Araç kutusu yeteneklerini sanal SKILL.md yolları eşlemesine yükler ve bunları files yükü üzerinden aracı durumuna başlangıç verisi olarak ekler. Aracı daha sonra temel yol altındaki /skills/ becerileri kullanabilir.

gibi FilesystemBackendtek başına depolamaya sahip bir arka uç görmek için bunu bağımsız değişken olarak backend geçirin. Beceriler arka uca yazılır ve aynı eşleme de geri döndürülür:

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

Varsayılan olarak, beceri dosyaları temel yolun altına /skills/ yerleştirilir. Konumu değiştirmek için farklı base_path bir iletin. Değer / ile başlamalı ve bitmelidir; aynı değeri de skills öğesinin create_deep_agent bağımsız değişkenine aktarırsınız.

Sonraki adım

LangGraph ile Foundry Agent Servisini Kullanma

İlgili içerik

• LangGraph ile Foundry Agent Servisini Kullanma
• Microsoft Foundry SDK'ları ve Uç Noktaları ile çalışmaya başlayın
• PyPI üzerinde langchain-azure-ai paketi