Microsoft Dökümhanesi

Microsoft Agent Framework, Microsoft Foundry proje uç noktalarından doğrudan model çıkarımı ve Foundry Agent Service içindeki hizmet tarafından yönetilen aracılara destek verir.

Başlangıç Yapmak

Projenize gerekli NuGet paketlerini ekleyin.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

İki ajan türü

Microsoft Foundry tümleştirmesi iki ayrı kullanım desenini kullanıma sunar:

Türü	Üretilen tür	Açıklama	Şu durumlarda kullanın:
Yanıt Aracısı	ChatClientAgent	Uygulamanız, çalışma zamanında AIProjectClient.AsAIAgent(...) aracılığıyla bir model, yönergeler ve araçlar sağlar. Sunucu tarafı aracı kaynağı oluşturulmaz.	Ajan tanımına sahipsiniz ve basit, esnek bir kurulum istiyorsunuz. Bu, çoğu örnekte kullanılan desendir.
Döküm Aracı ( sürüm olarak)	FoundryAgent	Sunucu tarafından yönetilen — aracı tanımları, Foundry portalı ya da AIProjectClient.AgentAdministrationClient ile programatik olarak oluşturulur ve sürümlendirilir. ProjectsAgentVersion, ProjectsAgentRecord veya AgentReference öğesini AIProjectClient.AsAIAgent(...) öğesine geçirin.	Hizmet API'leri aracılığıyla Foundry portalında yönetilen katı, sürümlenmiş aracı tanımlarına ihtiyacınız vardır

Yanıt Aracısı (doğrudan çıkarım)

AsAIAgent Doğrudan bir model ve yönergelerle kullanınAIProjectClient. Bu, çoğu senaryo için önerilen başlangıç noktasıdır.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Kod odaklı bu yaklaşım, sunucu tarafından yönetilen bir aracı kaynağı oluşturmaz.

Foundry Agent (sürümlü)

AI Projeleri SDK'sındaki yerel AIProjectClient.AgentAdministrationClient API'lerini kullanarak sürümlü aracı kaynaklarını alın ve bunları AsAIAgent ile sarmalayın. Aracılar doğrudan Dökümhane portalında veya AIProjectClient.AgentAdministrationClient program aracılığıyla oluşturulabilir ve yapılandırılabilir.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Önemli

Kurucu Aracıları araç ve yönergeleri, tasarlandıkları asıl yapıya sıkı sıkıya bağlıdır; çalışma zamanında araçları veya yönergeleri değiştirmeye çalışmak desteklenmez.

Aracıyı kullanma

Hem ChatClientAgent (Yanıtlar) hem de FoundryAgent (sürümlenmiş) standart AIAgent örneklerdir ve oturum, araçlar, ara yazılım ve akış dahil tüm standart işlemleri destekler.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

Aracıları çalıştırma ve aracılarla etkileşim kurma hakkında daha fazla bilgi için bkz. Aracı kullanmaya başlama öğreticileri.

Tools

'den AIProjectClient.AsAIAgent(...) oluşturulan döküm aracıları (Yanıtlar yolu) standart Agent Framework araç yüzeyini destekler. Tam liste ve desteklenen özellik matrisi için Araçlara genel bakış bölümüne bakın. Sürümlü bir aracı tanımından (FoundryAgent) yüklenen Foundry aracıları için, aracın araçları istemciye değil, Foundry aracı tanımına aittir.

Araç	Notlar
İşlev Araçları	Supported.
Araç Onayı	Supported. Çerçevenin işlev çağırma özellikli sohbet istemcisi tarafından sağlanır.
Kod Yorumlayıcısı	Supported.
Dosya Arama	Supported.
Barındırılan MCP Araçları	Supported.
Yerel MCP Araçları	Supported.
Foundry Araç Kutuları	Supported.

Araç Takımları

Note

Foundry Toolbox .NET belgeleri yakında kullanıma sunulacaktır.

Python dökümhane

Python'da, Foundry'ye özgü tüm istemciler artık agent_framework.foundry altında yaşıyor.

• agent-framework-foundry bulut Foundry bağlayıcılarını sağlar: FoundryChatClient, FoundryAgent, FoundryEmbeddingClientve FoundryMemoryProvider.
• agent-framework-foundry-local FoundryLocalClient yerel model yürütmeyi sağlar.

Önemli

Bu sayfa, Microsoft Foundry proje uç noktaları, model uç noktaları ve Foundry Aracısı Hizmeti için geçerli Python istemcilerini kapsar. Tek başına Azure OpenAI kaynak uç noktanız varsa (https://<your-resource>.openai.azure.com), OpenAI sağlayıcı sayfasında Python kılavuzunu kullanın. Desteklenen modelleri yerel olarak çalıştırmak istiyorsanız , Foundry Yerel sağlayıcı sayfasına bakın.

Python'de dökümhane sohbeti ve aracı desenleri

Scenario	Python şekli	Şu durumlarda kullanın:
Foundry Responses uç noktasıyla düz çıkarım	Agent(client=FoundryChatClient(...))	Uygulamanız aracı tanımına, araçlarına ve konuşma döngüsüne sahip ve bir modelin bir Foundry projesinde dağıtılmasını istiyorsunuz.
Döküm Aracı Servisi'nde servis tarafından yönetilen aracılar	FoundryAgent(...)	Foundry portalında veya hizmet API'leri aracılığıyla oluşturulan ve yapılandırılan bir PromptAgent veya HostedAgent'a bağlanmak istiyorsunuz.

Installation

pip install agent-framework-foundry
pip install azure-identity

Aynı agent-framework-foundry paket, Foundry modelleri-uç nokta eklemeleri için FoundryEmbeddingClient de içerir.

Konfigürasyon

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

İstem Aracıları için FOUNDRY_AGENT_VERSION kullanın. Barındırma hizmeti verilen aracılar bunu göz ardı edebilir.

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient ve FoundryAgent proje uç noktasını kullanın. FoundryEmbeddingClient ayrı modeller uç noktasını kullanır.

Doğru Python istemcisini seçin

Scenario	Tercih edilen istemci	Notlar
Azure OpenAI kaynağı	OpenAIChatCompletionClient / OpenAIChatClient	OpenAI sağlayıcı sayfasını kullanın.
Microsoft Foundry proje analizi	Agent(client=FoundryChatClient(...))	Foundry Yanıtları uç noktasını kullanır.
Microsoft Foundry hizmet tarafından yönetilen aracı	FoundryAgent	İstem Aracıları ve HostedAgents için önerilir.
Microsoft Foundry modelleri-uç nokta eklemeleri	FoundryEmbeddingClient	FOUNDRY_MODELS_ENDPOINT'yı, ayrıca FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL kullanır.
Dökümhane Yerel çalışma zamanı	Agent(client=FoundryLocalClient(...))	Bkz. Yerel Dökümhane.

aracı FoundryChatClient ile oluştur

FoundryChatClient Bir Foundry projesinde dağıtılan modele bağlanır ve Yanıtlar uç noktasını kullanır. Uygulamanızın yönergelere, araçlara ve oturum işlemeye sahip olması gerektiğinde bunu bir standartla Agent eşleştirin.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient, doğrudan çıkarım için Foundry öncelikli Python yoludur ve araçları, yapılandırılmış çıkışları ve akışı destekler.

Tools

FoundryChatClient, barındırılan her bir Foundry aracı için statik fabrika yöntemleri sunar. Fabrikalar, Agent üzerinde tools= öğesine veya doğrudan client.get_response(..., tools=[...]) öğesine ilettiğiniz SDK araç nesnelerini döndürür. FoundryAgent için, aracının kullandığı araçlar doğrudan Foundry aracı tanımının kendisinde tanımlanır; bkz. FoundryAgent ile nelerin çalışıp nelerin çalışmadığı.

Fabrikalar sınıf yöntemleridir, bu nedenle bir araç oluşturmak için bir örneğe ihtiyacınız yoktur:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

Araç desteği

Aşağıdaki tablo, Python FoundryChatClient’un bugün sunduğu tüm araçları listeler. FoundryAgent aynı araçlarla çalışır, ancak kodda geçirilmeleri yerine Foundry aracı tanımında yapılandırılmaları gerekir.

Araç	Fabrika açık FoundryChatClient	Statü	Ayrıntı
İşlev Araçları	yok — çağrılabilen veya @ai_function Python geçirin	Georgia	Python işleminizde yerel olarak çağrılır.
Araç Onayı	n/a — mevcut araçların üzerine kuruludur	Georgia	Barındırılan MCP ve işlev araçlarıyla çalışır.
Kod Yorumlayıcısı	get_code_interpreter_tool	Georgia	Foundry'de kodun yalıtılmış ortamda yürütülmesi.
Dosya Arama	get_file_search_tool	Georgia	Yüklenen dosyaları Foundry vektör depoları aracılığıyla arayın.
Web Araması	get_web_search_tool	Georgia	Microsoft tarafından yönetilen Bing destekli web topraklama. Yalnızca Azure OpenAI modelleri.
Görüntü Üretimi	get_image_generation_tool	Georgia	Foundry üzerinde sunulan görüntü oluşturma.
Barındırılan MCP	get_mcp_tool	Georgia	Foundry tarafından çağrılan uzak MCP sunucusu.
Yerel MCP	yok — kullan MCPStreamableHTTPTool / MCPStdioTool	Georgia	Uygulamanızın işlemi içinde çalışır; her türlü istemciyle çalışır.
Foundry Araç Kutuları	MCPStreamableHTTPTool araç kutusu MCP uç noktasına	Georgia	MCP üzerinden FoundryChatClient'dan alınır; sunucu tarafında FoundryAgent üzerinde eklenir.
Bing Temellendirme	get_bing_grounding_tool	Experimental	Bing Arama kaynağını kullanarak kendi temellendirmenizi sağlayın.
Bing Özel Arama	get_bing_custom_search_tool	Önizle	Bing dayandırması, özenle seçilmiş bir alan adları listesiyle sınırlandırılmıştır.
Azure AI Arama Hizmeti	get_azure_ai_search_tool	Experimental	Foundry bağlantısı üzerinden bir Azure Yapay Zeka Arama dizininde arama yapın.
SharePoint	get_sharepoint_tool	Önizle	SharePoint içerikte temel yanıtlar.
Microsoft Fabric	get_fabric_tool	Önizle	Fabric veri aracılarını sorgulama.
Bellek Arama	get_memory_search_tool	Önizle	Foundry tarafından yönetilen bir bellek deposunda arama.
Bilgisayar Kullanımı	get_computer_use_tool	Önizle	Ajanın bir masaüstü ya da tarayıcı ortamını kontrol etmesine izin verin.
Tarayıcı Otomasyonu	get_browser_automation_tool	Önizle	Azure Playwright bağlantısı aracılığıyla bir tarayıcı sürün.
Temsilciden Temsilciye (A2A)	get_a2a_tool	Önizle	Başka bir A2A ajanını araç olarak çağırın.

Note

Deneysel fabrika yöntemleri GA Foundry SDK türlerini sarar, ancak sarmalayıcıların kendileri GA öncesinde değişebilir. Önizleme fabrikaları, temelindeki özellik önizleme aşamasında olan ve değişebilen veya kaldırılabilen Foundry SDK türlerini sarmalar. Her ikisi de bir işlemde ilk kez kullanıldıklarında bir ExperimentalWarning oluşturur.

Web araması varyantları

Foundry, Bing destekli üç dayanaklandırma seçeneği sunar. Senaryonuzla eşleşeni seçin:

• get_web_search_tool (GA) — sıfır kurulum varsayılanı; Microsoft tarafından yönetilen Bing kaynağı. Yalnızca Azure OpenAI modelleri. user_location ve search_context_size ile sınırlıdır.
• get_bing_grounding_tool (deneysel) — Bing Search Azure kaynağınızla kendi grounding verinizi kullanın. count, freshness, market, set_lang ve OpenAI Foundry dışındaki modelleri destekler.
• get_bing_custom_search_tool (önizleme) — temellendirmeyi özenle seçilmiş bir etki alanları kümesiyle sınırlamak için kendi Bing Özel Arama örneğinizi kullanmanıza olanak tanır.

Üçü de arama verilerini Azure uyumluluk sınırının dışına gönderir. Tam karşılaştırma için web dayanaklandırmasına genel bakış sayfasını inceleyin.

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

Görüntü oluşturma

get_image_generation_tool Foundry'nin barındırılan görüntü oluşturma aracını yapılandırıyor. Model yanıtta görüntü içeriği oluşturur; yönetecek ek dosya yoktur.

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Bing ile temellendirme

get_bing_grounding_tool, Grounding with Bing Search Foundry aracını kapsar. Bing Search ile Grounding kaynağını kendiniz oluşturup bunu bir Foundry projesi bağlantısı olarak eklersiniz, ardından bağlantı kimliğini iletirsiniz.

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

Bing özel arama

get_bing_custom_search_tool, dayanaklandırmayı Bing Özel Arama kaynağında tanımlı izin listesiyle sınırlar.

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Azure Yapay Zeka Arama

get_azure_ai_search_tool, aracının bir Foundry proje bağlantısı aracılığıyla Azure Yapay Zeka Arama dizinini sorgulamasına olanak tanır.

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

SharePoint

get_sharepoint_tool, Bir Foundry SharePoint bağlantısı aracılığıyla ulaşılabilen SharePoint içerikteki yanıtların kaynağını oluşturur.

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool aracıyı bir Foundry bağlantısı aracılığıyla bir Fabric veri aracısına bağlar; böylece aracı, Fabric verilerinizle ilgili soruları yanıtlayabilir.

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

Bellek araması

get_memory_search_tool aracının, isteğe bağlı olarak kapsamı bir kullanıcı veya kiracı olarak belirlenmiş, Foundry tarafından yönetilen bir bellek deposunda arama yapmasını sağlar.

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

Bilgisayar kullanımı

get_computer_use_tool , Bilgisayar Kullanımı önizleme aracını yapılandırırken model, işaretçi ve klavye eylemleri vererek masaüstü veya tarayıcı ortamını yönlendirebilir.

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

Tarayıcı otomasyonu

get_browser_automation_tool aracıyı bir Foundry bağlantısı aracılığıyla Azure Playwright Testing kaynağına bağlar. Ajan, Playwright aracılığıyla gerçek bir tarayıcıyı kontrol edebilir.

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

Ajandan Ajana (A2A)

get_a2a_tool, bir Foundry aracısının onu çağırabilmesi için uzak bir A2A aracısını araç olarak sunar. Depolanan bir A2A bağlantısı için ya bir base_url (ve isteğe bağlı olarak bir agent_card_path) ya da bir project_connection_id sağlayın.

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

Keşif, oturumlar ve akışa yönelik genel A2A yönergeleri için Ajanlar Arası sağlayıcı sayfasına bakın.

FoundryEmbeddingClient ile gömme oluşturun

Dökümhane modelleri uç noktasından metin veya görüntü ekleme istediğinizde kullanın FoundryEmbeddingClient .

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Bir hizmet tarafından yönetilen aracı ile bağlanma FoundryAgent

Foundry'de bir aracı tanımı olduğunda FoundryAgent kullanın. Bu, İstem Aracıları ve HostedAgents için önerilen Python API'dir.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

HostedAgent için agent_version'i atlayıp bunun yerine barındırılan aracı adını kullanın.

Ne işe yarar ve nelerle çalışmaz? FoundryAgent

FoundryAgent , Foundry'de zaten var olan bir aracıya (bir İstem Aracısı veya Barındırılan Aracı) bağlanır. Ajanın tanımı — yönergeleri ve araç yapılandırması — Python kodunuzda değil, Foundry’dedir. Bu, bazı Agent düzeyindeki özelliklerin, Agent(client=FoundryChatClient(...)) ya da sohbet istemcisi destekli diğer ajanlarla karşılaştırıldığında farklı davrandığı anlamına gelir.

Tools

Araç türü FoundryAgent(...) öğesine iletildi	Behavior
FunctionTool (yerel Python çağrılabilir)	Desteklenir, ancak yalnızca eşleşen işlev tanımı Foundry aracısının üzerinde zaten varsa. Foundry çalışma zamanı, aracı tanımına dayanarak modele hangi araçları sunacağına karar verir. Model bir işlevi çağırdığında, Foundry istemciye bir araç çağrısı döndürür ve çerçeve, yerel Python çağrılabilirinizi işleminizde (Foundry'de değil) çağırır, ardından sonucu geri gönderir. FunctionTool öğesini istemci tarafında geçirmek yalnızca bu yerel uygulamayı sağlar; işlev Foundry aracısında tanımlanmamışsa model onu hiçbir zaman çağırmaz.
Barındırılan araçlar (web araması, kod yorumlayıcı, dosya arama, MCP, görüntü oluşturma vb.)	Göz ardı edildi. Bunlar, Foundry portalında veya hizmet API'leri aracılığıyla Foundry aracı tanımının kendisinde yapılandırılmalıdır. Bunları istemci tarafına geçirmenin hiçbir etkisi yoktur çünkü Foundry çalışma zamanı yalnızca aracı tanımına eklenmiş araçları tanır.

Kısaca: oluşturma zamanında yeni araçlar ekleyemezsiniz. Modelin çağırabileceği her araç (yerel Python işlevleri dahil) foundry'deki aracı tanımının bir parçası olmalıdır. FunctionTool öğesinin FoundryAgent(...) öğesine geçirilmesi yalnızca Foundry’de tanımlı işlev çağrıldığında Python işleminizde çalışan yerel uygulamayı sağlar; aracıya yeni bir araç kaydetmez.

Bağlam sağlayıcıları

context_providers=[...] kısmen desteklenir. Bağlam sağlayıcısının çalışıp çalışmadığı, sağlayıcının ne yapmaya çalıştığına bağlıdır:

Bağlam sağlayıcısı davranışı	FoundryAgent ile çalışır mı?
İleti olarak ek bağlam ekler (örneğin, alınan bellek, RAG kod parçacıkları, kullanıcı profili bilgileri)	Evet. Eklenen bağlam istekle birlikte iletilir.
Konuşmayı kalıcı olarak depolamak veya gözlemlemek (örneğin, mesaj dönüşlerini harici bir depolama alanına yazmak)	Evet. İstek/yanıt süreci etrafında yerel olarak çalışır.
Araçları dinamik olarak ekler (örneğin, SkillsProvider veya invoking() kaynağından araç döndüren herhangi bir sağlayıcı)	Hayır, araçlar zaten Foundry aracı tanımının bir parçası değilse. Foundry çalışma zamanı, modeli Foundry’de aracıya bağlı araçlarla çalıştırır; yalnızca yerel olarak bulunan araçlar modele sunulmaz ve çağrılmaz.

Dinamik araç seçimine, beceri yüklemesine veya çalışma zamanında eklenen araçlara dayalı başka bir davranışa ihtiyacınız varsa, bunun yerine kullanın Agent(client=FoundryChatClient(...)) ; bu yol model döngüsünün yerel olarak sahibidir ve tüm araç türlerini ve araç ekleme bağlam sağlayıcılarını destekler.

Çalıştırma seçenekleri (default_options ve agent.run(...) seçenekleri)

FoundryAgent(default_options=...) veya agent.run(..., **options) öğesine ilettiğiniz seçeneklerin (örneğin temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata vb.) hepsi dikkate alınmaz. Foundry'deki ajan tanımı asıl başvuru kaynağı olduğundan, birçok seçenek sessizce yok sayılır.

İstem Aracıları için çerçeve, isteği DökümHane Yanıtları API'sine göndermeden önce aşağıdakileri açıkça kaldırır veya geçersiz kılar:

Seçenek	Davranış FoundryAgent ile
model	Göz ardı edildi. Model, Foundry aracısı tanımından alınmıştır.
tools, tool_choice, parallel_tool_calls	İstek gövdesinden çıkarılmış. Araçlar, Foundry aracı tanımında bildirilmelidir (önceki bölüme bakın). FunctionTool çağrılabilen öğeler hala işlev çağrısı için yerel olarak bağlanır, ancak araç listesinin kendisi hizmete gönderilmez.
instructions ve sistem/geliştirici iletileri	Göz ardı edildi. Foundry aracısının kendi talimatları bağlayıcıdır. sistem/geliştirici iletileri, istek gönderilmeden önce ileti listesinden çıkarılır.
conversation_id	Kullanılır ve birine atıfta bulunduğunda Foundry aracı oturumuyla eşlenir.
extra_body	İletildi, çerçeve kümesine ait agent_reference veri yüküyle birleştirildi.
Örnekleme parametreleri (temperature, top_p, max_tokens, , seed, frequency_penalty, presence_penalty, , stop, ...), metadata, user, store, response_formatvb.	Yanıtlar API'sine iletildi. Foundry'nin bunları gerçekten uygulayıp uygulamadığı aracıya ve model yapılandırmasına bağlıdır; aracı tanımı bunları geçersiz kılabilir veya kısıtlayabilir; bu nedenle, bir İstem Aracısı için etkili olmasına güvenmeyin.

Barındırılan Aracılar için de aynı istemci tarafı ayıklama işlemi uygulanır, ancak bundan sonrası ilgili barındırılan aracının neyi uyguladığına bağlıdır. Barındırılan bir aracı, iletilen herhangi bir seçeneği kabul edebilir, yok sayabilir veya yeniden yorumlayabilir. Çalışma zamanı seçeneklerini yalnızca yol gösterici olarak kabul edin ve gerçek davranışı, çağırdığınız barındırılan aracı üzerinde doğrulayın.

Tip

Çalıştırma başına oluşturma parametreleri, yönergeler veya araç seçimi üzerinde ayrıntılı denetime ihtiyacınız varsa, bunları Foundry ajan tanımında yapılandırın ya da Agent(client=FoundryChatClient(...))'i uçtan uca destekleyen ChatOptions öğesine geçin.

Tip

İyi bir pratik kural: Bir özellik, her çalıştırmada ajanın yönergelerini veya araçlarını değiştirmeyi gerektiriyorsa, Agent(client=FoundryChatClient(...)) üzerinde yer alır. Aracının tanımı Foundry'de sabitse ve yalnızca yerel fonksiyon çağrısı ile mesaj düzeyinde bağlama ihtiyacınız varsa, FoundryAgent doğru seçimdir.

Dağıtılmış (host edilmiş) bir Foundry aracısına bağlanma

Hizmet tarafı oturumları (/agents/{name}/sessions) çalıştıran HostedAgents için, önizleme Responses arabirimini kullanmayı seçmek üzere FoundryAgent ile allow_preview=True kullanın:

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
)

Altyapı hizmet oturumunu kendiniz yönetmeniz gerektiğinde (örneğin, bir oturumu belirli bir kiracıya veya kullanıcıya atamak için), önizleme AIProjectClient API'sini kullanarak oturumu oluşturun ve agent.get_session(...) ile sarmalayın.

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

Tip

En son sürümü otomatik olarak çözümleme de dahil olmak üzere eksiksiz bir örnek için örneğe bakın.using_deployed_agent.py

Uyarı

Eski Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider ve Azure yapay zeka ekleme uyumluluk yüzeyleri geçerli agent_framework.azure ad alanından kaldırıldı. Geçerli Python kodu için, uygulamanız yönergelere ve araçlara sahip olduğunda FoundryChatClient kullanın, aracın tanımı Foundry'de olduğunda FoundryAgent kullanın ve Foundry model uç noktası gömme işlemleri için FoundryEmbeddingClient kullanın.

Aracıyı kullanma

Hem FoundryChatClient hem de FoundryAgent, araç çağrıları, oturumlar ve akış yanıtları dahil olmak üzere standart Python Agent deneyimiyle tümleştirilir. Yerel çalışma zamanları için Foundry Local sağlayıcı sayfasını kullanın.

Araç Takımları

Önemli

Araç kutusu API'leri deneyseldir. Yüzey, gelecek sürümlerde değişebilir.

Dökümhane araç kutusu, Bir Microsoft Foundry projesinde yapılandırılmış barındırılan araç yapılandırmalarının (kod yorumlayıcı, dosya arama, görüntü oluşturma, MCP, web araması) adlandırılmış, sürümlenmiş sunucu tarafı paketidir. Araç kutuları, araç yapılandırmasını Foundry portalında bir kez yönetmenize ve aracılar arasında yeniden kullanmanıza olanak tanır.

Agent Framework yalnızca tüketimi kapsar; araç kutusu sürümlerini oluşturma ve güncelleştirme işlemi, Foundry portalı veya ham azure-ai-projects SDK (azure-ai-projects>=2.1.0) aracılığıyla gerçekleştirilir.

FoundryAgent ve FoundryChatClient karşılaştırması

Temsilci türü	Araç kutusu davranışı
FoundryAgent (barındırılan)	Araç kutusu eki sunucu tarafında gerçekleşir. İstemci tarafı kablolama gerekmez.
FoundryChatClient (doğrudan çıkarım)	get_toolbox() ile araç kutusunu alın ve tools= olarak iletin.

İki tüketim deseni

Pattern	Açıklama
Yerel (barındırılan araçlar)	Araç yapılandırmaları Foundry çalışma zamanında yürütülür. Araç kutusunu doğrudan olarak tools=geçirin.
MCP	MCPStreamableHTTPTool araç kutusunun MCP uç noktasında kullanın. Yalnızca FoundryChatClientile değil, herhangi bir sohbet istemcisiyle de çalışır.

Araç kutusunu getirme

Araç kutusunu almak için kullanın FoundryChatClient.get_toolbox() :

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async with AzureCliCredential() as credential:
    client = FoundryChatClient(credential=credential)
    toolbox = await client.get_toolbox("research_toolbox")

    async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
        result = await agent.run("Summarize recent findings.")
        print(result.text)

Atlandığında version , get_toolbox iki istekte varsayılan sürümü çözümler. Ek gidiş dönüşten kaçınmak için belirli bir sürümü sabitleyin:

toolbox = await client.get_toolbox("research_toolbox", version="v3")

Note

Varsayılan sürümler sunucu tarafında değişiklik gösterebildiğinden, her get_toolbox() çağrısı ağa ulaşır; çerçeve tarafında önbellek yoktur. Önbelleğe alma, çağıran tarafından yönetilir.

Örtük düzleştirme

yazmanız toolbox.toolsgerekmez. Çerçeve, normalize_tools algılar ve ToolboxVersionObject otomatik olarak düzleştirir. Tüm bu çalışmalar:

# Single toolbox
agent = Agent(client=client, tools=toolbox)

# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])

# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])

# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])

Filtreleme araçları ile select_toolbox_tools

Eğer araç kutunuz birden fazla aracı bir araya getiriyorsa ancak bir ajan yalnızca bir alt kümeye ihtiyaç duyuyorsa, getirildikten sonra bu kümeyi daraltmak için select_toolbox_tools kullanın. Bu, modele gereksiz araç tanımları göndermeyi önler ve bu da belirteç kullanımını azaltır ve modelin kullanıma sunmamayı düşündüğünüz araçları çağırmasını önler:

from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name

# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])

# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])

# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))

Aracı işlevleri get_toolbox_tool_name(tool) ve get_toolbox_tool_type(tool) sırasıyla bir araç girişinin seçim adını ve ham türünü döndürür. FoundryHostedToolType, TypeAliasLiteral["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | strinclude_types üzerinde IDE rehberliğinde tamamlama için bir / (exclude_types) değeridir.

MCP tüketim yolu

Araç kutusunun MCP uç noktası URL'sini işaret ederek MCPStreamableHTTPTool bir araç kutusunu MCP sunucusu olarak da kullanabilirsiniz.

MCP uç noktası URL'si, Döküm Portalı'nda gösterilir veya şu biçimdedir:

https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1

İstemci, Foundry araç kutusu uç noktasına doğrudan bağlandığından, header_provideraracılığıyla bir Entra ID taşıyıcı belirteciyle kimlik doğrulaması yapmanız gerekir.

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Sınırlamalar

• Araç kutusunun içindeki MCP araçları sunucu tarafı kimlik doğrulaması kullanır. Foundry projesinde yapılandırılan bir OAuth bağlantısı aracılığıyla üst akış MCP sunucusuna yönelik kimlik doğrulaması gerçekleştirilir. İstemci, üst akış sunucusu için asla taşıyıcı belirteçleri tutmaz.
• MCP sunucusu olarak bir araç kutusu kullanmak için istemci tarafı kimlik doğrulaması gerekir. Bir araç kutusunun MCP uç noktasını MCPStreamableHTTPTool işaret ettiğinizde, get_bearer_token_provider(credential, "https://ai.azure.com/.default") aracılığıyla (örneğin header_provider aracılığıyla) bir Entra ID taşıyıcı belirteci sağlamanız gerekir.
• Onay akışı yönetimi, çalışma zamanında bir sorundur. Bir araç kutusu MCP aracı sırasında CONSENT_REQUIREDtetikleniyorsaagent.run(), araç kutusu getirme sırasında değil çalışma zamanında işlenir.

Samples

Sample	Açıklama
foundry_chat_client_with_toolbox.py	Temel araç kutusu getirme, sürüm sabitleme, araç kutularını birleştirme ve filtreleme
foundry_chat_client_with_toolbox_mcp.py	ILE MCP tüketim yolu MCPStreamableHTTPTool
foundry_toolbox_context_provider.py	Dönüş başına bağlam sağlayıcısı aracılığıyla dinamik araç seçimi

Sonraki Adımlar

Dökümhane Yerel