Orkestrasi Handoff

Penting

Fitur Agent Orchestration dalam Kerangka Kerja Agen sedang dalam tahap eksperimental. Mereka sedang dalam pengembangan aktif dan dapat berubah secara signifikan sebelum maju ke tahap pratinjau atau tahap kandidat rilis.

Orkestrasi handoff memungkinkan agen untuk mentransfer kontrol antara satu sama lain berdasarkan konteks atau atas permintaan pengguna. Setiap agen dapat "menyerahkan" percakapan ke agen lain dengan keahlian yang sesuai, memastikan bahwa agen yang tepat menangani setiap bagian tugas. Ini sangat berguna dalam dukungan pelanggan, sistem ahli, atau skenario apa pun yang memerlukan delegasi dinamis.

Untuk mempelajari lebih lanjut tentang pola tersebut, seperti kapan harus menggunakan pola atau kapan harus menghindari pola dalam beban kerja, lihat Handoff Orchestration.

Kasus penggunaan umum

Agen dukungan pelanggan menangani pertanyaan umum, lalu menyerahkan ke agen ahli teknis untuk pemecahan masalah, atau ke agen penagihan jika diperlukan:

Apa yang akan Anda Pelajari

• Cara menentukan agen dan hubungan serah-tangan mereka
• Cara menyiapkan pengaturan penyerahan tugas untuk perutean agen yang dinamis
• Cara melibatkan manusia dalam perulangan percakapan

Tentukan Agen Khusus

Setiap agen bertanggung jawab atas area tertentu. Dalam contoh ini, kami menentukan agen triase, agen pengembalian dana, agen status pesanan, dan agen pengembalian pesanan. Beberapa agen menggunakan plugin untuk menangani tugas tertentu.

Petunjuk / Saran

digunakan ChatCompletionAgent di sini, tetapi Anda dapat menggunakan jenis agen apa pun.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.Agents.Orchestration;
using Microsoft.SemanticKernel.Agents.Orchestration.Handoff;
using Microsoft.SemanticKernel.Agents.Runtime.InProcess;
using Microsoft.SemanticKernel.ChatCompletion;

// Plugin implementations
public sealed class OrderStatusPlugin {
    [KernelFunction]
    public string CheckOrderStatus(string orderId) => $"Order {orderId} is shipped and will arrive in 2-3 days.";
}
public sealed class OrderReturnPlugin {
    [KernelFunction]
    public string ProcessReturn(string orderId, string reason) => $"Return for order {orderId} has been processed successfully.";
}
public sealed class OrderRefundPlugin {
    [KernelFunction]
    public string ProcessReturn(string orderId, string reason) => $"Refund for order {orderId} has been processed successfully.";
}

// Helper function to create a kernel with chat completion
public static Kernel CreateKernelWithChatCompletion(...)
{
    ...
}

ChatCompletionAgent triageAgent = new ChatCompletionAgent {
    Name = "TriageAgent",
    Description = "Handle customer requests.",
    Instructions = "A customer support agent that triages issues.",
    Kernel = CreateKernelWithChatCompletion(...),
};

ChatCompletionAgent statusAgent = new ChatCompletionAgent {
    Name = "OrderStatusAgent",
    Description = "A customer support agent that checks order status.",
    Instructions = "Handle order status requests.",
    Kernel = CreateKernelWithChatCompletion(...),
};
statusAgent.Kernel.Plugins.Add(KernelPluginFactory.CreateFromObject(new OrderStatusPlugin()));

ChatCompletionAgent returnAgent = new ChatCompletionAgent {
    Name = "OrderReturnAgent",
    Description = "A customer support agent that handles order returns.",
    Instructions = "Handle order return requests.",
    Kernel = CreateKernelWithChatCompletion(...),
};
returnAgent.Kernel.Plugins.Add(KernelPluginFactory.CreateFromObject(new OrderReturnPlugin()));

ChatCompletionAgent refundAgent = new ChatCompletionAgent {
    Name = "OrderRefundAgent",
    Description = "A customer support agent that handles order refund.",
    Instructions = "Handle order refund requests.",
    Kernel = CreateKernelWithChatCompletion(...),
};
refundAgent.Kernel.Plugins.Add(KernelPluginFactory.CreateFromObject(new OrderRefundPlugin()));

Menyiapkan Koneksi Handoff

Gunakan OrchestrationHandoffs untuk menentukan agen mana yang dapat menyerahkan ke mana, dan dalam keadaan apa.

var handoffs = OrchestrationHandoffs
    .StartWith(triageAgent)
    .Add(triageAgent, statusAgent, returnAgent, refundAgent)
    .Add(statusAgent, triageAgent, "Transfer to this agent if the issue is not status related")
    .Add(returnAgent, triageAgent, "Transfer to this agent if the issue is not return related")
    .Add(refundAgent, triageAgent, "Transfer to this agent if the issue is not refund related");

Amati Respons Agen

Anda dapat membuat panggilan balik untuk mengambil respons agen saat percakapan berlangsung melalui ResponseCallback properti .

ChatHistory history = [];

ValueTask responseCallback(ChatMessageContent response)
{
    history.Add(response);
    return ValueTask.CompletedTask;
}

Keterlibatan Manusia dalam Proses

Fitur kunci dari pengaturan alih tugas adalah kemampuan bagi manusia untuk ikut serta dalam percakapan. Ini dicapai dengan menyediakan InteractiveCallback, yang dipanggil setiap kali agen membutuhkan input dari pengguna. Dalam aplikasi nyata, ini akan meminta masukan kepada pengguna; dalam sampel, Anda dapat menggunakan antrean respons.

// Simulate user input with a queue
Queue<string> responses = new();
responses.Enqueue("I'd like to track the status of my order");
responses.Enqueue("My order ID is 123");
responses.Enqueue("I want to return another order of mine");
responses.Enqueue("Order ID 321");
responses.Enqueue("Broken item");
responses.Enqueue("No, bye");

ValueTask<ChatMessageContent> interactiveCallback()
{
    string input = responses.Dequeue();
    Console.WriteLine($"\n# INPUT: {input}\n");
    return ValueTask.FromResult(new ChatMessageContent(AuthorRole.User, input));
}

Menyiapkan Orkestrasi Pengalihan

Buat objek HandoffOrchestration, masukkan agen, hubungan serah terima, dan panggilan balik.

HandoffOrchestration orchestration = new HandoffOrchestration(
    handoffs,
    triageAgent,
    statusAgent,
    returnAgent,
    refundAgent)
{
    InteractiveCallback = interactiveCallback,
    ResponseCallback = responseCallback,
};

Mulai Runtime

Runtime diperlukan untuk mengelola eksekusi agen. Di sini, kita menggunakan InProcessRuntime dan memulainya sebelum memanggil orkestrasi.

InProcessRuntime runtime = new InProcessRuntime();
await runtime.StartAsync();

Memanggil Orkestrasi

Panggil orkestrasi dengan tugas awal Anda (misalnya, "Saya adalah pelanggan yang membutuhkan bantuan dengan pesanan saya"). Agen akan merutekan percakapan sesuai kebutuhan, yang melibatkan manusia ketika diperlukan.

string task = "I am a customer that needs help with my orders";
var result = await orchestration.InvokeAsync(task, runtime);

Kumpulkan Hasil

Tunggu hingga orkestrasi selesai dan ambil output akhir.

string output = await result.GetValueAsync(TimeSpan.FromSeconds(300));
Console.WriteLine($"\n# RESULT: {output}");
Console.WriteLine("\n\nORCHESTRATION HISTORY");
foreach (ChatMessageContent message in history)
{
    // Print each message
    Console.WriteLine($"# {message.Role} - {message.AuthorName}: {message.Content}");
}

Opsional: Hentikan Runtime

Setelah pemrosesan selesai, hentikan runtime untuk membersihkan sumber daya.

await runtime.RunUntilIdleAsync();

Sampel Output

# RESULT: Handled order return for order ID 321 due to a broken item, and successfully processed the return.

ORCHESTRATION HISTORY

# Assistant - TriageAgent: Could you please specify what kind of help you need with your orders? Are you looking to check the order status, return an item, or request a refund?

# Assistant - OrderStatusAgent: Could you please tell me your order ID?

# Assistant - OrderStatusAgent: Your order with ID 123 has been shipped and will arrive in 2-3 days. Anything else I can assist you with?

# Assistant - OrderReturnAgent: I can help you with that. Could you please provide the order ID and the reason you'd like to return it?

# Assistant - OrderReturnAgent: Please provide the reason for returning the order with ID 321.

# Assistant - OrderReturnAgent: The return for your order with ID 321 has been successfully processed due to the broken item. Anything else I can assist you with?

Petunjuk / Saran

Kode sampel lengkap tersedia di sini

Tentukan Agen Khusus

Setiap agen bertanggung jawab atas area tertentu. Contohnya:

• TriageAgent: Menangani permintaan pelanggan awal dan memutuskan spesialis mana yang akan dilibatkan.
• RefundAgent: Menangani permintaan pengembalian dana.
• OrderStatusAgent: Memeriksa status pesanan.
• OrderReturnAgent: Menangani pengembalian pesanan.

Perangkat tambah

Pertama, kita perlu menentukan plugin yang akan digunakan dalam agen. Plugin ini akan berisi logika untuk menangani tugas tertentu.

from semantic_kernel.functions import kernel_function

class OrderStatusPlugin:
    @kernel_function
    def check_order_status(self, order_id: str) -> str:
        """Check the status of an order."""
        # Simulate checking the order status
        return f"Order {order_id} is shipped and will arrive in 2-3 days."


class OrderRefundPlugin:
    @kernel_function
    def process_refund(self, order_id: str, reason: str) -> str:
        """Process a refund for an order."""
        # Simulate processing a refund
        print(f"Processing refund for order {order_id} due to: {reason}")
        return f"Refund for order {order_id} has been processed successfully."


class OrderReturnPlugin:
    @kernel_function
    def process_return(self, order_id: str, reason: str) -> str:
        """Process a return for an order."""
        # Simulate processing a return
        print(f"Processing return for order {order_id} due to: {reason}")
        return f"Return for order {order_id} has been processed successfully."

Agen

Selanjutnya, kami menentukan agen yang akan menggunakan plugin ini.

Petunjuk / Saran

ChatCompletionAgent digunakan di sini bersama Azure OpenAI; namun, Anda dapat menggunakan jenis agen atau layanan model apa pun.

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

support_agent = ChatCompletionAgent(
    name="TriageAgent",
    description="A customer support agent that triages issues.",
    instructions="Handle customer requests.",
    service=OpenAIChatCompletion(),
)

refund_agent = ChatCompletionAgent(
    name="RefundAgent",
    description="A customer support agent that handles refunds.",
    instructions="Handle refund requests.",
    service=OpenAIChatCompletion(),
    plugins=[OrderRefundPlugin()],
)

order_status_agent = ChatCompletionAgent(
    name="OrderStatusAgent",
    description="A customer support agent that checks order status.",
    instructions="Handle order status requests.",
    service=OpenAIChatCompletion(),
    plugins=[OrderStatusPlugin()],
)

order_return_agent = ChatCompletionAgent(
    name="OrderReturnAgent",
    description="A customer support agent that handles order returns.",
    instructions="Handle order return requests.",
    service=OpenAIChatCompletion(),
    plugins=[OrderReturnPlugin()],
)

Tentukan Hubungan Handoff

Gunakan OrchestrationHandoffs untuk menentukan agen mana yang dapat menyerahkan ke mana, dan dalam keadaan apa.

from semantic_kernel.agents import OrchestrationHandoffs

handoffs = (
    OrchestrationHandoffs()
    .add_many(    # Use add_many to add multiple handoffs to the same source agent at once
        source_agent=support_agent.name,
        target_agents={
            refund_agent.name: "Transfer to this agent if the issue is refund related",
            order_status_agent.name: "Transfer to this agent if the issue is order status related",
            order_return_agent.name: "Transfer to this agent if the issue is order return related",
        },
    )
    .add(    # Use add to add a single handoff
        source_agent=refund_agent.name,
        target_agent=support_agent.name,
        description="Transfer to this agent if the issue is not refund related",
    )
    .add(
        source_agent=order_status_agent.name,
        target_agent=support_agent.name,
        description="Transfer to this agent if the issue is not order status related",
    )
    .add(
        source_agent=order_return_agent.name,
        target_agent=support_agent.name,
        description="Transfer to this agent if the issue is not order return related",
    )
)

Amati Respons Agen

Anda dapat menentukan panggilan balik untuk mencetak pesan setiap agen saat percakapan berlangsung.

from semantic_kernel.contents import ChatMessageContent

def agent_response_callback(message: ChatMessageContent) -> None:
    print(f"{message.name}: {message.content}")

Keterlibatan Manusia dalam Proses

Fitur kunci dari pengaturan alih tugas adalah kemampuan bagi manusia untuk ikut serta dalam percakapan. Ini dicapai dengan menyediakan human_response_function panggilan balik, yang dipanggil setiap kali agen membutuhkan input dari pengguna.

from semantic_kernel.contents import AuthorRole, ChatMessageContent

def human_response_function() -> ChatMessageContent:
    user_input = input("User: ")
    return ChatMessageContent(role=AuthorRole.USER, content=user_input)

Menyiapkan Orkestrasi Pengalihan

Buat objek HandoffOrchestration, masukkan agen, hubungan serah terima, dan panggilan balik.

from semantic_kernel.agents import HandoffOrchestration

handoff_orchestration = HandoffOrchestration(
    members=[
        support_agent,
        refund_agent,
        order_status_agent,
        order_return_agent,
    ],
    handoffs=handoffs,
    agent_response_callback=agent_response_callback,
    human_response_function=human_response_function,
)

Mulai Runtime

Mulai runtime untuk mengelola eksekusi agen.

from semantic_kernel.agents.runtime import InProcessRuntime

runtime = InProcessRuntime()
runtime.start()

Memanggil Orkestrasi

Panggil orkestrasi dengan tugas awal Anda (misalnya, "Pelanggan berada di baris."). Agen akan merutekan percakapan sesuai kebutuhan, yang melibatkan manusia ketika diperlukan.

orchestration_result = await handoff_orchestration.invoke(
    task="A customer is on the line.",
    runtime=runtime,
)

Kumpulkan Hasil

Tunggu hingga orkestrasi selesai.

value = await orchestration_result.get()
print(value)

Opsional: Hentikan Runtime

Setelah pemrosesan selesai, hentikan runtime untuk membersihkan sumber daya.

await runtime.stop_when_idle()

Sampel Output

TriageAgent: Hello! Thank you for reaching out. How can I assist you today?
User: I'd like to track the status of my order
OrderStatusAgent: Sure, I can help you with that. Could you please provide me with your order ID?
User: My order ID is 123
OrderStatusAgent: Your order with ID 123 has been shipped and is expected to arrive in 2-3 days. Is there anything else I can assist you with?
User: I want to return another order of mine
OrderReturnAgent: I can help you with returning your order. Could you please provide the order ID for the return and the reason you'd like to return it?
User: Order ID 321
OrderReturnAgent: Please provide the reason for returning the order with ID 321.
User: Broken item
OrderReturnAgent: The return for your order with ID 321 has been successfully processed due to the broken item. Is there anything else I can assist you with?
User: No, bye
Task is completed with summary: Handled order return for order ID 321 due to a broken item, and successfully processed the return.

Petunjuk / Saran

Kode sampel lengkap tersedia di sini.

Nota

Orkestrasi agen belum tersedia di Java SDK.

Langkah selanjutnya

Orkestrasi Magnetik