Menjelajahi Kolaborasi Agen di AgentChat

Penting

Ini adalah dokumen yang diarsipkan.

Penting

Fitur ini berada dalam tahap eksperimental tetapi tidak lagi dipertahankan. Untuk penggantian, lihat Orkestrasi Obrolan Grup dan panduan migrasi Bermigrasi dari AgentChat ke Orkestrasi Obrolan Grup.

Dokumentasi API terperinci yang terkait dengan diskusi ini tersedia di:

• AgentChat
• AgentGroupChat
• Microsoft.SemanticKernel.Agents.Chat

• AgentChat
• AgentGroupChat

Fitur saat ini tidak tersedia di Java.

Apa itu AgentChat?

AgentChat menyediakan kerangka kerja yang memungkinkan interaksi antara beberapa agen, bahkan jika mereka memiliki jenis yang berbeda. Hal ini memungkinkan ChatCompletionAgent dan OpenAIAssistantAgent bekerja sama dalam percakapan yang sama. AgentChat juga mendefinisikan titik masuk untuk memulai kolaborasi antar agen, baik melalui beberapa respons atau respons agen tunggal.

Sebagai kelas abstrak, AgentChat dapat disubkelas untuk mendukung skenario kustom.

Salah satu subkelas tersebut, AgentGroupChat, menawarkan implementasi konkret AgentChat, menggunakan pendekatan berbasis strategi untuk mengelola dinamika percakapan.

Membuat AgentGroupChat

Untuk membuat AgentGroupChat, Anda dapat menentukan agen yang berpartisipasi, atau membuat obrolan kosong dan kemudian menambahkan agen sebagai peserta. Mengonfigurasi Chat-Settings dan strateginya juga dilakukan selama inisialisasi AgentGroupChat. Pengaturan ini menentukan bagaimana dinamika percakapan akan berfungsi dalam grup.

Catatan: Chat-Settings default menghasilkan percakapan yang terbatas pada satu respons. Lihat AgentChat Perilaku untuk detail tentang mengonfigurasi Pengaturan Obrolan.

Membuat AgentGroupChat dengan Agent:

// Define agents
ChatCompletionAgent agent1 = ...;
OpenAIAssistantAgent agent2 = ...;

// Create chat with participating agents.
AgentGroupChat chat = new(agent1, agent2);

# Define agents
agent1 = ChatCompletionAgent(...)
agent2 = OpenAIAssistantAgent(...)

# Create chat with participating agents
chat = AgentGroupChat(agents=[agent1, agent2])

Fitur saat ini tidak tersedia di Java.

Menambahkan Agent ke AgentGroupChat:

// Define agents
ChatCompletionAgent agent1 = ...;
OpenAIAssistantAgent agent2 = ...;

// Create an empty chat.
AgentGroupChat chat = new();

// Add agents to an existing chat.
chat.AddAgent(agent1);
chat.AddAgent(agent2);

# Define agents
agent1 = ChatCompletionAgent(...)
agent2 = OpenAIAssistantAgent(...)

# Create an empty chat
chat = AgentGroupChat()

# Add agents to an existing chat
chat.add_agent(agent=agent1)
chat.add_agent(agent=agent2)

Fitur saat ini tidak tersedia di Java.

Menggunakan AgentGroupChat

AgentChat mendukung dua mode operasi: Single-Turn dan Multi-Turn. Dalam single-turn, agen tertentu ditunjuk untuk memberikan respons. Dalam multi-turn, semua agen dalam percakapan bergantian merespons hingga kriteria penghentian terpenuhi. Dalam kedua mode, agen dapat berkolaborasi dengan menanggapi satu sama lain untuk mencapai tujuan yang ditentukan.

Memberikan Masukan

Menambahkan pesan input ke AgentChat mengikuti pola yang sama dengan melampirkan objek ChatHistory.

AgentGroupChat chat = new();

chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, "<message content>"));

chat = AgentGroupChat()

await chat.add_chat_message(message="<message content>")

Fitur saat ini tidak tersedia di Java.

Pemanggilan Agen Satu Kali

Dalam pemanggilan multi-giliran, sistem harus memutuskan agen mana yang akan merespons selanjutnya dan kapan percakapan berakhir. Sebaliknya, pemanggilan satu kali hanya mengembalikan respons dari agen yang ditentukan, memungkinkan pemanggil untuk mengatur partisipasi agen secara langsung.

Setelah agen berpartisipasi dalam AgentChat melalui pemanggilan satu tahap, agen tersebut ditambahkan ke dalam kelompok agen yang memenuhi syarat untuk pemanggilan multi-tahap.

// Define an agent
ChatCompletionAgent agent = ...;

// Create an empty chat.
AgentGroupChat chat = new();

// Invoke an agent for its response
ChatMessageContent[] messages = await chat.InvokeAsync(agent).ToArrayAsync();

# Define an agent
agent = ChatCompletionAgent(...)

# Create an empty chat
chat = AgentGroupChat()

# Invoke an agent for its response(s)
async for message in chat.invoke(agent)
    # process message response(s)

Fitur saat ini tidak tersedia di Java.

Pemanggilan Agen Banyak Tahap

Meskipun kolaborasi agen mengharuskan sistem harus diberlakukan yang tidak hanya menentukan agen mana yang harus merespons selama setiap giliran tetapi juga menilai ketika percakapan telah mencapai tujuan yang dimaksudkan, memulai kolaborasi multi-giliran tetap mudah.

Tanggapan agen dikembalikan secara asinkron saat dihasilkan, memungkinkan percakapan berlangsung secara waktu nyata.

Catatan: Di bagian berikut, Pemilihan Agen dan Penghentian Obrolan, akan mempelajari Pengaturan Eksekusi secara rinci. Pengaturan Eksekusi default menggunakan pemilihan berurutan atau round-robin dan membatasi partisipasi agen ke satu giliran.

API Pengaturan Eksekusi .NET: AgentGroupChatSettings

// Define agents
ChatCompletionAgent agent1 = ...;
OpenAIAssistantAgent agent2 = ...;

// Create chat with participating agents.
AgentGroupChat chat =
  new(agent1, agent2)
  {
    // Override default execution settings
    ExecutionSettings =
    {
        TerminationStrategy = { MaximumIterations = 10 }
    }
  };

// Invoke agents
await foreach (ChatMessageContent response in chat.InvokeAsync())
{
  // Process agent response(s)...
}

# Define agents
agent1 = ChatCompletionAgent(...)
agent2 = OpenAIAssistantAgent(...)

# Create chat with participating agents
chat = AgentGroupChat(
    agents=[agent1, agent2],
    termination_strategy=DefaultTerminationStrategy(maximum_iterations=10),
)

async for response in chat.invoke():
    # process agent response(s)

Fitur saat ini tidak tersedia di Java.

Mengakses Riwayat Pesan

Riwayat percakapan AgentChat selalu dapat diakses, meskipun pesan dikirimkan melalui pola pemanggilan. Ini memastikan bahwa pertukaran sebelumnya tetap tersedia di seluruh percakapan.

Catatan: Pesan terbaru disediakan terlebih dahulu (urutan turun: terbaru ke terlama).

// Define and use a chat
AgentGroupChat chat = ...;

// Access history for a previously utilized AgentGroupChat
ChatMessageContent[] history = await chat.GetChatMessagesAsync().ToArrayAsync();

# Define a group chat
chat = AgentGroupChat(...)

# Access history for a previously utilized AgentGroupChat
history = await chat.get_chat_messages()

Fitur saat ini tidak tersedia di Java.

Karena berbagai jenis atau konfigurasi agen dapat mempertahankan versi riwayat percakapan mereka sendiri, riwayat spesifik agen juga tersedia dengan menentukan agen. (Misalnya: OpenAIAssistant versus ChatCompletionAgent.)

// Agents to participate in chat
ChatCompletionAgent agent1 = ...;
OpenAIAssistantAgent agent2 = ...;

// Define a group chat
AgentGroupChat chat = ...;

// Access history for a previously utilized AgentGroupChat
ChatMessageContent[] history1 = await chat.GetChatMessagesAsync(agent1).ToArrayAsync();
ChatMessageContent[] history2 = await chat.GetChatMessagesAsync(agent2).ToArrayAsync();

# Agents to participate in a chat
agent1 = ChatCompletionAgent(...)
agent2 = OpenAIAssistantAgent(...)

# Define a group chat
chat = AgentGroupChat(...)

# Access history for a previously utilized AgentGroupChat
history1 = await chat.get_chat_messages(agent=agent1)
history2 = await chat.get_chat_messages(agent=agent2)

Fitur saat ini tidak tersedia di Java.

Menentukan Perilaku AgentGroupChat

Kolaborasi antar agen untuk menyelesaikan tugas yang kompleks adalah pola agenik inti. Untuk menggunakan pola ini secara efektif, sistem harus diberlakukan yang tidak hanya menentukan agen mana yang harus merespons selama setiap giliran tetapi juga menilai kapan percakapan telah mencapai tujuan yang dimaksudkan. Ini membutuhkan pengelolaan pemilihan agen dan menetapkan kriteria yang jelas untuk penghentian percakapan, memastikan kerja sama yang mulus antara agen terhadap solusi. Kedua aspek ini diatur oleh properti Pengaturan Eksekusi.

Bagian berikut ini, Pemilihan Agen dan Penghentian Obrolan, akan membahas pertimbangan ini secara rinci.

Pilihan Agen

Dalam pemanggilan berulang, pemilihan agen mengikuti strategi pemilihan. Strategi ini didefinisikan oleh kelas dasar yang dapat diperluas untuk menerapkan perilaku kustom yang disesuaikan dengan kebutuhan tertentu. Untuk kenyamanan, dua Strategi Seleksi konkret yang telah ditentukan sebelumnya juga tersedia, menawarkan pendekatan siap pakai untuk menangani pemilihan agen selama percakapan.

Jika diketahui, agen pertama dapat ditentukan untuk selalu mengambil giliran pertama. Pengurang riwayat juga dapat digunakan untuk membatasi penggunaan token saat menggunakan strategi berdasarkan pada KernelFunction.

API Strategi Pemilihan .NET:

• SelectionStrategy
• SequentialSelectionStrategy
• KernelFunctionSelectionStrategy

// Define the agent names for use in the function template
const string WriterName = "Writer";
const string ReviewerName = "Reviewer";

// Initialize a Kernel with a chat-completion service
Kernel kernel = ...;

// Create the agents
ChatCompletionAgent writerAgent =
    new()
    {
        Name = WriterName,
        Instructions = "<writer instructions>",
        Kernel = kernel
    };

ChatCompletionAgent reviewerAgent =
    new()
    {
        Name = ReviewerName,
        Instructions = "<reviewer instructions>",
        Kernel = kernel
    };

// Define a kernel function for the selection strategy
KernelFunction selectionFunction =
    AgentGroupChat.CreatePromptFunctionForStrategy(
        $$$"""
        Determine which participant takes the next turn in a conversation based on the the most recent participant.
        State only the name of the participant to take the next turn.
        No participant should take more than one turn in a row.

        Choose only from these participants:
        - {{{ReviewerName}}}
        - {{{WriterName}}}

        Always follow these rules when selecting the next participant:
        - After {{{WriterName}}}, it is {{{ReviewerName}}}'s turn.
        - After {{{ReviewerName}}}, it is {{{WriterName}}}'s turn.

        History:
        {{$history}}
        """,
        safeParameterNames: "history");

// Define the selection strategy
KernelFunctionSelectionStrategy selectionStrategy = 
  new(selectionFunction, kernel)
  {
      // Always start with the writer agent.
      InitialAgent = writerAgent,
      // Parse the function response.
      ResultParser = (result) => result.GetValue<string>() ?? WriterName,
      // The prompt variable name for the history argument.
      HistoryVariableName = "history",
      // Save tokens by not including the entire history in the prompt
      HistoryReducer = new ChatHistoryTruncationReducer(3),
  };   

// Create a chat using the defined selection strategy.
AgentGroupChat chat =
    new(writerAgent, reviewerAgent)
    {
        ExecutionSettings = new() { SelectionStrategy = selectionStrategy }
    };

API Strategi Pemilihan Python:

• SelectionStrategy Kelas Dasar
• SequentialSelectionStrategy
• KernelFunctionSelectionStrategy

REVIEWER_NAME = "Reviewer"
WRITER_NAME = "Writer"

agent_reviewer = ChatCompletionAgent(
    kernel=kernel,
    name=REVIEWER_NAME,
    instructions="<instructions>",
)

agent_writer = ChatCompletionAgent(
    kernel=kernel,
    name=WRITER_NAME,
    instructions="<instructions>",
)

selection_function = KernelFunctionFromPrompt(
    function_name="selection",
    prompt=f"""
    Determine which participant takes the next turn in a conversation based on the the most recent participant.
    State only the name of the participant to take the next turn.
    No participant should take more than one turn in a row.

    Choose only from these participants:
    - {REVIEWER_NAME}
    - {WRITER_NAME}

    Always follow these rules when selecting the next participant:
    - After user input, it is {WRITER_NAME}'s turn.
    - After {WRITER_NAME} replies, it is {REVIEWER_NAME}'s turn.
    - After {REVIEWER_NAME} provides feedback, it is {WRITER_NAME}'s turn.

    History:
    {{{{$history}}}}
    """,
)

chat = AgentGroupChat(
    agents=[agent_writer, agent_reviewer],
    selection_strategy=KernelFunctionSelectionStrategy(
        function=selection_function,
        kernel=_create_kernel_with_chat_completion("selection"),
        result_parser=lambda result: str(result.value[0]) if result.value is not None else COPYWRITER_NAME,
        agent_variable_name="agents",
        history_variable_name="history",
    ),
)

Fitur saat ini tidak tersedia di Java.

Penghentian Percakapan

Dalam pemanggilan multi-giliran, strategi penghentian menentukan saat giliran terakhir berlangsung. Strategi ini memastikan percakapan berakhir pada titik yang sesuai.

Strategi ini didefinisikan oleh kelas dasar yang dapat diperluas untuk menerapkan perilaku kustom yang disesuaikan dengan kebutuhan tertentu. Untuk kenyamanan, beberapa Strategi Pemilihan konkret yang telah ditentukan sebelumnya juga tersedia, menawarkan pendekatan siap pakai untuk menentukan kriteria penghentian untuk percakapan AgentChat .

API Strategi Penghentian .NET:

• TerminationStrategy
• RegexTerminationStrategy
• KernelFunctionSelectionStrategy
• KernelFunctionTerminationStrategy
• AggregatorTerminationStrategy

// Initialize a Kernel with a chat-completion service
Kernel kernel = ...;

// Create the agents
ChatCompletionAgent writerAgent =
    new()
    {
        Name = "Writer",
        Instructions = "<writer instructions>",
        Kernel = kernel
    };

ChatCompletionAgent reviewerAgent =
    new()
    {
        Name = "Reviewer",
        Instructions = "<reviewer instructions>",
        Kernel = kernel
    };

// Define a kernel function for the selection strategy
KernelFunction terminationFunction =
    AgentGroupChat.CreatePromptFunctionForStrategy(
        $$$"""
        Determine if the reviewer has approved.  If so, respond with a single word: yes

        History:
        {{$history}}
        """,
        safeParameterNames: "history");

// Define the termination strategy
KernelFunctionTerminationStrategy terminationStrategy = 
  new(terminationFunction, kernel)
  {
      // Only the reviewer may give approval.
      Agents = [reviewerAgent],
      // Parse the function response.
      ResultParser = (result) => 
        result.GetValue<string>()?.Contains("yes", StringComparison.OrdinalIgnoreCase) ?? false,
      // The prompt variable name for the history argument.
      HistoryVariableName = "history",
      // Save tokens by not including the entire history in the prompt
      HistoryReducer = new ChatHistoryTruncationReducer(1),
      // Limit total number of turns no matter what
      MaximumIterations = 10,
};

// Create a chat using the defined termination strategy.
AgentGroupChat chat =
    new(writerAgent, reviewerAgent)
    {
        ExecutionSettings = new() { TerminationStrategy = terminationStrategy }
    };

API Strategi Penghentian Python:

• TerminationStrategy Kelas Dasar
• KernelFunctionTerminationStrategy
• AggregatorTerminationStrategy

REVIEWER_NAME = "Reviewer"
WRITER_NAME = "Writer"

agent_reviewer = ChatCompletionAgent(
    kernel=kernel,
    name=REVIEWER_NAME,
    instructions="<instructions>",
)

agent_writer = ChatCompletionAgent(
    kernel=kernel,
    name=WRITER_NAME,
    instructions="<instructions>",
)

termination_function = KernelFunctionFromPrompt(
    function_name="termination",
    prompt="""
    Determine if the copy has been approved.  If so, respond with a single word: yes

    History:
    {{$history}}
    """,
)

chat = AgentGroupChat(
    agents=[agent_writer, agent_reviewer],
    termination_strategy=KernelFunctionTerminationStrategy(
        agents=[agent_reviewer],
        function=termination_function,
        kernel=_create_kernel_with_chat_completion("termination"),
        result_parser=lambda result: str(result.value[0]).lower() == "yes",
        history_variable_name="history",
        maximum_iterations=10,
    ),
)

Fitur saat ini tidak tersedia di Java.

Mereset Penyelesaian Percakapan

Terlepas dari apakah AgentGroupChat dipanggil menggunakan pendekatan giliran tunggal atau multi-giliran, status AgentGroupChat diperbarui untuk menunjukkan bahwa itu selesai setelah kriteria penghentian terpenuhi. Ini memastikan bahwa sistem mengenali ketika percakapan telah sepenuhnya disimpulkan. Untuk terus menggunakan instans AgentGroupChat setelah mencapai status Selesai, status ini harus diatur ulang untuk memungkinkan interaksi lebih lanjut. Tanpa mengatur ulang, interaksi tambahan atau respons agen tidak akan dimungkinkan.

Dalam kasus pemanggilan berulang yang mencapai batas giliran maksimum, sistem akan menghentikan pemanggilan agen tetapi tidak akan menandai kejadian sebagai selesai. Hal ini memungkinkan kemungkinan memperpanjang percakapan tanpa perlu mengatur ulang status Penyelesaian.

// Define an use chat
AgentGroupChat chat = ...;

// Evaluate if completion is met and reset.
if (chat.IsComplete) 
{
  // Opt to take action on the chat result...

  // Reset completion state to continue use
  chat.IsComplete = false;
}

# Define a group chat
chat = AgentGroupChat()

# Evaluate if completion is met and reset
if chat.is_complete:
    # Reset completion state to continue use
    chat.is_complete = False

Fitur saat ini tidak tersedia di Java.

Bersihkan Status Percakapan Penuh

Setelah selesai menggunakan AgentChat di mana OpenAIAssistant terlibat, mungkin perlu untuk menghapus thread jarak jauh yang terkait dengan asisten. AgentChat mendukung pengaturan ulang atau penghapusan seluruh status percakapan, termasuk menghapus definisi utas jarak jauh apa pun. Ini memastikan bahwa tidak ada data percakapan residu yang tetap ditautkan ke asisten setelah obrolan berakhir.

Reset penuh tidak menghapus agen yang telah bergabung AgentChat dan meninggalkan AgentChat dalam keadaan di mana dapat digunakan kembali. Ini memungkinkan kelanjutan interaksi dengan agen yang sama tanpa perlu menginisialisasi ulang mereka, membuat percakapan di masa depan lebih efisien.

// Define an use chat
AgentGroupChat chat = ...;

// Clear the all conversation state
await chat.ResetAsync();

# Define a group chat
chat = AgentGroupChat()

# Clear the conversation state
await chat.reset()

Fitur saat ini tidak tersedia di Java.

Panduan Praktis

Untuk contoh menyeluruh dalam menggunakan AgentGroupChat untuk kolaborasi Agent, lihat:

• Cara Mengoordinasikan Kolaborasi Agen menggunakan AgentGroupChat