AgentChat'da Ajan İşbirliğini Keşfetme

Önemli

Bu özellik deneysel aşamadadır. Bu aşamadaki özellikler geliştirme aşamasındadır ve önizleme veya sürüm adayı aşamasına geçmeden önce değiştirilebilir.

Bu tartışmayla ilgili ayrıntılı API belgelerine şu adreste ulaşabilirsiniz:

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

• AgentChat
• AgentGroupChat

Özellik şu anda Java'da kullanılamıyor.

AgentChat nedir?

AgentChat, farklı türde olsalar bile birden çok aracı arasında etkileşime olanak tanıyan bir çerçeve sağlar. Bu, bir ChatCompletionAgent ve bir OpenAIAssistantAgent aynı konuşma içinde birlikte çalışmasını mümkün kılar. AgentChat, birden çok yanıt veya tek bir aracı yanıtı aracılığıyla aracılar arasında işbirliği başlatmaya yönelik giriş noktalarını da tanımlar.

Soyut bir sınıf olarak AgentChat özel senaryoları desteklemek için alt sınıfa eklenebilir.

Bu tür alt sınıflardan biri olan AgentGroupChat, konuşma dinamiklerini yönetmek için strateji tabanlı bir yaklaşım kullanarak AgentChatsomut bir uygulaması sunar.

Bir AgentGroupChat oluşturma

AgentGroupChatoluşturmak için, ya katılımcı ajanları belirtebilir ya da boş bir sohbet oluşturup ardından ajan katılımcıları ekleyebilirsiniz. Chat-Settings ve Stratejilerin yapılandırılması, AgentGroupChat başlatılması sırasında da yapılır. Bu ayarlar, konuşma dinamiğinin grup içinde nasıl çalışacağını tanımlar.

Not: Varsayılan Chat-Settings tek bir yanıtla sınırlı bir konuşmayla sonuçlanır. Sohbet Ayarlarını yapılandırmayla ilgili ayrıntılar için bkz AgentChat . Davranış .

AgentGroupChatile bir Agent oluşturma:

// 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])

Özellik şu anda Java'da kullanılamıyor.

Agent'ı AgentGroupChat'e ekleme:

// 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)

Özellik şu anda Java'da kullanılamıyor.

AgentGroupChat’ı kullanma

AgentChat iki işlem modunu destekler: Single-Turn ve Multi-Turn. single-turniçinde, belirli bir temsilci yanıt sağlamak üzere atanır. multi-turn'de, sohbetteki tüm ajanlar bir sonlandırma ölçütü karşılanıncaya kadar sırayla yanıtlar. Her iki modda da aracılar, tanımlanmış bir hedefe ulaşmak için birbirlerine yanıt vererek işbirliği yapabilir.

Giriş Sağlama

Bir AgentChat giriş iletisi eklemek, ChatHistory nesnesiyle aynı deseni izler.

AgentGroupChat chat = new();

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

chat = AgentGroupChat()

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

Özellik şu anda Java'da kullanılamıyor.

Tek Dönüşlü Aracı Çağırma

Birden çok dönüşlü çağrıda, sistem hangi aracının daha sonra yanıt vereceğine ve konuşmanın ne zaman biteceğine karar vermelidir. Buna karşılık, tek turluk bir çağrı, belirtilen ajandan bir yanıt alıp çağıranın, ajanın katılımını doğrudan yönetmesini sağlar.

Bir ajan AgentChat'ye tek dönüşlü bir çağrı yoluyla katıldıktan sonra, çok aşamalı çağrıya uygun ajanlar kümesine eklenir.

// 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)

Özellik şu anda Java'da kullanılamıyor.

Çok Aşamalı Aracı Çağırma

Ajan işbirliği, her dönüş sırasında hangi ajanın yanıt vermesi gerektiğini belirleyen ve aynı zamanda konuşmanın belirlenen hedefe ne zaman ulaştığını değerlendiren bir sistemin mevcut olmasını gerektirir, ancak çok aşamalı işbirliğini başlatmak yine de basittir.

Aracı yanıtları, oluşturuldukları sırada eşzamanlı olmayan bir şekilde döndürülür ve konuşmanın gerçek zamanlı olarak gelişmesine olanak tanır.

Not: Aşağıdaki bölümlerde Aracı Seçimi ve Sohbet Sonlandırma, Yürütme Ayarları'na ayrıntılı olarak göz atacaktır. Varsayılan Yürütme Ayarları sıralı veya dönüşümlü seçimi kullanır ve aracı katılımını bir kerelik katılımla sınırlar.

.NET Yürütme Ayarları API'si: 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)

Özellik şu anda Java'da kullanılamıyor.

Sohbet Geçmişine Erişme

AgentChat konuşma geçmişi, iletiler çağrı düzeni aracılığıyla teslim edilmesine rağmen her zaman erişilebilir. Bu, geçmiş değişimlerin konuşma boyunca kullanılabilir kalmasını sağlar.

Not: En son ileti önce gösterilir (azalan düzen: yeniden eskiye).

// 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()

Özellik şu anda Java'da kullanılamıyor.

Farklı aracı türleri veya yapılandırmaları, konuşma geçmişinin kendi versiyonlarını koruyabileceğinden, bir aracı belirterek aracıya özgü geçmişe de ulaşılabilir. (Örneğin: OpenAIAssistant ile ChatCompletionAgentkarşılaştırması.)

// 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)

Özellik şu anda Java'da kullanılamıyor.

AgentGroupChat Davranışını Tanımlama

Karmaşık görevleri çözmek için aracılar arasındaki işbirliği temel bir aracı düzenidir. Bu modeli etkili bir şekilde kullanmak için, her bir dönüşte hangi ajanın yanıt vermesi gerektiğini belirleyen ve konuşmanın hedeflenen amacına ne zaman ulaştığını değerlendiren bir sistemin mevcut olması gerekir. Bu, aracı seçimini yönetmeyi ve konuşma sonlandırma için net ölçütler belirlemeyi ve bir çözüme yönelik aracılar arasında sorunsuz işbirliği sağlamayı gerektirir. Bu özelliklerin her ikisi de Yürütme Ayarları özelliğine tabidir.

Aşağıdaki aracı seçimi ve sohbet sonlandırma bölümleri bu konuları ayrıntılı olarak ele alacaktır.

Temsilci Seçimi

Çok aşamalı çağrıda, aracı seçimi Seçim Stratejisi ile yönlendirilir. Bu strateji, belirli gereksinimlere göre uyarlanmış özel davranışları uygulamak için genişletilebilen bir temel sınıf tarafından tanımlanır. Kolaylık sağlamak için, konuşmalar sırasında aracı seçimini işlemeye yönelik kullanıma hazır yaklaşımlar sunan önceden tanımlanmış iki somut Seçim Stratejisi de mevcuttur.

Biliniyorsa, her zaman ilk sırayı alacak şekilde bir başlangıç ajanı belirtilebilir. KernelFunctiontemel alan bir strateji kullanılırken belirteç kullanımını sınırlamak için bir geçmiş azaltıcı da kullanılabilir.

.NET Seçim Stratejisi API'si:

• 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 }
    };

Python Seçim Stratejisi API'si:

• SelectionStrategy Temel Sınıf
• 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",
    ),
)

Özellik şu anda Java'da kullanılamıyor.

Sohbet Sonlandırma

Çoklu dönüş çağrısında Sonlandırma Stratejisi, son dönüşün ne zaman gerçekleşeceğini belirler. Bu strateji, konuşmanın uygun noktada bitmesini sağlar.

Bu strateji, belirli gereksinimlere göre uyarlanmış özel davranışları uygulamak için genişletilebilen bir temel sınıf tarafından tanımlanır. Kolaylık sağlamak için, konuşmalar için AgentChat sonlandırma ölçütlerini tanımlamaya yönelik kullanıma hazır yaklaşımlar sunan, önceden tanımlanmış çeşitli somut Seçim Stratejileri de mevcuttur.

.NET Sonlandırma Stratejisi API'si:

• 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 }
    };

Python Sonlandırma Stratejisi API'si:

• TerminationStrategy Temel Sınıf
• 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,
    ),
)

Özellik şu anda Java'da kullanılamıyor.

Sohbet Tamamlanma Durumunu Sıfırlama

Tek dönüşlü veya çok dönüşlü yaklaşım kullanılarak AgentGroupChat çağrılsa da çağrılmasa da, sonlandırma ölçütleri karşılandıktan sonra tamamlandığını göstermek için AgentGroupChat durumu güncellenir. Bu, sistemin bir konuşmanın tam olarak ne zaman sona erdiğini tanımasını sağlar. AgentGroupChat durumuna ulaştıktan sonra bir örneği kullanmaya devam etmek için bu durumun daha fazla etkileşime izin verecek şekilde sıfırlanması gerekir. Sıfırlama yapılmadan ek etkileşimler veya aracı yanıtları mümkün olmayacaktır.

Maksimum dönüş sınırına ulaşan çok dönüşlü çağrı durumunda sistem aracı çağrısını durduracak ancak örneği tamamlandı olarak işaretlemeyecektir. Bu, Tamamlanma durumunu sıfırlamaya gerek kalmadan konuşmanın genişletilmesine olanak tanır.

// 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

Özellik şu anda Java'da kullanılamıyor.

Tüm Konuşma Durumunu Temizle

AgentChat'in katıldığı bir OpenAIAssistant kullanmayı bitirdiğinizde, yardımcıyla ilişkili uzak iş parçacığını silmek gerekebilir. AgentChat , tüm uzak iş parçacığı tanımlarını silmeyi de içeren konuşma durumunun tamamını sıfırlamayı veya temizlemeyi destekler. Bu, sohbet sona erdikten sonra artık konuşma verilerinin yardımcıyla bağlantılı kalmamasını sağlar.

Tam sıfırlama, AgentChat öğesine katılan aracıları kaldırmaz ve AgentChat öğesini yeniden kullanılabilecek bir durumda bırakır. Bu, gelecekteki konuşmaları daha verimli hale getirerek yeniden başlatmaya gerek kalmadan aynı aracılarla etkileşimlerin devam etmesini sağlar.

// 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()

Özellik şu anda Java'da kullanılamıyor.

Nasıl Yapılır

AgentGroupChat kullanmaya yönelik, Agent işbirliği için uçtan uca bir örnek için bkz:

• AgentGroupChat kullanarak Aracı İşbirliğini Koordine Etme