Bagikan melalui

Permukaan API Agen Umum Kernel Semantik

Agen Semantic Kernel menerapkan antarmuka terpadu untuk pemanggilan, memungkinkan kode bersama yang beroperasi dengan mulus di berbagai tipe agen. Desain ini memungkinkan Anda untuk beralih agen sesuai kebutuhan tanpa memodifikasi sebagian besar logika aplikasi Anda.

Memanggil agen

Antarmuka API Agen mendukung pemanggilan streaming dan non-streaming.

Panggilan Agen Non-Streaming

Semantic Kernel mendukung empat varian pemanggilan agen non-streaming yang memungkinkan penerusan pesan dengan cara yang berbeda. Salah satunya juga memungkinkan pemanggilan agen tanpa pesan. Ini berharga untuk skenario di mana instruksi agen sudah memiliki semua konteks yang diperlukan untuk memberikan respons yang berguna.

// Invoke without any parameters.
agent.InvokeAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer all user questions about France."),
    new(AuthorRole.User, "What is the capital of France?")
});

Penting

Memanggil agen tanpa meneruskan AgentThread ke metode InvokeAsync akan membuat utas baru dan mengembalikannya dalam respons.

Semantic Kernel mendukung dua metode pemanggilan agen non-streaming yang memungkinkan untuk meneruskan pesan dengan cara yang berbeda. Dimungkinkan juga untuk memanggil agen tanpa pesan. Ini berharga untuk skenario di mana instruksi agen sudah memiliki semua konteks yang diperlukan untuk memberikan respons yang berguna.

Petunjuk / Saran

Semua argumen yang diteruskan ke metode pemanggilan Agen mengharuskan pemanggil untuk meneruskannya sebagai argumen kata kunci, kecuali untuk argumen posisi pertama, messages. Anda dapat memanggil dengan argumen posisi atau kata kunci untuk messages. Misalnya, baik await agent.get_response("What is the capital of France?") dan await agent.get_response(messages="What is the capital of France?") didukung. Semua parameter lain harus diteruskan sebagai argumen kata kunci.

Menggunakan metode get_response()

# Invoke without any messages.
await agent.get_response()

# Invoke with a string that will be used as a User message.
await agent.get_response(messages="What is the capital of France?")

# Invoke with a ChatMessageContent object.
await agent.get_response(messages=ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"))

# Invoke with multiple ChatMessageContent objects.
await agent.get_response(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
)

Menggunakan metode invoke()

# Invoke without any messages.
async for response in agent.invoke():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Penting

Memanggil agen tanpa meneruskan AgentThread ke metode get_response() atau invoke() akan membuat utas baru dan mengembalikan utas baru melalui respons.

Semantic Kernel mendukung tiga kelebihan beban pemanggilan agen non-streaming yang memungkinkan pengiriman pesan dengan berbagai cara. Salah satunya juga memungkinkan pemanggilan agen tanpa pesan. Ini berharga untuk skenario di mana instruksi agen sudah memiliki semua konteks yang diperlukan untuk memberikan respons yang berguna.

// Invoke without any parameters.
agent.invokeAsync(null);

// Invoke with a string that will be used as a User message.
agent.invokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.invokeAsync(new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.invokeAsync(List.of(
    new ChatMessageContent<>(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
    new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?")
));

Penting

Memanggil agen tanpa meneruskan AgentThread ke metode invokeAsync akan membuat utas baru dan mengembalikannya dalam respons.

Pemanggilan Agen Streaming

Semantic Kernel menyediakan empat variasi cara pemanggilan agen streaming yang memungkinkan penerusan pesan dengan cara yang berbeda. Salah satunya juga memungkinkan pemanggilan agen tanpa pesan. Ini berharga untuk skenario di mana instruksi agen sudah memiliki semua konteks yang diperlukan untuk memberikan respons yang berguna.

// Invoke without any parameters.
agent.InvokeStreamingAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeStreamingAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeStreamingAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeStreamingAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer any questions about capital cities."),
    new(AuthorRole.User, "What is the capital of France?")
});

Penting

Memanggil agen tanpa meneruskan AgentThread ke metode InvokeStreamingAsync akan membuat utas baru dan mengembalikannya dalam respons.

Semantic Kernel mendukung satu metode pemanggilan agen streaming yang memungkinkan untuk meneruskan pesan dengan cara yang berbeda. Dimungkinkan juga untuk mengaktifkan aliran agen tanpa pesan. Ini berharga untuk skenario di mana instruksi agen sudah memiliki semua konteks yang diperlukan untuk memberikan respons yang berguna.

# Invoke without any messages.
async for response in agent.invoke_stream():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke_stream("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke_stream(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke_stream(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Penting

Memanggil agen tanpa meneruskan AgentThread ke metode invoke_stream() akan membuat utas baru dan mengembalikannya dalam respons.

Fitur saat ini tidak tersedia di Java.

Memanggil dengan AgentThread

Semua overload metode memungkinkan menggunakan parameter AgentThread. Ini berguna untuk skenario di mana Anda memiliki percakapan yang sudah ada dengan agen yang ingin Anda lanjutkan.

// Invoke with an existing AgentThread.
agent.InvokeAsync("What is the capital of France?", existingAgentThread);

Semua metode pemanggilan juga mengembalikan AgentThread yang aktif sebagai bagian dari respons pemanggilan.

  1. Jika Anda meneruskan AgentThread ke metode pemanggilan, AgentThread yang dikembalikan akan sama dengan yang diteruskan.
  2. Jika Anda tidak meneruskan AgentThread ke metode pemanggilan, nilai balik AgentThread akan menjadi AgentThread baru.

Hasil yang dikembalikan AgentThread tersedia pada item respons individual dari metode panggilan bersama dengan pesan respons.

var result = await agent.InvokeAsync("What is the capital of France?").FirstAsync();
var newThread = result.Thread;
var resultMessage = result.Message;

Petunjuk / Saran

Untuk informasi selengkapnya tentang utas agen, lihat bagian arsitektur Alur Agen.

Semua argumen kata kunci metode pemanggilan memungkinkan pengiriman parameter AgentThread. Ini berguna untuk skenario di mana Anda memiliki percakapan yang sudah ada dengan agen yang ingin Anda lanjutkan.

# Invoke with an existing AgentThread.
agent.get_response("What is the capital of France?", thread=existing_agent_thread)

Semua metode pemanggilan juga mengembalikan AgentThread yang aktif sebagai bagian dari respons pemanggilan.

  1. Jika Anda meneruskan AgentThread ke metode pemanggilan, AgentThread yang dikembalikan akan sama dengan yang diteruskan.
  2. Jika Anda tidak meneruskan AgentThread ke metode pemanggilan, nilai balik AgentThread akan menjadi AgentThread baru.

Hasil yang dikembalikan AgentThread tersedia pada item respons individual dari metode panggilan bersama dengan pesan respons.

response = await agent.get_response("What is the capital of France?")
new_thread = response.thread
response_message = response.message

Petunjuk / Saran

Untuk informasi selengkapnya tentang utas agen, lihat bagian arsitektur Alur Agen.

Dua metode pemanggilan kelebihan beban memungkinkan melewati AgentThread parameter. Ini berguna untuk skenario di mana Anda memiliki percakapan yang sudah ada dengan agen yang ingin Anda lanjutkan.

// Invoke with an existing AgentThread.
agent.invokeAsync("What is the capital of France?", existingAgentThread);

Metode pemanggilan ini juga mengembalikan AgentThread yang aktif sebagai bagian dari respons pemanggilan.

  1. Jika Anda meneruskan AgentThread ke metode pemanggil, AgentThread yang dikembalikan akan menjadi instans baru dengan pesan sebelumnya dan pesan baru.
  2. Jika Anda tidak meneruskan AgentThread ke metode pemanggilan, nilai balik AgentThread akan menjadi AgentThread baru.

Hasil yang dikembalikan AgentThread tersedia pada item respons individual dari metode panggilan bersama dengan pesan respons.

var result = agent.invokeAsync("What is the capital of France?").block().get(0);
var newThread = result.getThread();
var resultMessage = result.getMessage();

Petunjuk / Saran

Untuk informasi selengkapnya tentang utas agen, lihat bagian arsitektur Alur Agen.

Memanggil dengan Opsi

Semua overload metode memungkinkan menggunakan parameter AgentInvokeOptions. Kelas opsi ini memungkinkan penyediaan pengaturan opsional apa pun.

// Invoke with additional instructions via options.
agent.InvokeAsync("What is the capital of France?", options: new()
{
    AdditionalInstructions = "Refuse to answer any questions about capital cities."
});

Berikut adalah daftar opsi yang didukung.

Pilihan Properti Deskripsi
Kernel (inti sistem operasi) Ambil alih kernel default yang digunakan oleh agen untuk pemanggilan ini.
KernelArguments Ambil alih argumen kernel default yang digunakan oleh agen untuk pemanggilan ini.
Instruksi Tambahan Berikan instruksi apa pun selain set instruksi agen asli, yang hanya berlaku untuk pemanggilan ini.
OnIntermediateMessage Panggilan balik yang dapat menerima semua pesan yang sepenuhnya terbentuk yang diproduksi secara internal ke Agen, termasuk panggilan fungsi dan pesan pemanggilan fungsi. Ini juga dapat digunakan untuk menerima pesan lengkap selama pemanggilan streaming.

Memanggil dengan Opsi

Satu metode pemanggilan kelebihan beban memungkinkan melewati AgentInvokeOptions parameter. Kelas opsi ini memungkinkan penyediaan pengaturan opsional apa pun.

// Invoke with additional instructions via options.
agent.invokeAsync("What is the capital of France?",
    null, // null AgentThread
    AgentInvokeOptions.builder()
        .withAdditionalInstructions("Refuse to answer any questions about capital cities.")
        .build()
);

Berikut adalah daftar opsi yang didukung.

Pilihan Properti Deskripsi
Kernel (inti sistem operasi) Ambil alih kernel default yang digunakan oleh agen untuk pemanggilan ini.
KernelArguments Ambil alih argumen kernel default yang digunakan oleh agen untuk pemanggilan ini.
Instruksi Tambahan Berikan instruksi apa pun selain set instruksi agen asli, yang hanya berlaku untuk pemanggilan ini.
KonteksPemanggilan Ambil alih konteks pemanggilan default yang digunakan agen untuk pemanggilan ini.

Mengelola instansi AgentThread

Anda dapat membuat AgentThread instans secara manual dan meneruskannya ke agen saat dipanggil, atau Anda dapat membiarkan agen membuat AgentThread instans untuk Anda secara otomatis pada pemanggilan. Objek AgentThread mewakili proses thread dalam semua keadaannya, termasuk: belum dibuat, aktif, dan dihapus.

AgentThread jenis yang memiliki implementasi sisi server akan dibuat pada penggunaan pertama dan tidak perlu dibuat secara manual. Namun, Anda dapat menghapus utas menggunakan kelas AgentThread.

// Delete a thread.
await agentThread.DeleteAsync();

# Delete a thread
await agent_thread.delete()

// Delete a thread.
agentThread.deleteAsync().block();

Petunjuk / Saran

Untuk informasi selengkapnya tentang utas agen, lihat bagian arsitektur Alur Agen.

Langkah selanjutnya

Mengonfigurasi agen dengan plugin

Menjelajahi Agen Penyelesaian Percakapan

  • Last updated on