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.

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.

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

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

Hizmet tarafı oturumları çalıştıran HostedAgents için, FoundryAgent'yi allow_preview=True ile kullanarak Yanıtlar yüzeyinin önizlemesine katılın ve version="v2" geçirin.

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

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

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 `FoundryChatClient`ile 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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-27

Microsoft Dökümhanesi

Başlangıç Yapmak

İki ajan türü

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

Foundry Agent (sürümlü)

Aracıyı kullanma

Araç Takımları

Python dökümhane

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

Installation

Konfigürasyon

FoundryChatClient

FoundryAgent

FoundryEmbeddingClient

Doğru Python istemcisini seçin

aracı FoundryChatClient ile oluştur

FoundryEmbeddingClient ile gömme oluşturun

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

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

Aracıyı kullanma

Araç Takımları

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

İki tüketim deseni

Araç kutusunu getirme

Örtük düzleştirme

Filtreleme araçları ile select_toolbox_tools

MCP tüketim yolu

Sınırlamalar

Samples

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar

`FoundryChatClient`

`FoundryAgent`

`FoundryEmbeddingClient`

aracı `FoundryChatClient` ile oluştur

`FoundryEmbeddingClient` ile gömme oluşturun

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

Filtreleme araçları ile `select_toolbox_tools`