Panduan Migrasi Kerangka Agen Kandidat Rilis

Saat kami mentransisikan beberapa agen dari tahap eksperimental ke tahap kandidat rilis, kami telah memperbarui API untuk menyederhanakan dan memperlancar penggunaannya. Lihat panduan skenario tertentu untuk mempelajari cara memperbarui kode yang ada agar berfungsi dengan API terbaru yang tersedia.

API Umum untuk Pemanggilan Agen

Dalam versi 1.43.0 kami merilis API pemanggilan agen umum baru, yang akan memungkinkan semua jenis agen dipanggil melalui API umum.

Untuk mengaktifkan API baru ini, kami memperkenalkan gagasan AgentThread, yang mewakili utas percakapan dan menyederhanakan berbagai persyaratan manajemen utas untuk jenis-jenis agen yang berbeda. Untuk beberapa jenis agen, di masa depan juga akan memungkinkan implementasi utas yang berbeda menggunakan agen yang sama.

Metode Invoke umum yang kami perkenalkan memungkinkan Anda menyampaikan pesan yang ingin Anda berikan kepada agen dan AgentThreadopsional. Jika AgentThread disediakan, ini akan melanjutkan percakapan yang sudah ada di AgentThread. Jika AgentThread tidak disediakan, utas default baru akan dibuat dan dikembalikan sebagai bagian dari respons.

Dimungkinkan juga untuk membuat instans AgentThread secara manual, misalnya dalam kasus di mana Anda mungkin memiliki ID thread dari layanan agen dasar, dan Anda ingin melanjutkan thread tersebut. Anda mungkin juga ingin menyesuaikan opsi utas, misalnya alat yang terkait.

Berikut adalah contoh sederhana tentang bagaimana agen apa pun sekarang dapat digunakan dengan kode agnostik agen.

private async Task UseAgentAsync(Agent agent, AgentThread? agentThread = null)
{
    // Invoke the agent, and continue the existing thread if provided.
    var responses = agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "Hi"), agentThread);

    // Output results.
    await foreach (AgentResponseItem<ChatMessageContent> response in responses)
    {
        Console.WriteLine(response);
        agentThread = response.Thread;
    }

    // Delete the thread if required.
    if (agentThread is not null)
    {
        await agentThread.DeleteAsync();
    }
}

Perubahan ini diterapkan di:

Opsi Proses Agen Azure AI

AzureAIAgent saat ini hanya mendukung utas jenis AzureAIAgentThread.

Selain memungkinkan thread dibuat secara otomatis untuk Anda saat pemanggilan agen, Anda juga dapat membuat instance AzureAIAgentThreadsecara manual.

AzureAIAgentThread mendukung pembuatan dengan menggunakan alat dan metadata yang disesuaikan, serta pesan untuk memulai percakapan.

AgentThread thread = new AzureAIAgentThread(
    agentsClient,
    messages: seedMessages,
    toolResources: tools,
    metadata: metadata);

Anda juga dapat membuat instans AzureAIAgentThread yang melanjutkan percakapan yang sudah ada.

AgentThread thread = new AzureAIAgentThread(
    agentsClient,
    id: "my-existing-thread-id");

Opsi Utas Agen Bedrock

BedrockAgent saat ini hanya mendukung utas jenis BedrockAgentThread.

Selain memungkinkan thread dibuat secara otomatis untuk Anda saat pemanggilan agen, Anda juga dapat membuat instance BedrockAgentThreadsecara manual.

AgentThread thread = new BedrockAgentThread(amazonBedrockAgentRuntimeClient);

Anda juga dapat membuat instans BedrockAgentThread yang melanjutkan percakapan yang sudah ada.

AgentThread thread = new BedrockAgentThread(
    amazonBedrockAgentRuntimeClient,
    sessionId: "my-existing-session-id");

Opsi Utas untuk Agen Penyelesaian Obrolan

ChatCompletionAgent saat ini hanya mendukung utas jenis ChatHistoryAgentThread. ChatHistoryAgentThread menggunakan objek ChatHistory di dalam memori untuk menyimpan pesan di utas.

Selain memungkinkan thread dibuat secara otomatis untuk Anda saat pemanggilan agen, Anda juga dapat membuat instance ChatHistoryAgentThreadsecara manual.

AgentThread thread = new ChatHistoryAgentThread();

Anda juga dapat membuat instans ChatHistoryAgentThread yang melanjutkan percakapan yang ada dengan meneruskan objek ChatHistory dengan pesan yang ada.

ChatHistory chatHistory = new([new ChatMessageContent(AuthorRole.User, "Hi")]);

AgentThread thread = new ChatHistoryAgentThread(chatHistory: chatHistory);

Pengaturan Diskusi Asisten OpenAI

OpenAIAssistantAgent saat ini hanya mendukung utas jenis OpenAIAssistantAgentThread.

Selain memungkinkan thread dibuat secara otomatis untuk Anda saat pemanggilan agen, Anda juga dapat membuat instance OpenAIAssistantAgentThreadsecara manual.

OpenAIAssistantAgentThread mendukung pembuatan dengan menggunakan alat dan metadata yang disesuaikan, serta pesan untuk memulai percakapan.

AgentThread thread = new OpenAIAssistantAgentThread(
    assistantClient,
    messages: seedMessages,
    codeInterpreterFileIds: fileIds,
    vectorStoreId: "my-vector-store",
    metadata: metadata);

Anda juga dapat membuat instans OpenAIAssistantAgentThread yang melanjutkan percakapan yang sudah ada.

AgentThread thread = new OpenAIAssistantAgentThread(
    assistantClient,
    id: "my-existing-thread-id");

Panduan Migrasi OpenAIAssistantAgent C#

Kami baru-baru ini menerapkan perubahan signifikan di sekitar OpenAIAssistantAgent di Kernel Semantik Agent Framework.

Perubahan ini diterapkan di:

Perubahan ini dimaksudkan untuk:

  • Sesuaikan dengan pola penggunaan untuk AzureAIAgentkami.
  • Perbaiki bug di sekitar pola inisialisasi statis.
  • Hindari membatasi fitur berdasarkan abstraksi SDK yang mendasarinya.

Panduan ini menyediakan instruksi langkah demi langkah untuk memigrasikan kode C# Anda dari implementasi lama ke yang baru. Perubahan termasuk pembaruan untuk membuat asisten, mengelola siklus hidup asisten, menangani thread, file, dan penyimpanan berbasis vektor.

1. Instansiasi Pelanggan

Sebelumnya, OpenAIClientProvider diperlukan untuk membuat OpenAIAssistantAgentapa pun. Dependensi ini telah disederhanakan.

Cara Baru

OpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(endpointUrl));
AssistantClient assistantClient = client.GetAssistantClient();

Jalan Lama (Tidak Digunakan Lagi)

var clientProvider = new OpenAIClientProvider(...);

2. Siklus Hidup Asisten

Membuat sebuah Asisten

Anda sekarang dapat langsung menginisialisasi OpenAIAssistantAgent menggunakan definisi Asisten yang sudah ada atau yang baru dari AssistantClient.

Cara Baru
Assistant definition = await assistantClient.GetAssistantAsync(assistantId);
OpenAIAssistantAgent agent = new(definition, client);

Plugin dapat langsung disertakan selama inisialisasi:

KernelPlugin plugin = KernelPluginFactory.CreateFromType<YourPlugin>();
Assistant definition = await assistantClient.GetAssistantAsync(assistantId);
OpenAIAssistantAgent agent = new(definition, client, [plugin]);

Membuat definisi asisten baru menggunakan metode ekstensi:

Assistant assistant = await assistantClient.CreateAssistantAsync(
    model,
    name,
    instructions: instructions,
    enableCodeInterpreter: true);
Jalan Lama (Tidak Digunakan Lagi)

Sebelumnya, definisi asisten dikelola secara tidak langsung.

3. Memanggil Agen

Anda dapat menentukan RunCreationOptions secara langsung, memungkinkan akses penuh ke kemampuan SDK yang mendasar.

Cara Baru

RunCreationOptions options = new(); // configure as needed
var result = await agent.InvokeAsync(options);

Jalan Lama (Tidak Digunakan Lagi)

var options = new OpenAIAssistantInvocationOptions();

4. Penghapusan Asisten

Anda dapat langsung mengelola penghapusan asisten dengan AssistantClient.

await assistantClient.DeleteAssistantAsync(agent.Id);

5. Siklus Hidup Utas

Membuat (Thread)

Thread sekarang dikelola melalui AssistantAgentThread.

Cara Baru
var thread = new AssistantAgentThread(assistantClient);
// Calling CreateAsync is an optional step.
// A thread will be created automatically on first use if CreateAsync was not called.
// Note that CreateAsync is not on the AgentThread base implementation since not all
// agent services support explicit thread creation.
await thread.CreateAsync();
Jalan Lama (Tidak Digunakan Lagi)

Sebelumnya, manajemen utas tidak langsung atau dikelola oleh agen.

Penghapusan Utas

var thread = new AssistantAgentThread(assistantClient, "existing-thread-id");
await thread.DeleteAsync();

6. Siklus Hidup File

Pembuatan dan penghapusan file sekarang menggunakan OpenAIFileClient.

Unggahan File

string fileId = await client.UploadAssistantFileAsync(stream, "<filename>");

Penghapusan File

await client.DeleteFileAsync(fileId);

7. Siklus Hidup Toko Vektor

Penyimpanan vektor dikelola langsung melalui VectorStoreClient dengan metode ekstensi yang nyaman.

Pembuatan Toko Vektor

string vectorStoreId = await client.CreateVectorStoreAsync([fileId1, fileId2], waitUntilCompleted: true);

Penghapusan Penyimpanan Vektor

await client.DeleteVectorStoreAsync(vectorStoreId);

Kompatibilitas ke Belakang

Pola yang tidak digunakan lagi ditandai dengan [Obsolete]. Untuk menekan peringatan usang (CS0618), perbarui file proyek Anda sebagai berikut:

<PropertyGroup>
  <NoWarn>$(NoWarn);CS0618</NoWarn>
</PropertyGroup>

Panduan migrasi ini membantu Anda bertransisi dengan lancar ke implementasi baru, menyederhanakan inisialisasi klien, manajemen sumber daya, dan integrasi dengan Kernel Semantik .NET SDK.

Penting

Untuk pengembang yang meningkatkan ke Kernel Semantik Python 1.26.1 atau yang lebih baru, pembaruan signifikan dan perubahan mendasar telah diperkenalkan untuk meningkatkan kerangka kerja agen kami saat kami mendekati peluncuran umum.

Perubahan ini diterapkan di:

Perubahan sebelumnya diterapkan di:

Panduan ini menyediakan instruksi langkah demi langkah untuk memigrasikan kode Python Anda dari implementasi lama ke implementasi baru.

Pengimpor Agen

Semua jalur impor agen telah dikonsolidasikan di bawah semantic_kernel.agents.

Gaya impor terbaru

from semantic_kernel.agents import (
    AutoGenConversableAgent,
    AzureAIAgent,
    AzureAssistantAgent,
    BedrockAgent,
    ChatCompletionAgent,
    OpenAIAssistantAgent,
)

Gaya impor sebelumnya (tidak digunakan lagi):

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.agents.autogen import AutoGenConversableAgent
from semantic_kernel.agents.azure_ai import AzureAIAgent
from semantic_kernel.agents.bedrock import BedrockAgent
from semantic_kernel.agents.open_ai import AzureAssistantAgent, OpenAIAssistantAgent

API Umum untuk Pemanggilan Agen

Pada Kernel Semantik Python 1.26.0 dan versi yang lebih baru, kami memperkenalkan abstraksi bersama baru untuk manajemen thread di semua agen. Untuk setiap agen, kami sekarang mengekspos kelas utas yang mengimplementasikan kelas dasar AgentThread, memungkinkan manajemen konteks melalui metode seperti create() dan delete().

Respons agen get_response(...), invoke(...), invoke_stream(...) sekarang mengembalikan AgentResponseItem[ChatMessageContent], yang memiliki dua atribut:

message: TMessage  # Usually ChatMessageContent
thread: AgentThread  # Contains the concrete type for the given agent

Menambahkan Pesan ke Utas

Pesan harus ditambahkan ke utas melalui argumen messages sebagai bagian dari metode-metode agen seperti get_response(...), invoke(...), atau invoke_stream(...).

Percakapan Agen Azure AI

Sebuah AzureAIAgentThread dapat dibuat sebagai berikut:

from semantic_kernel.agents import AzureAIAgentThread

thread = AzureAIAgentThread(
    client: AIProjectClient,  # required
    messages: list[ThreadMessageOptions] | None = None,  # optional
    metadata: dict[str, str] | None = None,  # optional
    thread_id: str | None = None,  # optional
    tool_resources: "ToolResources | None" = None,  # optional
)

Menyediakan thread_id (string) memungkinkan Anda untuk melanjutkan percakapan yang sudah ada. Jika dihilangkan, utas baru dibuat dan dikembalikan sebagai bagian dari respons agen.

Contoh implementasi lengkap:

import asyncio

from azure.identity.aio import DefaultAzureCredential

from semantic_kernel.agents import AzureAIAgent, AzureAIAgentSettings, AzureAIAgentThread

USER_INPUTS = [
    "Why is the sky blue?",
    "What are we talking about?",
]

async def main() -> None:
    ai_agent_settings = AzureAIAgentSettings.create()

    async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds) as client,
    ):
        # 1. Create an agent on the Azure AI agent service
        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.model_deployment_name,
            name="Assistant",
            instructions="Answer the user's questions.",
        )

        # 2. Create a Semantic Kernel agent for the Azure AI agent
        agent = AzureAIAgent(
            client=client,
            definition=agent_definition,
        )

        # 3. Create a thread for the agent
        # If no thread is provided, a new thread will be
        # created and returned with the initial response
        thread: AzureAIAgentThread = None

        try:
            for user_input in USER_INPUTS:
                print(f"# User: {user_input}")
                # 4. Invoke the agent with the specified message for response
                response = await agent.get_response(messages=user_input, thread=thread)
                print(f"# {response.content}: {response}")
                thread = response.thread
        finally:
            # 6. Cleanup: Delete the thread and agent
            await thread.delete() if thread else None
            await client.agents.delete_agent(agent.id)

if __name__ == "__main__":
    asyncio.run(main())

Utas Agen Bedrock

BedrockAgent menggunakan BedrockAgentThread untuk mengelola riwayat dan konteks percakapan. Anda dapat memberikan session_id untuk melanjutkan atau memulai konteks percakapan baru.

from semantic_kernel.agents import BedrockAgentThread

thread = BedrockAgentThread(
    bedrock_runtime_client: Any,
    session_id: str | None = None,
)

Jika tidak ada session_id yang disediakan, konteks baru dibuat secara otomatis.

Contoh implementasi lengkap:

import asyncio

from semantic_kernel.agents import BedrockAgent, BedrockAgentThread

async def main():
    bedrock_agent = await BedrockAgent.create_and_prepare_agent(
        "semantic-kernel-bedrock-agent",
        instructions="You are a friendly assistant. You help people find information.",
    )

    # Create a thread for the agent
    # If no thread is provided, a new thread will be
    # created and returned with the initial response
    thread: BedrockAgentThread = None

    try:
        while True:
            user_input = input("User:> ")
            if user_input == "exit":
                print("\n\nExiting chat...")
                break

            # Invoke the agent
            # The chat history is maintained in the session
            response = await bedrock_agent.get_response(
                input_text=user_input,
                thread=thread,
            )
            print(f"Bedrock agent: {response}")
            thread = response.thread
    except KeyboardInterrupt:
        print("\n\nExiting chat...")
        return False
    except EOFError:
        print("\n\nExiting chat...")
        return False
    finally:
        # Delete the agent
        await bedrock_agent.delete_agent()
        await thread.delete() if thread else None


if __name__ == "__main__":
    asyncio.run(main())

Riwayat Percakapan Agen

ChatCompletionAgent menggunakan ChatHistoryAgentThread untuk mengelola riwayat percakapan. Ini dapat diinisialisasi sebagai berikut:

from semantic_kernel.agents import ChatHistoryAgentThread

thread = ChatHistoryAgentThread(
    chat_history: ChatHistory | None = None, 
    thread_id: str | None = None
)

Menyediakan thread_id memungkinkan melanjutkan percakapan yang ada. Menghilangkannya akan membuat utas baru. Serialisasi dan rehidrasi status utas didukung untuk konteks percakapan yang berkelanjutan.

Contoh implementasi lengkap:

import asyncio

from semantic_kernel.agents import ChatCompletionAgent, ChatHistoryAgentThread
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

# Simulate a conversation with the agent
USER_INPUTS = [
    "Hello, I am John Doe.",
    "What is your name?",
    "What is my name?",
]


async def main():
    # 1. Create the agent by specifying the service
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="Assistant",
        instructions="Answer the user's questions.",
    )

    # 2. Create a thread to hold the conversation
    # If no thread is provided, a new thread will be
    # created and returned with the initial response
    thread: ChatHistoryAgentThread = None

    for user_input in USER_INPUTS:
        print(f"# User: {user_input}")
        # 3. Invoke the agent for a response
        response = await agent.get_response(
            messages=user_input,
            thread=thread,
        )
        print(f"# {response.name}: {response}")
        # 4. Store the thread, which allows the agent to
        # maintain conversation history across multiple messages.
        thread = response.thread

    # 5. Cleanup: Clear the thread
    await thread.delete() if thread else None

if __name__ == "__main__":
    asyncio.run(main())

Percakapan Asisten OpenAI

AzureAssistantAgent dan OpenAIAssistantAgent menggunakan AssistantAgentThread untuk mengelola riwayat dan konteks percakapan:

from semantic_kernel.agents import ChatHistoryAgentThread

thread = AssistantAgentThread(
    client: AsyncOpenAI,
    thread_id: str | None = None,
    messages: Iterable["ThreadCreateMessage"] | NotGiven = NOT_GIVEN,
    metadata: dict[str, Any] | NotGiven = NOT_GIVEN,
    tool_resources: ToolResources | NotGiven = NOT_GIVEN,
)

Jika thread_id disediakan, percakapan yang sudah ada akan dilanjutkan; jika tidak ada, utas baru akan dibuat.

Contoh implementasi lengkap:

# Copyright (c) Microsoft. All rights reserved.
import asyncio

from semantic_kernel.agents import AzureAssistantAgent


# Simulate a conversation with the agent
USER_INPUTS = [
    "Why is the sky blue?",
    "What is the speed of light?",
    "What have we been talking about?",
]


async def main():
    # 1. Create the client using Azure OpenAI resources and configuration
    client, model = AzureAssistantAgent.setup_resources()

    # 2. Create the assistant on the Azure OpenAI service
    definition = await client.beta.assistants.create(
        model=model,
        instructions="Answer questions about the world in one sentence.",
        name="Assistant",
    )

    # 3. Create a Semantic Kernel agent for the Azure OpenAI assistant
    agent = AzureAssistantAgent(
        client=client,
        definition=definition,
    )

    # 4. Create a new thread for use with the assistant
    # If no thread is provided, a new thread will be
    # created and returned with the initial response
    thread = None

    try:
        for user_input in USER_INPUTS:
            print(f"# User: '{user_input}'")
            # 6. Invoke the agent for the current thread and print the response
            response = await agent.get_response(messages=user_input, thread=thread)
            print(f"# {response.name}: {response}")
            thread = response.thread

    finally:
        # 7. Clean up the resources
        await thread.delete() if thread else None
        await agent.client.beta.assistants.delete(assistant_id=agent.id)


if __name__ == "__main__":
    asyncio.run(main())

Input Pesan untuk Pemanggilan Agen

Implementasi sebelumnya hanya mengizinkan input pesan tunggal ke metode seperti get_response(...), invoke(...), dan invoke_stream(...). Kami sekarang telah memperbarui metode ini untuk mendukung beberapa messages (str | ChatMessageContent | list[str | ChatMessageContent]). Input pesan perlu diteruskan dengan messages argumen kata kunci, seperti agent.get_response(messages="user input") atau agent.invoke(messages="user input").

Metode pemanggilan agen memerlukan pembaruan sebagai berikut:

Cara Lama

response = await agent.get_response(message="some user input", thread=thread)

Cara Baru

response = await agent.get_response(messages=["some initial inputer", "other input"], thread=thread)

AzureAIAgent

Dalam Kernel Semantik Python 1.26.0+, pembuatan utas AzureAIAgent sekarang dikelola melalui objek AzureAIAgentThread, tidak langsung pada klien.

Cara Lama

thread = await client.agents.create_thread()

Cara Baru

from semantic_kernel.agents import AzureAIAgentThread

thread = AzureAIAgentThread(
    client: AIProjectClient,  # required
    messages: list[ThreadMessageOptions] | None = None,  # optional
    metadata: dict[str, str] | None = None,  # optional
    thread_id: str | None = None,  # optional
    tool_resources: "ToolResources | None" = None,  # optional
)

Jika thread_id tidak disediakan pada awalnya, maka utas baru akan dibuat dan dikembalikan dalam respons agen.

ChatCompletionAgent

ChatCompletionAgent telah diperbarui untuk menyederhanakan konfigurasi layanan, penanganan plugin, dan perilaku panggilan fungsi. Di bawah ini adalah perubahan utama yang harus Anda pertimbangkan saat bermigrasi.

1. Menentukan Layanan

Anda sekarang dapat menentukan layanan secara langsung sebagai bagian dari konstruktor agen:

Cara Baru

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

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="<name>",
    instructions="<instructions>",
)

Catatan: Jika baik kernel maupun layanan disediakan, layanan akan diutamakan jika mereka memiliki service_id atau ai_model_id yang sama. Jika tidak, apabila terpisah, maka layanan AI pertama yang terdaftar di kernel akan digunakan.

Jalan Lama (Masih Valid)

Sebelumnya, Anda akan terlebih dahulu menambahkan layanan ke kernel dan kemudian meneruskan kernel ke agen:

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

kernel = Kernel()
kernel.add_service(AzureChatCompletion())

agent = ChatCompletionAgent(
    kernel=kernel,
    name="<name>",
    instructions="<instructions>",
)

2. Menambahkan Plugin

Plugin sekarang dapat disediakan langsung melalui konstruktor:

Cara Baru

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

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="<name>",
    instructions="<instructions>",
    plugins=[SamplePlugin()],
)

Jalan Lama (Masih Valid)

Plugin sebelumnya harus ditambahkan ke kernel secara terpisah:

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

kernel = Kernel()
kernel.add_plugin(SamplePlugin())

agent = ChatCompletionAgent(
    kernel=kernel,
    name="<name>",
    instructions="<instructions>",
)

Catatan: Kedua pendekatan tersebut valid, tetapi menentukan plugin secara langsung menyederhanakan inisialisasi.

3. Memanggil Agen

Anda sekarang memiliki dua cara untuk memanggil agen. Metode baru secara langsung mengambil satu respons, sementara metode lama mendukung streaming.

Cara Baru (Tanpa Utas/Konteks Percakapan)

response = await agent.get_response(messages="user input")
# response is of type AgentResponseItem[ChatMessageContent]

Catatan: jika respons berikutnya tidak menggunakan utas yang dikembalikan, percakapan akan menggunakan utas baru dan dengan demikian tidak akan dilanjutkan dengan konteks sebelumnya.

Cara Baru (Respons Tunggal dengan Konteks)

thread = ChatHistoryAgentThread()

for user_input in ["First user input", "Second User Input"]:
    response = await agent.get_response(messages=user_input, thread=thread)
    # response is of type AgentResponseItem[ChatMessageContent]
    thread = response.thread

Cara Lama (Tidak Lagi Valid)

chat_history = ChatHistory()
chat_history.add_user_message("<user_input>")
response = agent.get_response(message="user input", chat_history=chat_history)

4. Mengontrol Pemanggilan Fungsi

Perilaku panggilan fungsi sekarang dapat dikontrol secara langsung saat menentukan layanan dalam konstruktor agen:

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="<name>",
    instructions="<instructions>",
    plugins=[MenuPlugin()],
    function_choice_behavior=FunctionChoiceBehavior.Auto(
        filters={"included_functions": ["get_specials", "get_item_price"]}
    ),
)

Catatan: Sebelumnya, konfigurasi panggilan fungsi memerlukan penyiapan terpisah pada kernel atau objek layanan. Jika pengaturan eksekusi menentukan service_id atau ai_model_id yang sama dengan konfigurasi layanan AI, perilaku panggilan fungsi yang ditentukan dalam pengaturan eksekusi (melalui KernelArguments) akan lebih diutamakan daripada perilaku pilihan fungsi yang ditetapkan dalam konstruktor.

Pembaruan ini meningkatkan kesederhanaan dan konfigurasi, membuat ChatCompletionAgent lebih mudah diintegrasikan dan dikelola.

OpenAIAssistantAgent

Perubahan AzureAssistantAgent dan OpenAIAssistantAgent mencakup pembaruan untuk membuat asisten, membuat utas, menangani plugin, menggunakan alat penerjemah kode, bekerja dengan alat pencarian file, dan menambahkan pesan obrolan ke utas.

Menyiapkan Sumber Daya

Cara Lama

Klien AsyncAzureOpenAI dibuat sebagai bagian dari proses pembuatan objek Agen.

agent = await AzureAssistantAgent.create(
    deployment_name="optional-deployment-name",
    api_key="optional-api-key",
    endpoint="optional-endpoint",
    ad_token="optional-ad-token",
    ad_token_provider=optional_callable,
    default_headers={"optional_header": "optional-header-value"},
    env_file_path="optional-env-file-path",
    env_file_encoding="optional-env-file-encoding",
    ...,
)

Cara Baru

Agen menyediakan metode statis untuk membuat klien yang diperlukan untuk sumber daya yang ditentukan, di mana argumen kata kunci tingkat metode lebih diutamakan daripada variabel dan nilai lingkungan dalam file .env yang ada.

client, model = AzureAssistantAgent.setup_resources(
    ad_token="optional-ad-token",
    ad_token_provider=optional_callable,
    api_key="optional-api-key",
    api_version="optional-api-version",
    base_url="optional-base-url",
    default_headers="optional-default-headers",
    deployment_name="optional-deployment-name",
    endpoint="optional-endpoint",
    env_file_path="optional-env-file-path",
    env_file_encoding="optional-env-file-encoding",
    token_scope="optional-token-scope",
)

1. Membuat Asisten

Cara Lama

agent = await AzureAssistantAgent.create(
    kernel=kernel,
    service_id=service_id,
    name=AGENT_NAME,
    instructions=AGENT_INSTRUCTIONS,
    enable_code_interpreter=True,
)

atau

agent = await OpenAIAssistantAgent.create(
    kernel=kernel,
    service_id=service_id,
    name=<name>,
    instructions=<instructions>,
    enable_code_interpreter=True,
)

Cara Baru

# Azure AssistantAgent 

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<name>",
)

# Create the agent using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

atau

# OpenAI Assistant Agent

# Create the client using OpenAI resources and configuration
client, model = OpenAIAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<name>",
)

# Create the agent using the client and the assistant definition
agent = OpenAIAssistantAgent(
    client=client,
    definition=definition,
)

2. Membuat Utas

Cara Lama

thread_id = await agent.create_thread()

Cara Baru

from semantic_kernel.agents AssistantAgentThread, AzureAssistantAgent

client, model = AzureAssistantAgent.setup_resources()

# You may create a thread based on an existing thread id
# thread = AssistantAgentThread(client=client, thread_id="existing-thread-id")
# Otherwise, if not specified, a thread will be created during the first invocation
# and returned as part of the response
thread = None

async for response in agent.invoke(messages="user input", thread=thread):
    # handle response
    print(response)
    thread = response.thread

3. Pengelolaan Plugin

Cara Lama

# Create the instance of the Kernel
kernel = Kernel()

# Add the sample plugin to the kernel
kernel.add_plugin(plugin=MenuPlugin(), plugin_name="menu")

agent = await AzureAssistantAgent.create(
    kernel=kernel, 
    name="<name>", 
    instructions="<instructions>"
)

Catatan: Masih mungkin untuk mengelola plugin melalui kernel. Jika Anda tidak menyediakan kernel, kernel secara otomatis dibuat pada waktu pembuatan agen dan plugin akan ditambahkan ke instans tersebut.

Cara Baru

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="<instructions>",
    name="<name>",
)

# Create the agent with plugins passed in as a list
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
    plugins=[MenuPlugin()],
)

Lihat implementasi sampel untuk detail selengkapnya.

4. Menggunakan Alat Penerjemah Kode

Cara Lama

csv_file_path = ...

agent = await AzureAssistantAgent.create(
    kernel=kernel,
    name="<name>",
    instructions="<instructions>",
    enable_code_interpreter=True,
    code_interpreter_filenames=[csv_file_path],
)

Cara Baru

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

csv_file_path = ...

# Load the CSV file as a FileObject
with open(csv_file_path, "rb") as file:
    file = await client.files.create(file=file, purpose="assistants")

# Get the code interpreter tool and resources
code_interpreter_tool, code_interpreter_tool_resource = AzureAssistantAgent.configure_code_interpreter_tool(file.id)

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    name="<name>",
    instructions="<instructions>.",
    tools=code_interpreter_tool,
    tool_resources=code_interpreter_tool_resource,
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

Lihat implementasi sampel untuk detail selengkapnya.

5. Bekerja dengan Alat Pencarian File

Cara Lama

pdf_file_path = ...

agent = await AzureAssistantAgent.create(
    kernel=kernel,
    service_id=service_id,
    name=AGENT_NAME,
    instructions=AGENT_INSTRUCTIONS,
    enable_file_search=True,
    vector_store_filenames=[pdf_file_path],
)

Cara Baru

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

pdf_file_path = ...

# Load the employees PDF file as a FileObject
with open(pdf_file_path, "rb") as file:
    file = await client.files.create(file=file, purpose="assistants")

# Create a vector store specifying the file ID to be used for file search
vector_store = await client.beta.vector_stores.create(
    name="step4_assistant_file_search",
    file_ids=[file.id],
)

file_search_tool, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool(vector_store.id)

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    instructions="Find answers to the user's questions in the provided file.",
    name="FileSearch",
    tools=file_search_tool,
    tool_resources=file_search_tool_resources,
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

Lihat implementasi sampel untuk detail selengkapnya.

6. Menambahkan Pesan Obrolan ke Utas

Cara Lama

await agent.add_chat_message(
    thread_id=thread_id, 
    message=ChatMessageContent(role=AuthorRole.USER, content=user_input)
)

Cara Baru

Catatan: Metode lama masih berfungsi jika Anda meneruskan ChatMessageContent, tetapi Anda sekarang juga dapat meneruskan string sederhana.

await agent.add_chat_message(
    thread_id=thread_id, 
    message=user_input,
)

7. Membersihkan Sumber Daya

Cara Lama

await agent.delete_file(file_id)
await agent.delete_thread(thread_id)
await agent.delete()

Cara Baru

await client.files.delete(file_id)
await thread.delete()
await client.beta.assistants.delete(agent.id)

Menangani Output Terstruktur

Cara Lama

Tidak Lagi Tersedia dengan Cara Lama

Cara Baru

# Define a Pydantic model that represents the structured output from the OpenAI service
class ResponseModel(BaseModel):
    response: str
    items: list[str]

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Create the assistant definition
definition = await client.beta.assistants.create(
    model=model,
    name="<name>",
    instructions="<instructions>",
    response_format=AzureAssistantAgent.configure_response_format(ResponseModel),
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
)

Lihat implementasi sampel untuk detail selengkapnya.

Panduan migrasi ini akan membantu Anda memperbarui kode Anda ke implementasi baru, memanfaatkan konfigurasi berbasis klien, dan fitur yang ditingkatkan.

Agen tidak tersedia di Java.

  • Last updated on