AnlamSal Çekirdek-Aracı Çerçevesi Geçiş Kılavuzu

Microsoft Agent Framework'ün avantajları

• Basitleştirilmiş API: Daha az karmaşıklık ve ortak kod.
• Daha İyi Performans: İyileştirilmiş nesne oluşturma ve bellek kullanımı.
• Birleşik Arabirim: Farklı yapay zeka sağlayıcıları arasında tutarlı desenler.
• Gelişmiş Geliştirici Deneyimi: Daha sezgisel ve bulunabilir API'ler.

Aşağıdaki bölümlerde kodunuzu geçirmenize yardımcı olmak için Semantik Çekirdek Aracısı Çerçevesi ile Microsoft Agent Framework arasındaki temel farklar özetlenmektedir.

1. Ad Alanı Güncelleştirmeleri

Semantik Çekirdek

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

Ajan Çerçevesi

Agent Framework ad alanları altındadır Microsoft.Agents.AI. Agent Framework, bileşenler arasındaki iletişim için temel yapay zeka iletisini ve içerik türlerini Microsoft.Extensions.AI kullanır.

using Microsoft.Extensions.AI;
using Microsoft.Agents.AI;

2. Aracı Oluşturma Basitleştirme

Semantik Çekirdek

Anlam Çekirdeği'ndeki her aracı bir Kernel örneğe bağlıdır ve sağlanmadıysa boş Kernel bir aracıya sahiptir.

 Kernel kernel = Kernel
    .AddOpenAIChatClient(modelId, apiKey)
    .Build();

 ChatCompletionAgent agent = new() { Instructions = ParrotInstructions, Kernel = kernel };

Azure AI Foundry, bunu kullanan yerel bir aracı sınıfı oluşturmadan önce bulutta bir aracı kaynağı oluşturulmasını gerektirir.

PersistentAgentsClient azureAgentClient = AzureAIAgent.CreateAgentsClient(azureEndpoint, new AzureCliCredential());

PersistentAgent definition = await azureAgentClient.Administration.CreateAgentAsync(
    deploymentName,
    instructions: ParrotInstructions);

AzureAIAgent agent = new(definition, azureAgentClient);

Ajan Çerçevesi

Agent Framework'te aracı oluşturma, tüm ana sağlayıcılar tarafından sağlanan uzantılarla daha basit hale getirilir.

AIAgent openAIAgent = chatClient.CreateAIAgent(instructions: ParrotInstructions);
AIAgent azureFoundryAgent = await persistentAgentsClient.CreateAIAgentAsync(instructions: ParrotInstructions);
AIAgent openAIAssistantAgent = await assistantClient.CreateAIAgentAsync(instructions: ParrotInstructions);

Ayrıca, barındırılan aracı sağlayıcıları için, mevcut bir barındırılan GetAIAgent aracıdan aracı almak için yöntemini de kullanabilirsiniz.

AIAgent azureFoundryAgent = await persistentAgentsClient.GetAIAgentAsync(agentId);

3. Aracı İş Parçacığı Oluşturma

Semantik Çekirdek

Çağıranın iş parçacığı türünü bilmesi ve el ile oluşturması gerekir.

// Create a thread for the agent conversation.
AgentThread thread = new OpenAIAssistantAgentThread(this.AssistantClient);
AgentThread thread = new AzureAIAgentThread(this.Client);
AgentThread thread = new OpenAIResponseAgentThread(this.Client);

Ajan Çerçevesi

Aracı, iş parçacığını oluşturmakla sorumludur.

// New.
AgentThread thread = agent.GetNewThread();

4. Barındırılan Aracı İş Parçacığı Temizleme

Bu durum yalnızca barındırılan iş parçacıkları sağlayan birkaç yapay zeka sağlayıcısı için geçerlidir.

Semantik Çekirdek

İş parçacıklarının silme yöntemi vardır self .

OpenAI Yardımcıları Sağlayıcısı:

await thread.DeleteAsync();

Ajan Çerçevesi

Uyarı

OpenAI Yanıtları, konuşmaların işlenme şeklini basitleştiren yeni bir konuşma modeli sunar. Bu değişiklik, artık kullanım dışı bırakılan OpenAI Yardımcıları modeline kıyasla barındırılan iş parçacığı yönetimini basitleştirir. Daha fazla bilgi için OpenAI Yardımcıları geçiş kılavuzuna bakın.

Tüm sağlayıcılar barındırılan iş parçacıklarını veya iş parçacığı silmeyi AgentThread desteklemediğinden Agent Framework'ün türünde bir iş parçacığı silme API'si yoktur. Daha fazla sağlayıcı yanıt tabanlı mimarilere geçiş yaptıkçe bu tasarım daha yaygın hale gelecektir.

İş parçacığı silmeye ihtiyacınız varsa ve sağlayıcı buna izin veriyorsa, çağıranın oluşturulan iş parçacıklarını izlemesi ve daha sonra sağlayıcının SDK'sı aracılığıyla gerektiğinde bunları silmesi gerekir .

OpenAI Yardımcıları Sağlayıcısı:

await assistantClient.DeleteThreadAsync(thread.ConversationId);

5. Araç Kaydı

Semantik Çekirdek

Bir işlevi araç olarak kullanıma sunmanız için şunları yapın:

1. İşlevi bir [KernelFunction] öznitelikle süsleyin.
2. Bir Plugin sınıfınız var veya işlevini sarmak için öğesini KernelPluginFactory kullanın.
3. Eklentinizi eklemek için bir Kernel seçeneğine sahip olun.
4. aracını Kernel aracıya geçirin.

KernelFunction function = KernelFunctionFactory.CreateFromMethod(GetWeather);
KernelPlugin plugin = KernelPluginFactory.CreateFromFunctions("KernelPluginName", [function]);
Kernel kernel = ... // Create kernel
kernel.Plugins.Add(plugin);

ChatCompletionAgent agent = new() { Kernel = kernel, ... };

Ajan Çerçevesi

Agent Framework'te, tek bir çağrıda araçları doğrudan aracı oluşturma işlemine kaydedebilirsiniz.

AIAgent agent = chatClient.CreateAIAgent(tools: [AIFunctionFactory.Create(GetWeather)]);

6. Aracı Akışsız Çağırma

yöntemi adlarında InvokeRun, dönüş türleri ve parametrelerinde önemli farklar AgentRunOptionsgörülebilir.

Semantik Çekirdek

Akış Dışı, birden çok aracı iletisi döndürmek için bir akış düzeni IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> kullanır.

await foreach (AgentResponseItem<ChatMessageContent> result in agent.InvokeAsync(userInput, thread, agentOptions))
{
    Console.WriteLine(result.Message);
}

Ajan Çerçevesi

AkışSız, birden çok ileti içerebilen aracı yanıtına sahip tek AgentRunResponse bir değer döndürür. Çalıştırmanın metin sonucu veya AgentRunResponse.Textiçinde AgentRunResponse.ToString() kullanılabilir. Yanıt kapsamında oluşturulan tüm iletiler listede döndürülür AgentRunResponse.Messages . Bu, araç arama iletilerini, işlev sonuçlarını, mantık güncelleştirmelerini ve nihai sonuçları içerebilir.

AgentRunResponse agentResponse = await agent.RunAsync(userInput, thread);

7. Aracı Akış Çağırma

Temel farklar yöntemi adlarında InvokeRunile arasında, dönüş türleri ve parametreleridir AgentRunOptions.

Semantik Çekirdek

await foreach (StreamingChatMessageContent update in agent.InvokeStreamingAsync(userInput, thread))
{
    Console.Write(update);
}

Ajan Çerçevesi

Agent Framework benzer bir akış API'sine sahiptir ve temel fark, güncelleştirme başına aracıyla ilgili daha fazla bilgi içeren nesneler döndürmesidir AgentRunResponseUpdate .

AIAgent'ın temel aldığı herhangi bir hizmet tarafından üretilen tüm güncelleştirmeler döndürülür. Aracının metinsel sonucu, değerlerin birleştirilmesiyle AgentRunResponse.Text kullanılabilir.

await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(userInput, thread))
{
    Console.Write(update); // Update is ToString() friendly
}

8. Araç İşlevi İmzaları

Sorun: Anlam Çekirdeği eklenti yöntemleri özniteliklere ihtiyaç duyar [KernelFunction] .

public class MenuPlugin
{
    [KernelFunction] // Required.
    public static MenuItem[] GetMenu() => ...;
}

Çözüm: Agent Framework, öznitelikleri olmadan yöntemleri doğrudan kullanabilir.

public class MenuTools
{
    [Description("Get menu items")] // Optional description.
    public static MenuItem[] GetMenu() => ...;
}

9. Seçenekler Yapılandırması

Sorun: Anlam Çekirdeği'nde karmaşık seçenekler kurulumu.

OpenAIPromptExecutionSettings settings = new() { MaxTokens = 1000 };
AgentInvokeOptions options = new() { KernelArguments = new(settings) };

Çözüm: Agent Framework'teki basitleştirilmiş seçenekler.

ChatClientAgentRunOptions options = new(new() { MaxOutputTokens = 1000 });

Önemli

Bu örnekte uygulamaya özgü seçeneklerin bir öğesine geçirilmesi gösterilmektedir ChatClientAgent. Tüm AIAgents desteği ChatClientAgentRunOptionsdeğildir. ChatClientAgent temel alınan çıkarım hizmetlerini temel alan aracılar oluşturmak için sağlanır ve bu nedenle gibi MaxOutputTokensçıkarım seçeneklerini destekler.

10. Bağımlılık Ekleme

Semantik Çekirdek

Her Kernel aracı soyutlamasının bir özellik ile başlatılması gerektiğinden, hizmet kapsayıcısında aracı oluşturabilmek için bir Kernel kayıt gereklidir.

Anlam Çekirdeği, Agent aracılar için temel soyutlama sınıfı olarak türünü kullanır.

services.AddKernel().AddProvider(...);
serviceContainer.AddKeyedSingleton<SemanticKernel.Agents.Agent>(
    TutorName,
    (sp, key) =>
        new ChatCompletionAgent()
        {
            // Passing the kernel is required.
            Kernel = sp.GetRequiredService<Kernel>(),
        });

Ajan Çerçevesi

Agent Framework türü temel soyutlama sınıfı olarak sağlar AIAgent .

services.AddKeyedSingleton<AIAgent>(() => client.CreateAIAgent(...));

11. Aracı Türü Birleştirme

Semantik Çekirdek

Semantik Çekirdek, çeşitli hizmetler için belirli aracı sınıfları sağlar, örneğin:

• ChatCompletionAgent sohbet tamamlama tabanlı çıkarım hizmetleriyle kullanmak için.
• OpenAIAssistantAgent OpenAI Yardımcıları hizmetiyle kullanmak için.
• AzureAIAgent Azure AI Foundry Agents hizmetiyle kullanım için.

Ajan Çerçevesi

Agent Framework, belirtilen tüm hizmetleri tek bir aracı türü ChatClientAgentolan aracılığıyla destekler.

ChatClientAgent arabirimini uygulayan bir SDK sağlayan temel alınan herhangi bir hizmeti kullanarak aracılar IChatClient oluşturmak için kullanılabilir.

Önemli farklar

Kodunuzu geçirmenize yardımcı olmak için Anlam Çekirdek Aracısı Çerçevesi ile Microsoft Agent Framework arasındaki temel farkların bir özeti aşağıdadır.

1. Güncelleştirmeleri paketleme ve içeri aktarma

Semantik Çekirdek

Semantik Çekirdek paketleri olarak yüklenir ve olarak semantic-kernelsemantic_kerneliçeri aktarılır. Pakette ayrıca farklı yapay zeka sağlayıcıları ve diğer özellikler için farklı bağımlılıkları yüklemek üzere yükleyebileceğiniz bir dizi extras vardır.

from semantic_kernel import Kernel
from semantic_kernel.agents import ChatCompletionAgent

Ajan Çerçevesi

Agent Framework paketi olarak yüklenir ve olarak agent-frameworkagent_frameworkiçeri aktarılır. Agent Framework farklı şekilde oluşturulmuştur, çekirdek işlevselliğini içeren bir çekirdek paketi agent-framework-core vardır ve ardından bu çekirdek paketi kullanan , agent-framework-azure-ai, agent-framework-mem0vb. birden çok paket agent-framework-copilotstudiovardır. Çalıştırdığınızda pip install agent-framework --pre çekirdek paketi ve tüm paketleri yükler, böylece tüm özellikleri hızlı bir şekilde kullanmaya başlayabilirsiniz. Neye ihtiyacınız olduğunu bildiğiniz için paket sayısını azaltmaya hazır olduğunuzda yalnızca ihtiyacınız olan paketleri yükleyebilirsiniz. Örneğin yalnızca Azure AI Foundry ve Mem0 kullanmayı planlıyorsanız yalnızca şu iki paketi yükleyebilirsiniz: pip install agent-framework-azure-ai agent-framework-mem0 --pre, agent-framework-core bu iki pakete bağımlılıktır, bu nedenle otomatik olarak yüklenir.

Paketler ayrılmış olsa da, içeri aktarmaların tümü veya agent_frameworkmodülleridir. Bu nedenle, örneğin Azure AI Foundry istemcisini içeri aktarmak için aşağıdaki adımları gerçekleştirebilirsiniz:

from agent_framework.azure import AzureAIAgentClient

En yaygın kullanılan türlerin çoğu doğrudan öğesinden agent_frameworkiçeri aktarılır:

from agent_framework import ChatMessage, ChatAgent

2. Aracı Türü Birleştirme

Semantik Çekirdek

Anlam Çekirdeği, ChatCompletionAgent, AzureAIAgent, OpenAIAssistantAgent vb. gibi çeşitli hizmetler için belirli aracı sınıfları sağlar. Bkz. Anlam Çekirdeğindeki aracı türleri.

Ajan Çerçevesi

Aracı Çerçevesi'nde aracıların çoğu Azure AI Foundry, OpenAI ChatCompletion ve OpenAI Yanıtları gibi tüm ChatAgent temel hizmetlerle kullanılabilen kullanılarak oluşturulurChatClient. İki ek aracı daha vardır: CopilotStudioAgent Copilot Studio ile kullanım ve A2AAgent A2A ile kullanım.

Tüm yerleşik aracılar BaseAgent ' ı (from agent_framework import BaseAgent) temel alır. Ayrıca tüm aracılar (AgentProtocol) arabirimiyle from agent_framework import AgentProtocol tutarlıdır.

3. Aracı Oluşturma Basitleştirme

Semantik Çekirdek

Anlam Çekirdeği'ndeki her aracı bir Kernel örneğe bağlıdır ve sağlanmazsa boş Kernel olur.

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(),
    name="Support",
    instructions="Answer in one sentence.",
)

Ajan Çerçevesi

Agent Framework'te aracı oluşturma işlemi doğrudan iki şekilde gerçekleştirilebilir:

from agent_framework.azure import AzureAIAgentClient
from agent_framework import ChatMessage, ChatAgent

agent = ChatAgent(chat_client=AzureAIAgentClient(credential=AzureCliCredential()), instructions="You are a helpful assistant")

Veya sohbet istemcileri tarafından sağlanan kolaylık yöntemleriyle:

from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent(instructions="You are a helpful assistant")

Doğrudan yöntem, aracınız için ayarlayabileceğiniz tüm olası parametreleri kullanıma sunar. Kolaylık yönteminin bir alt kümesi olsa da, doğrudan yöntemi dahili olarak çağırdığı için yine de aynı parametre kümesini geçirebilirsiniz.

4. Aracı İş Parçacığı Oluşturma

Semantik Çekirdek

Çağıranın iş parçacığı türünü bilmesi ve el ile oluşturması gerekir.

from semantic_kernel.agents import ChatHistoryAgentThread

thread = ChatHistoryAgentThread()

Ajan Çerçevesi

Aracıdan sizin için yeni bir iş parçacığı oluşturması istenebilir.

agent = ...
thread = agent.get_new_thread()

Ardından iş parçacığı üç yoldan biriyle oluşturulur:

1. Aracının bir thread_id (veya conversation_id benzeri) kümesi varsa, temel alınan hizmette bu kimlikle bir iş parçacığı oluşturur. bir iş parçacığına service_thread_idsahip olduktan sonra, iletileri bellekte depolamak için artık bunu kullanamazsınız. Bu yalnızca hizmet tarafı iş parçacığı kavramına sahip aracılar için geçerlidir. Azure AI Foundry Aracıları ve OpenAI Yardımcıları gibi.
2. Aracının bir chat_message_store_factory kümesi varsa, bu fabrikayı kullanarak bir ileti deposu oluşturur ve bunu kullanarak bellek içi iş parçacığı oluşturur. Daha sonra parametresi olarak ayarlanmış storebir aracıyla True kullanılamaz.
3. Önceki ayarlardan hiçbiri ayarlı değilse, dikkate alınır uninitialized ve nasıl kullanıldığına bağlı olarak bellek içi iş parçacığına veya hizmet iş parçacığına dönüşür.

Ajan Çerçevesi

Uyarı

OpenAI Yanıtları, konuşmaların işlenme şeklini basitleştiren yeni bir konuşma modeli sunar. Bu, artık kullanım dışı bırakılan OpenAI Yardımcıları modeline kıyasla barındırılan iş parçacığı yönetimini basitleştirir. Daha fazla bilgi için OpenAI Yardımcıları geçiş kılavuzuna bakın.

Tüm sağlayıcılar barındırılan AgentThread iş parçacıklarını veya iş parçacığı silmeyi desteklemediğinden, Agent Framework'ün türünde bir iş parçacığı silme API'si yoktur ve daha fazla sağlayıcı yanıt tabanlı mimarilere kaydıkça bu daha yaygın hale gelir.

İş parçacığı silmeye ihtiyacınız varsa ve sağlayıcı buna izin veriyorsa, çağıranın oluşturulan iş parçacıklarını izlemesi ve daha sonra sağlayıcının sdk'sı aracılığıyla gerektiğinde bunları silmesi gerekir .

OpenAI Yardımcıları Sağlayıcısı:

# OpenAI Assistants threads have self-deletion method in Semantic Kernel
await thread.delete_async()

5. Araç Kaydı

Semantik Çekirdek

Bir işlevi araç olarak kullanıma sunmanız için şunları yapın:

1. İşlevi bir @kernel_function dekoratörle süsleyin.
2. Bir Plugin sınıfınız var veya işlevi sarmak için çekirdek eklentisi fabrikasını kullanın.
3. Eklentinizi eklemek için bir Kernel seçeneğine sahip olun.
4. aracını Kernel aracıya geçirin.

from semantic_kernel.functions import kernel_function

class SpecialsPlugin:
    @kernel_function(name="specials", description="List daily specials")
    def specials(self) -> str:
        return "Clam chowder, Cobb salad, Chai tea"

agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(),
    name="Host",
    instructions="Answer menu questions accurately.",
    plugins=[SpecialsPlugin()],
)

Ajan Çerçevesi

Tek bir çağrıda araçları doğrudan aracı oluşturma işlemine kaydedebilirsiniz. Agent Framework'te birden çok işlevi sarmalayan bir eklenti kavramı yoktur, ancak isterseniz bunu yine de yapabilirsiniz.

Araç oluşturmanın en basit yolu yalnızca bir Python işlevi oluşturmaktır:

def get_weather(location: str) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny."

agent = chat_client.create_agent(tools=get_weather)

Uyarı

tools parametresi hem aracı oluşturma, run hem ve run_stream yöntemleri hem de get_response ve get_streaming_response yöntemleri üzerinde bulunur, hem liste hem de tek bir işlev olarak araçları sağlamanıza olanak tanır.

İşlevin adı daha sonra aracın adı olur ve docstring aracın açıklaması olur ve parametrelere bir açıklama da ekleyebilirsiniz:

from typing import Annotated

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

Son olarak, aracın adını ve açıklamasını daha fazla özelleştirmek için dekoratör kullanabilirsiniz:

from typing import Annotated
from agent_framework import ai_function

@ai_function(name="weather_tool", description="Retrieves weather information for any location")
def get_weather(location: Annotated[str, "The location to get the weather for."])
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny."

Bu, yöntem olarak birden çok araç içeren bir sınıf oluşturduğunuzda da çalışır.

Aracıyı oluştururken artık işlev aracını parametresine geçirerek aracıya tools sağlayabilirsiniz.

class Plugin:

    def __init__(self, initial_state: str):
        self.state: list[str] = [initial_state]

    def get_weather(self, location: Annotated[str, "The location to get the weather for."]) -> str:
        """Get the weather for a given location."""
        self.state.append(f"Requested weather for {location}. ")
        return f"The weather in {location} is sunny."

    def get_weather_details(self, location: Annotated[str, "The location to get the weather details for."]) -> str:
        """Get detailed weather for a given location."""
        self.state.append(f"Requested detailed weather for {location}. ")
        return f"The weather in {location} is sunny with a high of 25°C and a low of 15°C."

plugin = Plugin("Initial state")
agent = chat_client.create_agent(tools=[plugin.get_weather, plugin.get_weather_details])

... # use the agent

print("Plugin state:", plugin.state)

Uyarı

Sınıf içindeki işlevler, araçların adını ve açıklamasını özelleştirmek için ile @ai_function de donatılabilir.

Bu mekanizma, LLM tarafından sağlanamayan bağlantılar, gizli diziler vb. ek girişlere ihtiyaç duyan araçlar için de kullanışlıdır.

Uyumluluk: Aracı Çerçevesi araçları olarak KernelFunction kullanma

Örnekleri olan KernelFunction semantik çekirdek kodunuz varsa (istemlerden veya yöntemlerden), yöntemini kullanarak bunları Agent Framework araçlarına .as_agent_framework_tool dönüştürebilirsiniz.

Önemli

Bu özellik için 1.38 veya üzeri bir sürüm gerekir semantic-kernel .

bir istem şablonundan KernelFunction kullanma

from semantic_kernel import Kernel
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion, OpenAIChatPromptExecutionSettings
from semantic_kernel.prompt_template import KernelPromptTemplate, PromptTemplateConfig
from agent_framework.openai import OpenAIResponsesClient

# Create a kernel with services and plugins
kernel = Kernel()
# will get the api_key and model_id from the environment
kernel.add_service(OpenAIChatCompletion(service_id="default"))

# Create a function from a prompt template that uses plugin functions
function_definition = """
Today is: {{time.date}}
Current time is: {{time.time}}

Answer to the following questions using JSON syntax, including the data used.
Is it morning, afternoon, evening, or night (morning/afternoon/evening/night)?
Is it weekend time (weekend/not weekend)?
"""

prompt_template_config = PromptTemplateConfig(template=function_definition)
prompt_template = KernelPromptTemplate(prompt_template_config=prompt_template_config)

# Create a KernelFunction from the prompt
kernel_function = KernelFunctionFromPrompt(
    description="Determine the kind of day based on the current time and date.",
    plugin_name="TimePlugin",
    prompt_execution_settings=OpenAIChatPromptExecutionSettings(service_id="default", max_tokens=100),
    function_name="kind_of_day",
    prompt_template=prompt_template,
)

# Convert the KernelFunction to an Agent Framework tool
agent_tool = kernel_function.as_agent_framework_tool(kernel=kernel)

# Use the tool with an Agent Framework agent
agent = OpenAIResponsesClient(model_id="gpt-4o").create_agent(tools=agent_tool)
response = await agent.run("What kind of day is it?")
print(response.text)

Bir yöntemden KernelFunction kullanma

from semantic_kernel.functions import kernel_function
from agent_framework.openai import OpenAIResponsesClient

# Create a plugin class with kernel functions
@kernel_function(name="get_weather", description="Get the weather for a location")
def get_weather(self, location: str) -> str:
    return f"The weather in {location} is sunny."

# Get the KernelFunction and convert it to an Agent Framework tool
agent_tool = get_weather.as_agent_framework_tool()

# Use the tool with an Agent Framework agent
agent = OpenAIResponsesClient(model_id="gpt-4o").create_agent(tools=agent_tool)
response = await agent.run("What's the weather in Seattle?")
print(response.text)

create_search_function ile VectorStore kullanma

Aracı Çerçevesi ile Semantik Çekirdeğin VectorStore tümleştirmelerini de kullanabilirsiniz. Vektör create_search_function deposu koleksiyonundaki yöntemi, Aracı Çerçevesi aracına dönüştürülebilen bir döndürür KernelFunction .

from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAITextEmbedding
from semantic_kernel.connectors.azure_ai_search import AzureAISearchCollection
from semantic_kernel.functions import KernelParameterMetadata
from agent_framework.openai import OpenAIResponsesClient

# Define your data model
class HotelSampleClass:
    HotelId: str
    HotelName: str
    Description: str
    # ... other fields

# Create an Azure AI Search collection
collection = AzureAISearchCollection[str, HotelSampleClass](
    record_type=HotelSampleClass,
    embedding_generator=OpenAITextEmbedding()
)

async with collection:
    await collection.ensure_collection_exists()
    # Load your records into the collection
    # await collection.upsert(records)

    # Create a search function from the collection
    search_function = collection.create_search_function(
        description="A hotel search engine, allows searching for hotels in specific cities.",
        search_type="keyword_hybrid",
        filter=lambda x: x.Address.Country == "USA",
        parameters=[
            KernelParameterMetadata(
                name="query",
                description="What to search for.",
                type="str",
                is_required=True,
                type_object=str,
            ),
            KernelParameterMetadata(
                name="city",
                description="The city that you want to search for a hotel in.",
                type="str",
                type_object=str,
            ),
            KernelParameterMetadata(
                name="top",
                description="Number of results to return.",
                type="int",
                default_value=5,
                type_object=int,
            ),
        ],
        string_mapper=lambda x: f"(hotel_id: {x.record.HotelId}) {x.record.HotelName} - {x.record.Description}",
    )

    # Convert the search function to an Agent Framework tool
    search_tool = search_function.as_agent_framework_tool()

    # Use the tool with an Agent Framework agent
    agent = OpenAIResponsesClient(model_id="gpt-4o").create_agent(
        instructions="You are a travel agent that helps people find hotels.",
        tools=search_tool
    )
    response = await agent.run("Find me a hotel in Seattle")
    print(response.text)

Bu desen tüm AnlamSal Çekirdek VectorStore bağlayıcılarıyla (Azure AI Search, Qdrant, Pinecone vb.) çalışır ve Agent Framework aracılarıyla mevcut vektör arama altyapınızdan yararlanmanızı sağlar.

Bu uyumluluk katmanı, kodunuzu Semantik Çekirdek'ten Agent Framework'e aşamalı olarak geçirmenize olanak tanır ve agent framework'ün basitleştirilmiş aracı oluşturma ve yürütme desenlerinden yararlanarak mevcut KernelFunction uygulamalarınızı yeniden kullanır.

6. Aracı Akışsız Çağırma

yöntemi adlarında invokerun, dönüş türleri (örneğin, AgentRunResponse) ve parametrelerinde önemli farklar görülebilir.

Semantik Çekirdek

Akış Dışı çağrısı, birden çok aracı iletisi döndürmek için zaman uyumsuz bir yineleyici deseni kullanır.

async for response in agent.invoke(
    messages=user_input,
    thread=thread,
):
    print(f"# {response.role}: {response}")
    thread = response.thread

Son yanıtı almak için bir kolaylık yöntemi de vardı:

response = await agent.get_response(messages="How do I reset my bike tire?", thread=thread)
print(f"# {response.role}: {response}")

Ajan Çerçevesi

AkışSız çalıştırma, birden çok ileti içerebilen aracı yanıtıyla tek AgentRunResponse bir döndürür. Çalıştırmanın metin sonucu veya response.textiçinde str(response) kullanılabilir. Yanıt kapsamında oluşturulan tüm iletiler listede döndürülür response.messages . Bu, araç arama iletilerini, işlev sonuçlarını, akıl yürütme güncelleştirmelerini ve nihai sonuçları içerebilir.

agent = ...

response = await agent.run(user_input, thread)
print("Agent response:", response.text)

7. Aracı Akış Çağırma

yöntemi adlarında invokerun_streamile arasındaki temel farklar, dönüş türleri (AgentRunResponseUpdate) ve parametreleridir.

Semantik Çekirdek

async for update in agent.invoke_stream(
    messages="Draft a 2 sentence blurb.",
    thread=thread,
):
    if update.message:
        print(update.message.content, end="", flush=True)

Ajan Çerçevesi

Benzer akış API'si deseni ve temel fark, güncelleştirme başına aracıyla ilgili daha fazla bilgi de dahil olmak üzere nesneleri döndürmesidir AgentRunResponseUpdate .

Aracıyı temel alan herhangi bir hizmet tarafından üretilen tüm içerikler döndürülür. Aracının nihai sonucu, değerleri tek bir yanıtta update birleştirerek kullanılabilir.

from agent_framework import AgentRunResponse
agent = ...
updates = []
async for update in agent.run_stream(user_input, thread):
    updates.append(update)
    print(update.text)

full_response = AgentRunResponse.from_agent_run_response_updates(updates)
print("Full agent response:", full_response.text)

Bunu doğrudan da yapabilirsiniz:

from agent_framework import AgentRunResponse
agent = ...
full_response = AgentRunResponse.from_agent_response_generator(agent.run_stream(user_input, thread))
print("Full agent response:", full_response.text)

8. Seçenekler Yapılandırması

Sorun: Anlam Çekirdeği'nde karmaşık seçenekler kurulumu

from semantic_kernel.connectors.ai.open_ai import OpenAIPromptExecutionSettings

settings = OpenAIPromptExecutionSettings(max_tokens=1000)
arguments = KernelArguments(settings)

response = await agent.get_response(user_input, thread=thread, arguments=arguments)

Çözüm: Agent Framework'te basitleştirilmiş seçenekler

Agent Framework, tüm parametrelerin doğrudan ilgili yöntemlere geçirilmesine olanak tanır; böylece, istemediğiniz sürece fazladan bir şey içeri aktarmanız veya herhangi bir seçenek nesnesi oluşturmanız gerekmez. Dahili olarak, ve ChatOptionsiçin ChatClients bir ChatAgents nesnesi kullanır ve isterseniz oluşturabilir ve geçirebilirsiniz. Bu, seçenekleri tutmak için içinde ChatAgent de oluşturulur ve çağrı başına geçersiz kılınabilir.

agent = ...

response = await agent.run(user_input, thread, max_tokens=1000, frequency_penalty=0.5)

Uyarı

Yukarıdakiler bir ChatAgentöğesine özgüdür, çünkü diğer aracıların farklı seçenekleri olabilir, hepsi parametre olarak kabul messages etmelidir, çünkü bu içinde AgentProtocoltanımlanmıştır.

Sonraki Adımlar

Hızlı Başlangıç Kılavuzu