Bagikan melalui

Menjelajahi Kernel Semantik OpenAIAssistantAgent

Penting

Fitur agen tunggal, seperti OpenAIAssistantAgent, berada dalam tahap kandidat rilis. Fitur-fitur ini hampir lengkap dan umumnya stabil, meskipun mungkin mengalami penyempurnaan atau pengoptimalan kecil sebelum mencapai ketersediaan umum penuh.

Petunjuk / Saran

Dokumentasi API terperinci yang terkait dengan diskusi ini tersedia di:

Petunjuk / Saran

Dokumentasi API terperinci yang terkait dengan diskusi ini tersedia di:

Fitur saat ini tidak tersedia di Java.

Apa itu Asisten?

OpenAI Assistants API adalah antarmuka khusus yang dirancang untuk kemampuan AI yang lebih canggih dan interaktif, memungkinkan pengembang untuk membuat agen berorientasi tugas yang dipersonalisasi dan multi-langkah. Tidak seperti API Penyelesaian Obrolan, yang berfokus pada pertukaran percakapan sederhana, Assistant API memungkinkan interaksi dinamis berbasis tujuan dengan fitur tambahan seperti penerjemah kode dan pencarian file.

Menyiapkan lingkungan pengembangan Anda

Untuk melanjutkan pengembangan OpenAIAssistantAgent, konfigurasikan lingkungan pengembangan Anda dengan paket yang sesuai.

Tambahkan paket Microsoft.SemanticKernel.Agents.OpenAI ke proyek Anda:

dotnet add package Microsoft.SemanticKernel.Agents.OpenAI --prerelease

Anda mungkin juga ingin menyertakan paket Azure.Identity:

dotnet add package Azure.Identity

Instal paket semantic-kernel:

pip install semantic-kernel

Fitur saat ini tidak tersedia di Java.

Membuat OpenAIAssistantAgent

Membuat OpenAIAssistant memerlukan pembuatan klien terlebih dahulu untuk dapat berkomunikasi dengan layanan jarak jauh.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
Assistant assistant =
    await client.CreateAssistantAsync(
        "<model name>",
        "<agent name>",
        instructions: "<agent instructions>");
OpenAIAssistantAgent agent = new(assistant, client);

from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent, OpenAIAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings, OpenAISettings

# Set up the client and model using Azure OpenAI Resources
client = AzureAssistantAgent.create_client()

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

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

# or

# Set up the client and model using OpenAI Resources
client = OpenAIAssistantAgent.create_client()

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

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

Fitur saat ini tidak tersedia di Java.

Mengambil data OpenAIAssistantAgent

Setelah dibuat, pengidentifikasi asisten dapat diakses melalui pengidentifikasi tersebut. Pengidentifikasi ini dapat digunakan untuk membuat OpenAIAssistantAgent berdasarkan definisi asisten yang sudah ada.

Untuk .NET, pengidentifikasi agen diekspos sebagai string melalui properti yang ditentukan oleh agen mana pun.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
Assistant assistant = await client.GetAssistantAsync("<assistant id>");
OpenAIAssistantAgent agent = new(assistant, client);

# Using Azure OpenAI Resources

# Create the client using Azure OpenAI resources and configuration
client = AzureAssistantAgent.create_client()

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

# Store the assistant ID
assistant_id = definition.id

# Retrieve the assistant definition from the server based on the assistant ID
new_asst_definition = await client.beta.assistants.retrieve(assistant_id)

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

Fitur saat ini tidak tersedia di Java.

Menggunakan OpenAIAssistantAgent

Seperti semua aspek Assistant API, percakapan disimpan dari jarak jauh. Setiap percakapan disebut utas dan diidentifikasi oleh pengidentifikasi string yang unik. Interaksi dengan OpenAIAssistantAgent Anda terkait dengan pengidentifikasi utas khusus ini. Detail utas Assistant API diabstraksikan melalui kelas OpenAIAssistantAgentThread, yang merupakan implementasi dari AgentThread.

OpenAIAssistantAgent saat ini hanya mendukung utas jenis OpenAIAssistantAgentThread.

Anda dapat memanggil OpenAIAssistantAgent tanpa menentukan AgentThread, untuk memulai utas baru dan AgentThread baru akan dikembalikan sebagai bagian dari respons.


// Define agent
OpenAIAssistantAgent agent = ...;
AgentThread? agentThread = null;

// Generate the agent response(s)
await foreach (AgentResponseItem<ChatMessageContent> response in agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "<user input>")))
{
  // Process agent response(s)...
  agentThread = response.Thread;
}

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

Anda juga dapat memanggil OpenAIAssistantAgent dengan AgentThread yang Anda buat.

// Define agent
OpenAIAssistantAgent agent = ...;

// Create a thread with some custom metadata.
AgentThread agentThread = new OpenAIAssistantAgentThread(client, metadata: myMetadata);

// Generate the agent response(s)
await foreach (ChatMessageContent response in agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "<user input>"), agentThread))
{
  // Process agent response(s)...
}

// Delete the thread when it is no longer needed
await agentThread.DeleteAsync();

Anda juga dapat membuat OpenAIAssistantAgentThread yang melanjutkan percakapan sebelumnya dengan id.

// Create a thread with an existing thread id.
AgentThread agentThread = new OpenAIAssistantAgentThread(client, "existing-thread-id");

from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent

# Define agent
openai_agent = await ...

# Create a thread for the agent conversation
thread: AssistantAgentThread = None

# Generate the agent response(s)
async for response in agent.invoke(messages="user input", thread=thread):
  # process agent response(s)...
  thread = response.thread

# Delete the thread when it is no longer needed
await thread.delete() if thread else None

Fitur saat ini tidak tersedia di Java.

Menghapus sebuah OpenAIAssistantAgent

Karena definisi asisten disimpan dari jarak jauh, definisi akan bertahan jika tidak dihapus.
Menghapus definisi asisten dapat dilakukan langsung dengan klien.

Catatan: Mencoba menggunakan instans agen setelah dihapus akan menghasilkan pengecualian layanan.

Untuk .NET, pengidentifikasi agen diekspos sebagai string melalui properti Agent.Id yang ditentukan oleh agen apa pun.

AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient();
await client.DeleteAssistantAsync("<assistant id>");

await client.beta.assistants.delete(agent.id)

Fitur saat ini tidak tersedia di Java.

Menangani Pesan Perantara dengan OpenAIAssistantAgent

Semantic Kernel OpenAIAssistantAgent dirancang untuk memanggil sebuah agen yang memenuhi kueri atau pertanyaan pengguna. Selama pemanggilan, agen dapat menjalankan alat untuk mendapatkan jawaban akhir. Untuk mengakses pesan perantara yang dihasilkan selama proses ini, penelepon dapat menyediakan fungsi panggilan balik yang menangani instans FunctionCallContent atau FunctionResultContent.

Dokumentasi callback untuk OpenAIAssistantAgent akan segera tersedia.

Mengonfigurasi on_intermediate_message panggilan balik dalam agent.invoke(...) atau agent.invoke_stream(...) memungkinkan pemanggil untuk menerima pesan perantara yang dihasilkan selama proses merumuskan respons akhir agen.

import asyncio
from typing import Annotated

from semantic_kernel.agents import AssistantAgentThread, AzureAssistantAgent
from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings
from semantic_kernel.contents import AuthorRole, ChatMessageContent, FunctionCallContent, FunctionResultContent
from semantic_kernel.functions import kernel_function


# Define a sample plugin for the sample
class MenuPlugin:
    """A sample Menu Plugin used for the concept sample."""

    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"


# This callback function will be called for each intermediate message,
# which will allow one to handle FunctionCallContent and FunctionResultContent.
# If the callback is not provided, the agent will return the final response
# with no intermediate tool call steps.
async def handle_intermediate_steps(message: ChatMessageContent) -> None:
    for item in message.items or []:
        if isinstance(item, FunctionResultContent):
            print(f"Function Result:> {item.result} for function: {item.name}")
        elif isinstance(item, FunctionCallContent):
            print(f"Function Call:> {item.name} with arguments: {item.arguments}")
        else:
            print(f"{item}")


async def main():
    # Create the client using Azure OpenAI resources and configuration
    client = AzureAssistantAgent.create_client()

    # Define the assistant definition
    definition = await client.beta.assistants.create(
        model=AzureOpenAISettings().chat_deployment_name,
        name="Host",
        instructions="Answer questions about the menu.",
    )

    # Create the AzureAssistantAgent instance using the client and the assistant definition and the defined plugin
    agent = AzureAssistantAgent(
        client=client,
        definition=definition,
        plugins=[MenuPlugin()],
    )

    # 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: AssistantAgentThread = None

    user_inputs = [
        "Hello",
        "What is the special soup?",
        "What is the special drink?",
        "How much is that?",
        "Thank you",
    ]

    try:
        for user_input in user_inputs:
            print(f"# {AuthorRole.USER}: '{user_input}'")
            async for response in agent.invoke(
                messages=user_input,
                thread=thread,
                on_intermediate_message=handle_intermediate_steps,
            ):
                print(f"# {response.role}: {response}")
                thread = response.thread
    finally:
        await thread.delete() if thread else None
        await client.beta.assistants.delete(assistant_id=agent.id)


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

Berikut ini menunjukkan sampel output dari proses pemanggilan agen:

AuthorRole.USER: 'Hello'
AuthorRole.ASSISTANT: Hello! How can I assist you today?
AuthorRole.USER: 'What is the special soup?'
Function Call:> MenuPlugin-get_specials with arguments: {}
Function Result:> 
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        for function: MenuPlugin-get_specials
AuthorRole.ASSISTANT: The special soup is Clam Chowder. Would you like to know more about the specials or 
    anything else?
AuthorRole.USER: 'What is the special drink?'
AuthorRole.ASSISTANT: The special drink is Chai Tea. If you have any more questions, feel free to ask!
AuthorRole.USER: 'How much is that?'
Function Call:> MenuPlugin-get_item_price with arguments: {"menu_item":"Chai Tea"}
Function Result:> $9.99 for function: MenuPlugin-get_item_price
AuthorRole.ASSISTANT: The Chai Tea is priced at $9.99. If there's anything else you'd like to know, 
    just let me know!
AuthorRole.USER: 'Thank you'
AuthorRole.ASSISTANT: You're welcome! If you have any more questions or need further assistance, feel free to 
    ask. Enjoy your day!

Fitur saat ini tidak tersedia di Java.

Spesifikasi Deklaratif

Dokumentasi tentang menggunakan spesifikasi deklaratif akan segera hadir.

Penting

Fitur ini dalam tahap eksperimental. Fitur pada tahap ini sedang dalam pengembangan dan dapat berubah sebelum maju ke tahap pratinjau atau kandidat rilis.

OpenAIAssistantAgent mendukung instansiasi dari spesifikasi deklaratif YAML. Pendekatan deklaratif memungkinkan Anda menentukan properti agen, instruksi, konfigurasi model, alat, dan opsi lainnya dalam satu dokumen yang dapat diaudit. Hal ini membuat komposisi agen portabel dan mudah dikelola di seluruh lingkungan.

Nota

Setiap alat, fungsi, atau plugin yang tercantum dalam YAML deklaratif harus tersedia untuk agen pada waktu konstruksi. Untuk plugin berbasis kernel, ini berarti plugin harus terdaftar di Kernel. Untuk alat bawaan seperti Penerjemah Kode atau Pencarian File, konfigurasi dan kredensial yang benar harus disediakan. Pemuat agen tidak akan mengembangkan fungsi dari nol. Jika komponen yang diperlukan hilang, pembuatan agen akan gagal.

Cara Menggunakan Spesifikasi Deklaratif

Daripada menghitung setiap kemungkinan konfigurasi YAML, bagian ini menguraikan prinsip-prinsip utama dan menyediakan tautan ke sampel konsep yang menunjukkan kode lengkap untuk setiap jenis alat. Merujuklah pada contoh-contoh konsep ini untuk implementasi menyeluruh dari OpenAIAssistantAgent dengan spesifikasi secara deklaratif.

AzureAssistantAgent Sampel:

OpenAIAssistantAgent Sampel:

Contoh: Membuat AzureAIAgent dari YAML

Spesifikasi deklaratif YAML minimal mungkin terlihat seperti berikut:

type: openai_assistant
name: Host
instructions: Respond politely to the user's questions.
model:
  id: ${OpenAI:ChatModelId}
tools:
  - id: MenuPlugin.get_specials
    type: function
  - id: MenuPlugin.get_item_price
    type: function

Untuk detail tentang cara menyambungkan agen, lihat sampel kode lengkap di atas.

Poin Penting

  • Spesifikasi deklaratif memungkinkan menentukan struktur, alat, dan perilaku agen dalam YAML.
  • Semua alat dan plugin yang direferensikan harus terdaftar atau dapat diakses pada runtime.
  • Alat bawaan seperti Bing, Pencarian File, dan Penerjemah Kode memerlukan konfigurasi dan kredensial yang tepat (seringkali melalui variabel lingkungan atau argumen eksplisit).
  • Untuk contoh komprehensif, lihat tautan sampel yang disediakan yang menunjukkan skenario praktis, termasuk pendaftaran plugin, konfigurasi identitas Azure, dan penggunaan alat tingkat lanjut.

Fitur ini tidak tersedia.

Panduan Praktis

Untuk contoh lengkap untuk OpenAIAssistantAgent, lihat:

Langkah Selanjutnya

Menjelajahi Agen Respons OpenAI

  • Last updated on