Zkoumání spolupráce agentů v `AgentChat`

Článek
03/06/2025

Důležité

Tato funkce je v experimentální fázi. Funkce v této fázi jsou stále ve vývoji a před přechodem do fáze Preview nebo verze Candidate se můžou změnit.

Podrobná dokumentace k rozhraní API související s touto diskuzí je k dispozici na adrese:

Co je `AgentChat`?

AgentChat poskytuje architekturu, která umožňuje interakci mezi více agenty, i když se jedná o různé typy. Díky tomu může ChatCompletionAgent a OpenAIAssistantAgent spolupracovat ve stejné konverzaci. AgentChat také definuje vstupní body pro zahájení spolupráce mezi agenty, ať už prostřednictvím více odpovědí nebo jedné odpovědi agenta.

Jako abstraktní třída může být AgentChat podtříděna pro podporu vlastních scénářů.

Jedna z takových podtříd, AgentGroupChat, nabízí konkrétní implementaci AgentChat, pomocí přístupu založeného na strategii ke správě dynamiky konverzací.

Vytvoření `AgentGroupChat`

Pokud chcete vytvořit AgentGroupChat, můžete buď určit agenty, kteří se budou účastnit, nebo vytvořit prázdný chat a následně přidat účastníky agentů. Konfigurace nastavení chatu a strategií se provádí také během inicializace AgentGroupChat. Tato nastavení definují, jak bude dynamika konverzace fungovat ve skupině.

Vytvořit `AgentGroupChat` s `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])

Přidání `Agent` do `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)

Použití `AgentGroupChat`

AgentChat podporuje dva režimy provozu: Single-Turn a Multi-Turn. V single-turnje pro poskytnutí odpovědi určen konkrétní agent. Ve multi-turn se všichni agenti v konverzaci střídají, dokud nebude splněno kritérium ukončení. V obou režimech můžou agenti spolupracovat tím, že na sebe vzájemně reagují, aby dosáhli definovaného cíle.

Poskytnutí vstupu

Přidání vstupní zprávy k objektu AgentChat se řídí stejným vzorem jako u objektu ChatHistory.

AgentGroupChat chat = new();

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

chat = AgentGroupChat()

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

Volání agenta pro jedno otočení

Při vícenásobném vyvolání musí systém rozhodnout, který agent bude reagovat, a kdy má konverzace končit. Naproti tomu vyvolání s jednou otáčkou prostě vrátí odpověď od zadaného agenta, což volajícímu umožňuje přímou správu účasti agenta.

Jakmile se agent zúčastní AgentChat skrze jediný pokus o vyvolání, je přidán do skupiny agentů, kteří jsou způsobilí pro vícenásobné vyvolávání.

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

Vyvolání agenta pro vícenásobné interakce

I když spolupráce agentů vyžaduje, aby byl zaveden systém, který nejen určuje, který agent by měl během každého kroku reagovat, ale také posuzuje, kdy konverzace dosáhla zamýšleného cíle, zahájení spolupráce s více kroky zůstává jednoduchá.

Odpovědi agenta se vrací asynchronně, jak jsou generovány, což umožňuje konverzaci rozvinout v reálném čase.

Rozhraní API pro nastavení spouštění .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)

Přístup k historii chatu

Historie konverzací AgentChat je vždy přístupná, i když se zprávy doručují prostřednictvím vzorce vyvolání. Tím zajistíte, že předchozí výměny zůstanou dostupné v celé konverzaci.

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

Vzhledem k tomu, že různé typy nebo konfigurace agentů můžou udržovat vlastní verzi historie konverzací, je k dispozici také konkrétní historie agenta zadáním agenta. (Příklad: 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)

Definování chování `AgentGroupChat`

Spolupráce mezi agenty za účelem řešení složitých úloh je základním vzorem agentů. Aby bylo možné tento model efektivně používat, musí být zaveden systém, který nejen určuje, který agent by měl během každého turnu reagovat, ale také posuzuje, kdy konverzace dosáhla zamýšleného cíle. To vyžaduje správu výběru agenta a stanovení jasných kritérií pro ukončení konverzace, což zajišťuje bezproblémovou spolupráci mezi agenty směrem k řešení. Oba tyto aspekty řídí vlastnost Nastavení provedení.

V následujících částech se podrobně zaměříme na výběr agenta a ukončení chatu.

Výběr agenta

Při vícenásobném vyvolání se výběr agenta řídí Strategií Výběru. Tato strategie je definována základní třídou, která se dá rozšířit, aby implementovaly vlastní chování přizpůsobené konkrétním potřebám. Pro usnadnění práce jsou k dispozici také dvě předdefinované konkrétní strategie výběru, které nabízejí přístupy připravené k použití pro zpracování výběru agenta během konverzací.

Pokud je to známo, může být zadán počáteční agent, aby vždy šel jako první. Při použití strategie založené na KernelFunctionmůže být použit také redukčník historie k omezení využití tokenů .

Rozhraní API pro .NET strategii výběru:

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

Ukončení chatu

Při víceotáčkovém vyvolání strategie ukončení určuje, kdy nastane konečná fáze. Tato strategie zajistí, že konverzace skončí v příslušném okamžiku.

Tato strategie je definována základní třídou, která se dá rozšířit, aby implementovaly vlastní chování přizpůsobené konkrétním potřebám. Pro usnadnění je k dispozici také několik předdefinovaných konkrétních výběrových strategií a nabízí přístupy připravené k použití pro definování kritérií ukončení pro AgentChat konverzace.

Rozhraní API pro .NET strategii výběru:

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

Resetování stavu dokončení chatu

Bez ohledu na to, zda je AgentGroupChat vyvolán jednorázově nebo víceturnově, stav AgentGroupChat se aktualizuje, aby indikoval dokončení po splnění ukončovacích kritérií. Tím zajistíte, že systém rozpozná, když se konverzace plně ukončila. Pokud chcete pokračovat v používání instance AgentGroupChat poté, co dosáhla stavu Dokončeno, musí být tento stav resetován, aby bylo možné provádět další operace. Bez resetování nebudou možné další interakce nebo odpovědi agenta.

V případě vícenásobného vyvolání, které dosáhne maximálního limitu kol, systém zastaví vyvolání agenta, ale neoznačí instanci jako dokončenou. To umožňuje rozšířit konverzaci bez nutnosti resetovat stav dokončení .

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

Vymazat stav úplné konverzace

Při dokončení používání AgentChat, kde se OpenAIAssistant účastnil, může být nutné odstranit vzdálené vlákno přidružené k asistentovi. AgentChat podporuje resetování nebo vymazání celého stavu konverzace, což zahrnuje vymazání všech definic vzdálených vláken. Tím se zajistí, že po ukončení chatu nebudou žádná reziduální data konverzace propojená s asistentem.

Úplné resetování neodebere agenty , kteří se připojili k AgentChat, a ponechá AgentChat ve stavu, ve kterém je možné znovu použít. To umožňuje pokračování interakcí se stejnými agenty, aniž by bylo nutné je znovu inicializovat, aby budoucí konverzace byly efektivnější.

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

Postupy

Kompletní příklad použití AgentGroupChat pro spolupráci Agent najdete tady:

Jak koordinovat spolupráci agentů pomocí AgentGroupChat

Vytvoření agenta ze šablony

Sdílet prostřednictvím

Zkoumání spolupráce agentů v `AgentChat`

Co je `AgentChat`?

Vytvoření `AgentGroupChat`

Vytvořit `AgentGroupChat` s `Agent`:

Přidání `Agent` do `AgentGroupChat`:

Použití `AgentGroupChat`

Poskytnutí vstupu

Volání agenta pro jedno otočení

Vyvolání agenta pro vícenásobné interakce

Přístup k historii chatu

Definování chování `AgentGroupChat`

Výběr agenta

Ukončení chatu

Resetování stavu dokončení chatu

Vymazat stav úplné konverzace

Postupy

Další materiály

Sdílet prostřednictvím

Zkoumání spolupráce agentů v AgentChat

Co je AgentChat?

Vytvoření AgentGroupChat

Vytvořit AgentGroupChat s Agent:

Přidání Agent do AgentGroupChat:

Použití AgentGroupChat

Poskytnutí vstupu

Volání agenta pro jedno otočení

Vyvolání agenta pro vícenásobné interakce

Přístup k historii chatu

Definování chování AgentGroupChat

Výběr agenta

Ukončení chatu

Resetování stavu dokončení chatu

Vymazat stav úplné konverzace

Postupy

Další materiály

Zkoumání spolupráce agentů v `AgentChat`

Co je `AgentChat`?

Vytvoření `AgentGroupChat`

Vytvořit `AgentGroupChat` s `Agent`:

Přidání `Agent` do `AgentGroupChat`:

Použití `AgentGroupChat`

Definování chování `AgentGroupChat`