Aracılığıyla paylaş

Microsoft Agent Framework aracı türleri

Microsoft Agent Framework, farklı kullanım örneklerini ve gereksinimlerini karşılamak için çeşitli aracı türleri için destek sağlar.

Tüm aracılar, AIAgenttüm aracı türleri için tutarlı bir arabirim sağlayan ortak bir temel sınıftan türetilir. Bu, çoklu ajan orkestrasyonları gibi ortak, aracı bağımsız ve daha üst düzey işlevler oluşturmaya olanak tanır.

Tüm aracılar, Agenttüm aracı türleri için tutarlı bir arabirim sağlayan ortak bir temel sınıftan türetilir. Bu, çoklu ajan orkestrasyonları gibi ortak, aracı bağımsız ve daha üst düzey işlevler oluşturmaya olanak tanır.

Varsayılan Aracı Çalışma Zamanı Yürütme Modeli

Microsoft Agent Framework'teki tüm aracılar yapılandırılmış çalışma zamanı modeli kullanılarak yürütülür. Bu model, belirleyici bir döngüde kullanıcı etkileşimlerini, model çıkarımlarını ve araç yürütmeyi koordine eder.

AI Aracısı Diyagramı

Önemli

Üçüncü taraf sunucularla veya aracılarla çalışan uygulamalar oluşturmak için Microsoft Agent Framework kullanıyorsanız, bunu riski size aittir. Üçüncü taraf sunucularla veya aracılarla paylaşılan tüm verileri gözden geçirmenizi ve verilerin saklanması ve konumu için üçüncü taraf uygulamaları konusunda bilgili olmanızı öneririz. Verilerinizin kuruluşunuzun Azure uyumluluk ve coğrafi sınırları dışında akıp akmayacağını ve ilgili etkileri yönetmek sizin sorumluluğunuzdadır.

Çıkarım hizmetlerini temel alan basit aracılar

Agent Framework, birçok farklı çıkarım hizmetini temel alan basit aracılar oluşturmayı kolaylaştırır. Bir uygulama sağlayan herhangi bir Microsoft.Extensions.AI.IChatClient çıkarım hizmeti, bu aracıları oluşturmak için kullanılabilir. Microsoft.Agents.AI.ChatClientAgent, herhangi IChatClient bir uygulama için aracı sağlamak için kullanılan aracı sınıfıdır.

Bu ajanlar, kutusundan çıktığı anda kullanılabilen geniş bir işlevsellik yelpazesini destekler.

  1. İşlev çağrısı.
  2. Yerel sohbet geçmişi yönetimi veya hizmet tarafından sağlanan sohbet geçmişi yönetimi ile çok aşamalı konuşmalar.
  3. Özel hizmet tarafından sağlanan araçlar (örneğin, MCP, Kod Yürütme).
  4. Düzenlenmiş çıkış.

Bu aracılardan birini oluşturmak için, seçtiğiniz uygulamayı kullanarak ChatClientAgent bir IChatClient oluşturmanız yeterlidir.

using Microsoft.Agents.AI;

var agent = new ChatClientAgent(chatClient, instructions: "You are a helpful assistant");

Bu aracıları oluşturmayı daha da kolaylaştırmak için, Agent Framework birçok popüler hizmet için yardımcılar sağlar. Daha fazla bilgi için her hizmetin belgelerine bakın.

Temel çıkarım hizmeti Description Desteklenen hizmet sohbeti geçmişinin saklanması InMemory/Özel sohbet geçmişi depolaması destekleniyor
Azure AI Foundry Temsilcisi Azure AI Foundry Agents Hizmeti'ni arka uç olarak kullanan bir aracı. Evet Hayı
Azure AI Foundry Modelleri Chat Tamamlama Azure AI Foundry Hizmeti'nde dağıtılan modellerden herhangi birini arka uç olarak kullanan ve ChatCompletion yöntemi aracılığıyla çalışan bir aracı. Hayı Evet
Azure AI Foundry Model Yanıtları Yanıtlar aracılığıyla Azure AI Foundry Hizmeti'nde dağıtılan modellerden herhangi birini arka uç olarak kullanan bir aracı. Evet Evet
Azure OpenAI ChatCompletion Azure OpenAI ChatCompletion hizmetini kullanan bir aracı. Hayı Evet
Azure OpenAI Yanıtları Azure OpenAI Yanıtlar hizmetini kullanan bir aracı. Evet Evet
OpenAI ChatCompletion OpenAI ChatCompletion hizmetini kullanan bir aracı. Hayı Evet
OpenAI Yanıtları OpenAI Yanıtlar hizmetini kullanan bir ajan. Evet Evet
OpenAI Yardımcıları OpenAI Yardımcıları hizmetini kullanan bir temsilci. Evet Hayı
Diğer IChatClient Aracı oluşturmak için başka Microsoft.Extensions.AI.IChatClient herhangi bir uygulamayı da kullanabilirsiniz. Varies Varies

Karmaşık özel ajanlar

Ayrıca, yalnızca bir IChatClientçevresinde sarmalayıcı olmayan tamamen özel aracılar oluşturmak da mümkündür. Aracı çerçevesi AIAgent temel türünü sağlar. Bu temel tür, alt sınıflandırıldığında aracının davranışı ve özellikleri üzerinde tam denetim sağlayan tüm aracılar için temel soyutlamadır.

Daha fazla bilgi için Özel Aracılar belgelerine bakın.

Uzak aracılar için proxy'ler

Agent Framework, A2A gibi ortak hizmet barındırılan aracı protokolleri için kullanıma AIAgent hazır uygulamalar sağlar. Bu şekilde, uygulamanızdaki uzak aracılara kolayca bağlanabilir ve bunları kullanabilirsiniz.

Daha fazla bilgi için her aracı türünün belgelerine bakın:

Protokol Description
A2A A2A protokolü aracılığıyla uzak bir aracıya proxy görevi gören bir ajan.

Azure ve OpenAI SDK Seçenekleri Referans

Azure AI Foundry, Azure OpenAI veya OpenAI hizmetlerini kullanırken, bu hizmetlere bağlanmak için çeşitli SDK seçenekleriniz vardır. Bazı durumlarda, aynı hizmete bağlanmak için birden çok SDK kullanmak veya farklı hizmetlere bağlanmak için aynı SDK'yı kullanmak mümkündür. Burada, her birine bağlanırken kullanmanız gereken URL ile kullanılabilen farklı seçeneklerin listesi yer alır. <resource> ve <project> etiketlerini gerçek kaynak ve proje adlarınızla değiştirdiğinizden emin olun.

AI Hizmeti SDK Nuget Bağlantı
Azure AI Foundry Modelleri Azure OpenAI SDK 2 Azure.AI.OpenAI https://ai-foundry-<resource.services.ai.azure.com/>
Azure AI Foundry Modelleri OpenAI SDK 3 OpenAI https://ai-foundry-<resource.services.ai.azure.com/openai/v1/>
Azure AI Foundry Modelleri Azure AI Çıkarım SDK 2 Azure.AI.Inference https://ai-foundry-<resource.services.ai.azure.com/models>
Azure AI Foundry Ajanları Azure AI Kalıcı Aracılar SDK'sı Azure.AI.Agents.Persistent https://ai-foundry-<resource.services.ai.azure.com/api/projects/ai-project-project><>
Azure OpenAI1 Azure OpenAI SDK 2 Azure.AI.OpenAI <https:// resource.openai.azure.com/>
Azure OpenAI1 OpenAI SDK'sı OpenAI <https://resource.openai.azure.com/openai/v1/>
OpenAI OpenAI SDK'sı OpenAI URL gerekmez
  1. Azure OpenAI'den Azure AI Foundry'ye yükseltme
  2. OpenAI SDK'sını kullanmanızı öneririz.
  3. Azure AI Foundry modellerine erişmek için OpenAI SDK'sını kullanmanızı öneririz ancak Azure AI Foundry Modelleri yalnızca OpenAI'nin değil birçok farklı satıcının modellerini destekler. Tüm bu modeller OpenAI SDK'sı aracılığıyla desteklenir.

OpenAI SDK'sını kullanma

Yukarıdaki tabloda gösterildiği gibi, OpenAI SDK'sı birden çok hizmete bağlanmak için kullanılabilir. Bağlandığınız hizmete bağlı olarak, OpenAIClient oluştururken özel bir URL ayarlamanız gerekebilir. Hizmete bağlı olarak farklı kimlik doğrulama mekanizmaları da kullanabilirsiniz.

Özel bir URL gerekiyorsa (yukarıdaki tabloya bakın), OpenAIClientOptions aracılığıyla ayarlayabilirsiniz.

var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(serviceUrl) };

İstemciyi oluştururken bir API anahtarı kullanmak mümkündür.

OpenAIClient client = new OpenAIClient(new ApiKeyCredential(apiKey), clientOptions);

Azure Hizmeti kullanırken, API anahtarı yerine Azure kimlik bilgilerini kullanmak da mümkündür.

OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), clientOptions)

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.

OpenAIClient'ı oluşturduktan sonra, kullanmak istediğiniz belirli bir hizmet için bir alt istemci alabilir ve ardından bu hizmetten bir AIAgent alt istemci oluşturabilirsiniz.

AIAgent agent = client
    .GetChatClient(model)
    .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Azure OpenAI SDK'sını kullanma

Bu SDK hem Azure OpenAI hem de Azure AI Foundry Models hizmetlerine bağlanmak için kullanılabilir. Her iki durumda da, AzureOpenAIClient oluştururken doğru hizmet URL'sini sağlamanız gerekir. Kullanılacak doğru URL için yukarıdaki tabloya bakın.

AIAgent agent = new AzureOpenAIClient(
    new Uri(serviceUrl),
    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Azure AI Kalıcı Aracılar SDK'sını kullanma

Bu SDK yalnızca Azure AI Foundry Agents hizmetiyle desteklenir. Kullanılacak doğru URL için yukarıdaki tabloya bakın.

var persistentAgentsClient = new PersistentAgentsClient(serviceUrl, new DefaultAzureCredential());
AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "Joker",
    instructions: "You are good at telling jokes.");

Çıkarım hizmetlerini temel alan basit aracılar

Agent Framework, birçok farklı çıkarım hizmetini temel alan basit aracılar oluşturmayı kolaylaştırır. Bu aracıları oluşturmak için sohbet istemcisi uygulaması sağlayan herhangi bir çıkarım hizmeti kullanılabilir. Bu, istemcinin standart SupportsChatGetResponse sınıfıyla kullanılması için desteklemesi gereken yöntemler için bir standart tanımlayan Agent kullanılarak yapılabilir.

Bu ajanlar, kutusundan çıktığı anda kullanılabilen geniş bir işlevsellik yelpazesini destekler.

  1. Fonksiyon çağırma
  2. Yerel sohbet geçmişi yönetimi veya hizmet tarafından sağlanan sohbet geçmişi yönetimi ile çok aşamalı konuşmalar
  3. Özel hizmet tarafından sağlanan araçlar (örneğin, MCP, Kod Yürütme)
  4. Yapılandırılmış çıkış
  5. Akış yanıtları

Bu aracılardan birini oluşturmak için istediğiniz sohbet istemcisi uygulamasını kullanarak bir Agent oluşturmanız yeterlidir.

import os
from agent_framework import Agent
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity.aio import DefaultAzureCredential

Agent(
    client=AzureOpenAIResponsesClient(credential=DefaultAzureCredential(), project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"), deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME")),
    instructions="You are a helpful assistant"
) as agent
response = await agent.run("Hello!")

Alternatif olarak, sohbet istemcisinde kolaylık yöntemini kullanabilirsiniz:

from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity.aio import DefaultAzureCredential

agent = AzureOpenAIResponsesClient(async_credential=DefaultAzureCredential(), project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"), deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME")).as_agent(
    instructions="You are a helpful assistant"
)

Uyarı

Bu örnek AzureOpenAIResponsesClient'ı kullanmayı gösterir, ancak aynı desen uygulayan tüm sohbet istemcilerinde SupportsChatGetResponsede geçerlidir. Diğer istemcilerle ilgili daha fazla ayrıntı için sağlayıcılara genel bakış konusuna bakın.

Ayrıntılı örnekler için aşağıdaki aracıya özgü belgeler bölümlerine bakın.

Desteklenen Sohbet Sağlayıcıları

Temel Çıkarım Hizmeti Description Hizmet Sohbeti Geçmişi depolaması destekleniyor
Azure AI Foundry Temsilcisi Azure AI Ajanları Hizmeti'ni arka plan olarak kullanan bir ajan. Evet
Azure OpenAI Sohbeti Tamamlama Azure OpenAI Sohbet Tamamlama hizmetini kullanan bir aracı. Hayı
Azure OpenAI Yanıtları Azure OpenAI Yanıtlar hizmetini kullanan bir aracı. Evet
Azure OpenAI Yardımcıları Azure OpenAI Yardımcıları hizmetini kullanan bir aracı. Evet
OpenAI Sohbet Tamamlama OpenAI Sohbet Tamamlama hizmetini kullanan bir aracı. Hayı
OpenAI Yanıtları OpenAI Yanıtlar hizmetini kullanan bir ajan. Evet
OpenAI Yardımcıları OpenAI Yardımcıları hizmetini kullanan bir temsilci. Evet
Anthropic Claude "Anthropic Claude modellerini kullanan bir ajan." Hayı
Amazon Bedrock Amazon Bedrock modellerini Agent Framework Bedrock sohbet yazılımı aracılığıyla kullanan bir acente. Hayı
GitHub Yardımcı Pilotu GitHub Copilot SDK arka planını kullanan bir aracı. Hayı
Ollama (OpenAI uyumlu) OpenAI uyumlu API'ler aracılığıyla yerel olarak barındırılan Ollama modellerini kullanan bir aracı. Hayı
Diğer Tüm ChatClient'lar Başka herhangi bir SupportsChatGetResponse uygulamasını da bir ajan oluşturmak için kullanabilirsiniz. Varies

Oturum tabanlı konuşma durumu desteklendiğinde özel sohbet geçmişi depolaması desteklenir.

Akış Yanıtları

Ajanlar hem normal hem de akış yanıtlarını destekler.

# Regular response (wait for complete result)
response = await agent.run("What's the weather like in Seattle?")
print(response.text)

# Streaming response (get results as they are generated)
async for chunk in agent.run("What's the weather like in Portland?", stream=True):
    if chunk.text:
        print(chunk.text, end="", flush=True)

Akış örnekleri için bkz:

Daha fazla çağrı deseni için Çalıştırma Aracıları bölümüne bakın.

İşlev Araçları

Gelişmiş özellikler için aracılara işlev araçları sağlayabilirsiniz:

import os
from typing import Annotated
from azure.identity.aio import DefaultAzureCredential
from agent_framework.azure import AzureOpenAIResponsesClient

def get_weather(location: Annotated[str, "The location to get the weather for."]) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25°C."

async with DefaultAzureCredential() as credential:
    agent = AzureOpenAIResponsesClient(
        async_credential=credential,
        project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
        deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"),
    ).as_agent(
        instructions="You are a helpful weather assistant.",
        tools=get_weather,
    )
    response = await agent.run("What's the weather in Seattle?")

Araçlar ve araç desenleri için bkz. Araçlara genel bakış.

Özel aracılar

Tamamen özel uygulamalar (örneğin, belirlenimici aracılar veya API destekli aracılar) için bkz. Özel Aracılar. Bu sayfa, SupportsAgentRun uygulamasını veya BaseAgent uzatılmasını, AgentResponseUpdate ile akış güncellemeleri de dahil olmak üzere kapsar.

Diğer ajan türleri

Agent Framework ayrıca aşağıdakiler gibi protokol destekli aracılar içerir:

Ajan Türü Description
A2A Uzak A2A uyumlu aracılara bağlanan ve çağıran bir proxy aracısı.

Sonraki Adımlar

Çalışan Ajanlar

  • Last updated on