Bagikan melalui

Panduan Migrasi Semantik Kernel ke Kerangka Kerja Agen

Manfaat Microsoft Agent Framework

  • API yang disederhanakan: Mengurangi kompleksitas dan kode boilerplate.
  • Performa Yang Lebih Baik: Pembuatan objek yang dioptimalkan dan penggunaan memori.
  • Antarmuka Terpadu: Pola yang konsisten di berbagai penyedia AI.
  • Pengalaman Pengembang yang Ditingkatkan: API yang lebih intuitif dan dapat ditemukan.

Bagian berikut ini meringkas perbedaan utama antara Semantic Kernel Agent Framework dan Microsoft Agent Framework untuk membantu Anda memigrasikan kode Anda.

1. Pembaruan Namespace

Kernel Semantik

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

Kerangka Kerja Agen

Namespace Agent Framework berada di bawah Microsoft.Agents.AI. Agent Framework menggunakan pesan AI inti dan jenis konten dari Microsoft.Extensions.AI untuk komunikasi antar komponen.

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

2. Penyederhanaan Pembuatan Agen

Kernel Semantik

Setiap agen di Kernel Semantik tergantung pada Kernel instans dan memiliki kosong Kernel jika tidak disediakan.

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

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

Azure AI Foundry mengharuskan sumber daya agen dibuat di cloud sebelum membuat kelas agen lokal yang menggunakannya.

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

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

AzureAIAgent agent = new(definition, azureAgentClient);

Kerangka Kerja Agen

Pembuatan agen dalam Agent Framework dibuat lebih sederhana dengan ekstensi yang disediakan oleh semua penyedia utama.

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

Selain itu, untuk penyedia agen yang dihosting, Anda juga dapat menggunakan GetAIAgent metode untuk mengambil agen dari agen yang dihosting yang ada.

AIAgent azureFoundryAgent = await persistentAgentsClient.GetAIAgentAsync(agentId);

3. Utas Agen/Pembuatan Sesi

Kernel Semantik

Pemanggil harus mengetahui jenis utas dan membuatnya secara manual.

// 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);

Kerangka Kerja Agen

Agen bertanggung jawab untuk membuat sesi.

// New.
AgentSession session = await agent.GetNewSessionAsync();

4. Utas Agen yang Dihosting/Pembersihan Sesi

Kasus ini berlaku secara eksklusif untuk beberapa penyedia AI yang masih menyediakan utas yang dihosting.

Kernel Semantik

Utas memiliki self metode penghapusan.

Penyedia Asisten OpenAI:

await thread.DeleteAsync();

Kerangka Kerja Agen

Nota

Respons OpenAI memperkenalkan model percakapan baru yang menyederhanakan cara percakapan ditangani. Perubahan ini menyederhanakan manajemen riwayat obrolan yang dihosting dibandingkan dengan model Asisten OpenAI yang sekarang tidak digunakan lagi. Untuk informasi selengkapnya, lihat panduan migrasi Asisten OpenAI.

Agent Framework tidak memiliki riwayat obrolan atau API penghapusan sesi dalam jenis karena AgentSession tidak semua penyedia mendukung riwayat obrolan yang dihosting atau penghapusan riwayat obrolan.

Jika Anda memerlukan penghapusan riwayat obrolan dan penyedia mengizinkannya, pemanggil harus melacak sesi yang dibuat dan menghapus hsitory obrolan terkait nanti ketika diperlukan melalui SDK penyedia.

Penyedia Asisten OpenAI:

await assistantClient.DeleteThreadAsync(session.ConversationId);

5. Pendaftaran Alat

Kernel Semantik

Untuk mengekspos fungsi sebagai alat, Anda harus:

  1. Hiasi fungsi dengan [KernelFunction] atribut .
  2. Memiliki Plugin kelas atau menggunakan KernelPluginFactory untuk membungkus fungsi.
  3. Kernel Memiliki untuk menambahkan plugin Anda.
  4. Teruskan ke Kernel agen.
KernelFunction function = KernelFunctionFactory.CreateFromMethod(GetWeather);
KernelPlugin plugin = KernelPluginFactory.CreateFromFunctions("KernelPluginName", [function]);
Kernel kernel = ... // Create kernel
kernel.Plugins.Add(plugin);

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

Kerangka Kerja Agen

Dalam Agent Framework, dalam satu panggilan Anda dapat mendaftarkan alat langsung dalam proses pembuatan agen.

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

6. Pemanggilan Agen Non-Streaming

Perbedaan utama dapat dilihat dalam nama metode dari Invoke ke Run, jenis pengembalian, dan parameter AgentRunOptions.

Kernel Semantik

Non-Streaming menggunakan pola IAsyncEnumerable<AgentResponseItem<ChatMessageContent>> streaming untuk mengembalikan beberapa pesan agen.

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

Kerangka Kerja Agen

Non-Streaming mengembalikan satu AgentResponse dengan respons agen yang dapat berisi beberapa pesan. Hasil teks dari eksekusi tersedia di AgentResponse.Text atau AgentResponse.ToString(). Semua pesan yang dibuat sebagai bagian dari respons dikembalikan dalam AgentResponse.Messages daftar. Ini mungkin termasuk pesan panggilan alat, hasil fungsi, pembaruan penalaran, dan hasil akhir.

AgentResponse agentResponse = await agent.RunAsync(userInput, session);

7. Pemanggilan Streaming Agen

Perbedaan utama ada dalam nama metode dari Invoke ke Run, jenis pengembalian, dan parameter AgentRunOptions.

Kernel Semantik

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

Kerangka Kerja Agen

Agent Framework memiliki pola API streaming yang sama, dengan perbedaan utamanya adalah mengembalikan AgentResponseUpdate objek yang menyertakan lebih banyak informasi terkait agen per pembaruan.

Semua pembaruan yang dihasilkan oleh layanan apa pun yang mendasar AIAgent dikembalikan. Hasil tekstual agen tersedia dengan menggabungkan AgentResponse.Text nilai.

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

8. Tanda Tangan Fungsi Alat

Masalah: Metode plugin Kernel Semantik membutuhkan [KernelFunction] atribut.

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

Solusi: Agent Framework dapat menggunakan metode secara langsung tanpa atribut.

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

9. Konfigurasi Opsi

Masalah: Penyiapan opsi kompleks di Kernel Semantik.

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

Solusi: Opsi yang disederhanakan dalam Kerangka Kerja Agen.

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

Penting

Contoh ini menunjukkan meneruskan opsi khusus implementasi ke ChatClientAgent. Tidak semua AIAgents dukungan ChatClientAgentRunOptions. ChatClientAgent disediakan untuk membangun agen berdasarkan layanan inferensi yang mendasar, dan oleh karena itu mendukung opsi inferensi seperti MaxOutputTokens.

10. Injeksi Dependensi

Kernel Semantik

Pendaftaran Kernel diperlukan dalam kontainer layanan untuk dapat membuat agen, karena setiap abstraksi agen perlu diinisialisasi dengan Kernel properti.

Kernel Semantik menggunakan Agent jenis sebagai kelas abstraksi dasar untuk agen.

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

Kerangka Kerja Agen

Agent Framework menyediakan AIAgent jenis sebagai kelas abstraksi dasar.

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

11. Konsolidasi Jenis Agen

Kernel Semantik

Semantic Kernel menyediakan kelas agen tertentu untuk berbagai layanan, misalnya:

  • ChatCompletionAgent untuk digunakan dengan layanan inferensi berbasis penyelesaian obrolan.
  • OpenAIAssistantAgent untuk digunakan dengan layanan Asisten OpenAI.
  • AzureAIAgent untuk digunakan dengan layanan Azure AI Foundry Agents.

Kerangka Kerja Agen

Agent Framework mendukung semua layanan yang disebutkan melalui satu jenis agen, ChatClientAgent.

ChatClientAgent dapat digunakan untuk membangun agen menggunakan layanan yang mendasar yang menyediakan SDK yang mengimplementasikan IChatClient antarmuka.

Perbedaan utama

Berikut adalah ringkasan perbedaan utama antara Semantic Kernel Agent Framework dan Microsoft Agent Framework untuk membantu Anda memigrasikan kode Anda.

1. Pembaruan paket dan impor

Kernel Semantik

Paket Kernel Semantik diinstal sebagai semantic-kernel dan diimpor sebagai semantic_kernel. Paket ini juga memiliki sejumlah extras yang dapat Anda instal untuk menginstal dependensi yang berbeda untuk penyedia AI yang berbeda dan fitur lainnya.

from semantic_kernel import Kernel
from semantic_kernel.agents import ChatCompletionAgent

Kerangka Kerja Agen

Paket Agent Framework diinstal sebagai agent-framework dan diimpor sebagai agent_framework. Agent Framework dibangun secara berbeda, memiliki paket agent-framework-core inti yang berisi fungsionalitas inti, dan kemudian ada beberapa paket yang mengandalkan paket inti tersebut, seperti agent-framework-azure-ai, agent-framework-mem0, agent-framework-copilotstudio, dll. Ketika Anda menjalankannya pip install agent-framework --pre akan menginstal paket inti dan semua paket, sehingga Anda dapat memulai semua fitur dengan cepat. Ketika Anda siap untuk mengurangi jumlah paket karena Anda tahu apa yang Anda butuhkan, Anda hanya dapat menginstal paket yang Anda butuhkan, jadi misalnya jika Anda hanya berencana untuk menggunakan Azure AI Foundry dan Mem0, Anda hanya dapat menginstal dua paket tersebut: pip install agent-framework-azure-ai agent-framework-mem0 --pre, agent-framework-core adalah dependensi untuk kedua paket tersebut, jadi akan diinstal secara otomatis.

Meskipun paket dibagi, impor semuanya berasal dari agent_framework, atau modulnya. Jadi, misalnya untuk mengimpor klien untuk Azure AI Foundry yang akan Anda lakukan:

from agent_framework.azure import AzureAIAgentClient

Banyak jenis yang paling umum digunakan diimpor langsung dari agent_framework:

from agent_framework import ChatMessage, ChatAgent

2. Konsolidasi Jenis Agen

Kernel Semantik

Semantic Kernel menyediakan kelas agen tertentu untuk berbagai layanan, misalnya, ChatCompletionAgent, AzureAIAgent, OpenAIAssistantAgent, dll. Lihat Jenis agen di Kernel Semantik.

Kerangka Kerja Agen

Dalam Agent Framework, sebagian besar agen dibangun menggunakan ChatAgent yang dapat digunakan dengan semua ChatClient layanan berbasis, seperti Azure AI Foundry, OpenAI ChatCompletion, dan OpenAI Responses. Ada dua agen tambahan: CopilotStudioAgent untuk digunakan dengan Copilot Studio dan A2AAgent untuk digunakan dengan A2A.

Semua agen bawaan didasarkan pada BaseAgent (from agent_framework import BaseAgent). Dan semua agen konsisten dengan AgentProtocol antarmuka (from agent_framework import AgentProtocol).

3. Penyederhanaan Pembuatan Agen

Kernel Semantik

Setiap agen di Kernel Semantik tergantung pada Kernel instans dan akan memiliki kosong Kernel jika tidak disediakan.

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

Kerangka Kerja Agen

Pembuatan agen dalam Agent Framework dapat dilakukan dengan dua cara, secara langsung:

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

Atau, dengan metode kenyamanan yang disediakan oleh klien obrolan:

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

Metode langsung mengekspos semua parameter yang mungkin dapat Anda tetapkan untuk agen Anda. Meskipun metode kenyamanan memiliki subset, Anda masih dapat meneruskan serangkaian parameter yang sama, karena memanggil metode langsung secara internal.

4. Pembuatan Utas Agen

Kernel Semantik

Pemanggil harus mengetahui jenis utas dan membuatnya secara manual.

from semantic_kernel.agents import ChatHistoryAgentThread

thread = ChatHistoryAgentThread()

Kerangka Kerja Agen

Agen dapat diminta untuk membuat utas baru untuk Anda.

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

Utas kemudian dibuat dengan salah satu dari tiga cara:

  1. Jika agen memiliki thread_id set (atau conversation_id atau sesuatu yang serupa), agen akan membuat utas di layanan yang mendasar dengan ID tersebut. Setelah utas memiliki service_thread_id, Anda tidak dapat lagi menggunakannya untuk menyimpan pesan dalam memori. Ini hanya berlaku untuk agen yang memiliki konsep utas sisi layanan. seperti Agen Azure AI Foundry dan Asisten OpenAI.
  2. Jika agen memiliki set chat_message_store_factory , agen akan menggunakan pabrik tersebut untuk membuat penyimpanan pesan dan menggunakannya untuk membuat utas dalam memori. Kemudian tidak dapat lagi digunakan dengan agen dengan parameter yang store diatur ke True.
  3. Jika tidak ada pengaturan sebelumnya yang diatur, pengaturan tersebut dipertimbangkan uninitialized dan tergantung pada cara penggunaannya, pengaturan tersebut akan menjadi utas dalam memori atau utas layanan.

Kerangka Kerja Agen

Nota

Respons OpenAI memperkenalkan model percakapan baru yang menyederhanakan cara percakapan ditangani. Ini menyederhanakan manajemen utas yang dihosting dibandingkan dengan model Asisten OpenAI yang sekarang tidak digunakan lagi. Untuk informasi selengkapnya, lihat panduan migrasi Asisten OpenAI.

Agent Framework tidak memiliki API penghapusan utas dalam jenis karena AgentThread tidak semua penyedia mendukung utas atau penghapusan utas yang dihosting dan ini akan menjadi lebih umum karena lebih banyak penyedia beralih ke arsitektur berbasis respons.

Jika Anda memerlukan penghapusan utas dan penyedia mengizinkan ini, pemanggil harus melacak utas yang dibuat dan menghapusnya nanti jika diperlukan melalui sdk penyedia.

Penyedia Asisten OpenAI:

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

5. Pendaftaran Alat

Kernel Semantik

Untuk mengekspos fungsi sebagai alat, Anda harus:

  1. Hiasi fungsi dengan @kernel_function dekorator.
  2. Memiliki Plugin kelas atau menggunakan pabrik plugin kernel untuk membungkus fungsi.
  3. Kernel Memiliki untuk menambahkan plugin Anda.
  4. Teruskan ke Kernel agen.
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()],
)

Kerangka Kerja Agen

Dalam satu panggilan, Anda dapat mendaftarkan alat langsung dalam proses pembuatan agen. Agent Framework tidak memiliki konsep plugin untuk membungkus beberapa fungsi, tetapi Anda masih dapat melakukannya jika diinginkan.

Cara paling sederhana untuk membuat alat hanyalah membuat fungsi Python:

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

agent = chat_client.as_agent(tools=get_weather)

Nota

Parameter tools hadir pada pembuatan agen, run metode dan run_stream , serta get_response metode dan get_streaming_response , memungkinkan Anda untuk menyediakan alat baik sebagai daftar atau satu fungsi.

Nama fungsi kemudian akan menjadi nama alat, dan docstring akan menjadi deskripsi alat, Anda juga dapat menambahkan deskripsi ke parameter:

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

Terakhir, Anda dapat menggunakan dekorator untuk menyesuaikan nama dan deskripsi alat lebih lanjut:

from typing import Annotated
from agent_framework import tool

@tool(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."

Ini juga berfungsi saat Anda membuat kelas dengan beberapa alat sebagai metode.

Saat membuat agen, Anda sekarang dapat menyediakan alat fungsi ke agen dengan meneruskannya ke tools parameter .

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.as_agent(tools=[plugin.get_weather, plugin.get_weather_details])

... # use the agent

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

Nota

Fungsi dalam kelas juga dapat dihiasi dengan @tool untuk menyesuaikan nama dan deskripsi alat.

Mekanisme ini juga berguna untuk alat yang membutuhkan input tambahan yang tidak dapat disediakan oleh LLM, seperti koneksi, rahasia, dll.

Kompatibilitas: Menggunakan KernelFunction sebagai alat Agent Framework

Jika Anda memiliki kode Kernel Semantik yang ada dengan KernelFunction instans (baik dari perintah atau dari metode), Anda dapat mengonversinya ke alat Agent Framework menggunakan metode ..as_agent_framework_tool

Penting

Fitur ini memerlukan semantic-kernel versi 1.38 atau yang lebih tinggi.

Menggunakan KernelFunction dari templat perintah

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").as_agent(tools=agent_tool)
response = await agent.run("What kind of day is it?")
print(response.text)

Menggunakan KernelFunction dari metode

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").as_agent(tools=agent_tool)
response = await agent.run("What's the weather in Seattle?")
print(response.text)

Menggunakan VectorStore dengan create_search_function

Anda juga dapat menggunakan integrasi VectorStore Kernel Semantic dengan Agent Framework. Metode create_search_function dari koleksi penyimpanan vektor mengembalikan KernelFunction yang dapat dikonversi ke alat Kerangka Kerja Agen.

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

Pola ini berfungsi dengan konektor Semantic Kernel VectorStore (Azure AI Search, Qdrant, Pinecone, dll.), memungkinkan Anda memanfaatkan infrastruktur pencarian vektor yang ada dengan agen Agent Framework.

Lapisan kompatibilitas ini memungkinkan Anda untuk secara bertahap memigrasikan kode Anda dari Semantic Kernel ke Agent Framework, menggunakan kembali implementasi yang ada KernelFunction sambil memanfaatkan pola pembuatan dan eksekusi agen Agen Framework yang disederhanakan.

6. Pemanggilan Agen Non-Streaming

Perbedaan utama dapat dilihat dalam nama metode dari invoke ke run, jenis pengembalian (misalnya, AgentResponse) dan parameter.

Kernel Semantik

Pemanggilan Non-Streaming menggunakan pola iterator asinkron untuk mengembalikan beberapa pesan agen.

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

Dan ada metode kenyamanan untuk mendapatkan respons akhir:

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

Kerangka Kerja Agen

Eksekusi Non-Streaming mengembalikan satu AgentResponse dengan respons agen yang dapat berisi beberapa pesan. Hasil teks dari eksekusi tersedia di response.text atau str(response). Semua pesan yang dibuat sebagai bagian dari respons dikembalikan dalam response.messages daftar. Ini mungkin termasuk pesan panggilan alat, hasil fungsi, pembaruan penalaran, dan hasil akhir.

agent = ...

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

7. Pemanggilan Streaming Agen

Perbedaan utama dalam nama metode dari invoke ke run_stream, mengembalikan jenis (AgentResponseUpdate) dan parameter.

Kernel Semantik

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)

Kerangka Kerja Agen

Pola API streaming serupa dengan perbedaan utama adalah bahwa ia mengembalikan AgentResponseUpdate objek termasuk lebih banyak informasi terkait agen per pembaruan.

Semua konten yang dihasilkan oleh layanan apa pun yang mendasar Agen dikembalikan. Hasil akhir agen tersedia dengan menggabungkan update nilai ke dalam satu respons.

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

full_response = AgentResponse.from_agent_response_updates(updates)
print("Full agent response:", full_response.text)

Anda bahkan dapat melakukannya secara langsung:

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

8. Konfigurasi Opsi

Masalah: Penyiapan opsi kompleks di Kernel Semantik

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)

Solusi: Opsi berbasis TypedDict yang Disederhanakan dalam Kerangka Kerja Agen

Agent Framework menggunakan sistem opsi berbasis TypedDict untuk ChatClients dan ChatAgents. Opsi diteruskan melalui parameter tunggal options sebagai kamus yang ditik, dengan kelas TypedDict khusus penyedia (seperti OpenAIChatOptions) untuk pelengkapan otomatis IDE penuh dan pemeriksaan jenis.

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

# Set default options at agent creation
agent = client.as_agent(
    instructions="You are a helpful assistant.",
    default_options={
        "max_tokens": 1000,
        "temperature": 0.7,
    }
)

# Override options per call
response = await agent.run(
    user_input,
    thread,
    options={
        "max_tokens": 500,
        "frequency_penalty": 0.5,
    }
)

Nota

Parameter tools dan instructions tetap sebagai argumen kata kunci langsung pada pembuatan dan run() metode agen, dan tidak diteruskan melalui options kamus. Lihat Panduan Peningkatan Opsi Yang Ditik untuk pola migrasi terperinci.

Langkah selanjutnya

Panduan Mulai Cepat

  • Last updated on