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.

Ö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 Hizmet sohbeti geçmişi depolama desteği Özel sohbet geçmişi depolama desteği
Azure AI Foundry Temsilcisi Azure AI Foundry Agents Hizmeti'ni arka uç olarak kullanan bir aracı. Yes 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ı Yes
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ı. Hayı Yes
Azure OpenAI ChatCompletion Azure OpenAI ChatCompletion hizmetini kullanan bir aracı. Hayı Yes
Azure OpenAI Yanıtları Azure OpenAI Yanıtlar hizmetini kullanan bir aracı. Yes Yes
OpenAI ChatCompletion OpenAI ChatCompletion hizmetini kullanan bir aracı. Hayı Yes
OpenAI Yanıtları OpenAI Yanıtlar hizmetini kullanan bir ajan. Yes Yes
OpenAI Yardımcıları OpenAI Yardımcıları hizmetini kullanan bir temsilci. Yes 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 Aracıları 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 AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions)

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)
    .CreateAIAgent(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 AzureCliCredential())
     .GetChatClient(deploymentName)
     .CreateAIAgent(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 AzureCliCredential());
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 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 ChatAgent oluşturmanız yeterlidir.

from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        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 AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with DefaultAzureCredential() as credential:
    agent = AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful assistant"
    )

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

Desteklenen Aracı Türleri

Temel Çıkarım Hizmeti Description Hizmet Sohbeti Geçmişi depolaması destekleniyor Desteklenen Özel Sohbet Geçmişi depolama alanı
Azure AI Aracısı Azure AI Ajanları Hizmeti'ni arka plan olarak kullanan bir ajan. Yes Hayı
Azure OpenAI Sohbeti Tamamlama Azure OpenAI Sohbet Tamamlama hizmetini kullanan bir aracı. Hayı Yes
Azure OpenAI Yanıtları Azure OpenAI Yanıtlar hizmetini kullanan bir aracı. Yes Yes
OpenAI Sohbet Tamamlama OpenAI Sohbet Tamamlama hizmetini kullanan bir aracı. Hayı Yes
OpenAI Yanıtları OpenAI Yanıtlar hizmetini kullanan bir ajan. Yes Yes
OpenAI Yardımcıları OpenAI Yardımcıları hizmetini kullanan bir temsilci. Yes Hayı
Diğer Tüm ChatClient'lar Aracı oluşturmak için başka bir sohbet istemcisi uygulamasını da kullanabilirsiniz. Varies Varies

İşlev Araçları

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

from typing import Annotated
from pydantic import Field
from azure.identity.aio import DefaultAzureCredential
from agent_framework.azure import AzureAIAgentClient

def get_weather(location: Annotated[str, Field(description="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,
    AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful weather assistant.",
        tools=get_weather
    ) as agent
):
    response = await agent.run("What's the weather in Seattle?")

İşlev araçlarıyla ilgili tam örnekler için bkz:

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_stream("What's the weather like in Portland?"):
    if chunk.text:
        print(chunk.text, end="", flush=True)

Akış örnekleri için bkz:

Kod Yorumlayıcı Araçları

Azure AI aracıları, Python kodunu yürütmek için barındırılan kod yorumlayıcı araçlarını destekler:

from agent_framework import ChatAgent, HostedCodeInterpreterTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant that can execute Python code.",
        tools=HostedCodeInterpreterTool()
    ) as agent
):
    response = await agent.run("Calculate the factorial of 100 using Python")

Kod yorumlayıcı örnekleri için bkz:

Özel aracılar

Ayrıca, yalnızca bir sohbet istemcisi etrafında sarmalayıcı olmayan tamamen özel aracılar oluşturmak da mümkündür. Aracı Çerçevesi, uygulandığında/alt sınıflandığında aracının AgentProtocol davranışı ve BaseAgent özellikleri üzerinde tam denetime olanak tanıyan protokolü ve temel sınıfı sağlar.

from agent_framework import BaseAgent, AgentRunResponse, AgentRunResponseUpdate, AgentThread, ChatMessage
from collections.abc import AsyncIterable

class CustomAgent(BaseAgent):
    async def run(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AgentRunResponse:
        # Custom agent implementation
        pass

    def run_stream(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AsyncIterable[AgentRunResponseUpdate]:
        # Custom streaming implementation
        pass
  • Last updated on