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

Makale
03/16/2025

Önemli

Bu özellik deneysel aşamadadır. Bu aşamadaki özellikler hala 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`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.

`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. Sohbet Ayarları ve Stratejileri yapılandırması da AgentGroupChat başlatma sırasında gerçekleştirilir. Bu ayarlar, konuşma dinamiğinin grup içinde nasıl çalışacağını tanımlar.

`AgentGroupChat`ile 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])

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

`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>")

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 aracı AgentChat üzerinden tek dönüşlü bir çağrıya katıldıktan sonra, çok dönüşlü çağrı için uygun aracı 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)

Ç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.

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

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.

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

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)

`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ı sırasında 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. KernelFunction temel alınarak bir strateji kullanıldığında belirteç kullanımını sınırlamak için bir geçmiş azaltıcı da kullanılabilir.

.NET Seçim Stratejisi API'si:

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

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",
    ),
)

Sohbet Sonlandırma

Çoklu tur çağrısında, Sonlandırma Stratejisi son tur 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 sonlandırma ölçütlerini tanımlamaya yönelik kullanıma hazır yaklaşımlar sunan, önceden tanımlanmış çeşitli somut AgentChat de kullanılabilir.

.NET Seçim Stratejisi API'si:

// 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(selectionFunction, 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 }
    };

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

Sohbet Tamamlanma Durumunu Sıfırlama

AgentGroupChat tek dönüşlü veya çok dönüşlü yaklaşım kullanılarak çağrılsa da, sonlandırma ölçütleri karşılandığında AgentGroupChat durumu, tamamlandığını belirtmek için 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

Tüm Konuşma Durumunu Temizle

AgentChat'in katıldığı bir OpenAIAssistant kullanımı tamamlandığında, yardımcısıile ilişkili uzak iş parçacığı'ü silmek gerekebilir. AgentChat uzak bir konu tanımı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, 'ye katılan AgentChat aracılarını kaldırmaz ve AgentChat'ü 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()

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

Şablondan Aracı Oluşturma

Aracılığıyla paylaş

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

`AgentChat`nedir?

`AgentGroupChat` oluşturma

`AgentGroupChat`ile bir `Agent` oluşturma:

`Agent`'ı `AgentGroupChat`'e ekleme:

`AgentGroupChat`’ı kullanma

Giriş Sağlama

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

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

Sohbet Geçmişine Erişme

`AgentGroupChat` Davranışını Tanımlama

Temsilci Seçimi

Sohbet Sonlandırma

Sohbet Tamamlanma Durumunu Sıfırlama

Tüm Konuşma Durumunu Temizle

Nasıl Yapılır

Ek kaynaklar

Aracılığıyla paylaş

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

AgentChatnedir?

AgentGroupChat oluşturma

AgentGroupChatile bir Agent oluşturma:

Agent'ı AgentGroupChat'e ekleme:

AgentGroupChat’ı kullanma

Giriş Sağlama

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

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

Sohbet Geçmişine Erişme

AgentGroupChat Davranışını Tanımlama

Temsilci Seçimi

Sohbet Sonlandırma

Sohbet Tamamlanma Durumunu Sıfırlama

Tüm Konuşma Durumunu Temizle

Nasıl Yapılır

Ek kaynaklar

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

`AgentChat`nedir?

`AgentGroupChat` oluşturma

`AgentGroupChat`ile bir `Agent` oluşturma:

`Agent`'ı `AgentGroupChat`'e ekleme:

`AgentGroupChat`’ı kullanma

`AgentGroupChat` Davranışını Tanımlama