Samenwerking tussen agenten verkennen in `AgentChat`

2025-05-26

Belangrijk

Deze functie bevindt zich in de experimentele fase. Functies in deze fase zijn in ontwikkeling en kunnen worden gewijzigd voordat u naar de preview- of releasekandidaatfase gaat.

Gedetailleerde API-documentatie met betrekking tot deze discussie is beschikbaar op:

Wat is `AgentChat`?

AgentChat biedt een framework dat interactie tussen meerdere agents mogelijk maakt, zelfs als ze van verschillende typen zijn. Hierdoor kunnen een ChatCompletionAgent en een OpenAIAssistantAgent samenwerken binnen hetzelfde gesprek. AgentChat definieert ook toegangspunten voor het initiëren van samenwerking tussen agents, hetzij via meerdere antwoorden of één agentantwoord.

Als abstracte klasse kunnen van AgentChat subklassen worden gemaakt om aangepaste scenario's te ondersteunen.

Een dergelijke subklasse, AgentGroupChat, biedt een concrete implementatie van AgentChat, met behulp van een strategiegebaseerde benadering om gespreksdynamiek te beheren.

Een `AgentGroupChat` aanmaken

Als u een AgentGroupChatwilt maken, kunt u de deelnemende agenten opgeven of een lege chat maken en vervolgens agenten als deelnemers toevoegen. Het configureren van de chatinstellingen en strategieën wordt ook uitgevoerd tijdens AgentGroupChat initialisatie. Deze instellingen bepalen hoe de gespreksdynamiek in de groep werkt.

Een `AgentGroupChat` creëren met een `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])

Een `Agent` toevoegen aan een `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)

`AgentGroupChat` gebruiken

AgentChat ondersteunt twee bewerkingsmodi: Single-Turn en Multi-Turn. In single-turnwordt een specifieke agent aangewezen om een antwoord te geven. In multi-turnreageren alle agents in het gesprek om beurten totdat aan een beëindigingscriterium wordt voldaan. In beide modi kunnen agents samenwerken door op elkaar te reageren om een gedefinieerd doel te bereiken.

Het geven van invoer

Het toevoegen van een invoerbericht aan een AgentChat volgt hetzelfde patroon als een ChatHistory-object.

AgentGroupChat chat = new();

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

chat = AgentGroupChat()

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

Eenmalige oproep van agent

In een aanroep met meerdere beurten moet het systeem beslissen welke agent vervolgens reageert en wanneer het gesprek moet worden beëindigd. Een aanroep van één beurt retourneert daarentegen gewoon een reactie van de opgegeven agent, zodat de beller de deelname van de agent rechtstreeks kan beheren.

Nadat de agent deelneemt aan een AgentChat via een enkelvoudige aanroep, wordt deze toegevoegd aan de verzameling agenten die in aanmerking komen voor aanroepen met meerdere beurten.

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

Meertraps aanroep van agent

Hoewel samenwerking tussen agents vereist dat een systeem aanwezig is dat niet alleen bepaalt welke agent moet reageren tijdens elke beurt, maar ook beoordeelt wanneer het gesprek het beoogde doel heeft bereikt, blijft het initiëren van samenwerking met meerdere paden eenvoudig.

Antwoorden van de agent worden asynchroon geretourneerd wanneer ze worden gegenereerd, zodat het gesprek in real-time kan verlopen.

API voor .NET-uitvoeringsinstellingen: 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)

Chatgeschiedenis openen

De AgentChat gespreksgeschiedenis is altijd toegankelijk, ook al worden berichten bezorgd via het aanroeppatroon. Dit zorgt ervoor dat eerdere uitwisselingen tijdens het gesprek beschikbaar blijven.

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

Omdat verschillende agenttypen of configuraties hun eigen versie van de gespreksgeschiedenis kunnen onderhouden, is de specifieke agentgeschiedenis ook beschikbaar door een agent op te geven. (Bijvoorbeeld: 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)

`AgentGroupChat` gedrag definiëren

Samenwerking tussen agents voor het oplossen van complexe taken is een kernagentisch patroon. Als u dit patroon effectief wilt gebruiken, moet een systeem aanwezig zijn dat niet alleen bepaalt welke agent moet reageren tijdens elke beurt, maar ook beoordeelt wanneer het gesprek het beoogde doel heeft bereikt. Hiervoor moet agentselectie worden beheerd en duidelijke criteria worden vastgesteld voor gespreksafbreking, waardoor naadloze samenwerking tussen agents tot een oplossing wordt gewaarborgd. Beide aspecten worden beheerd door de eigenschap Execution Settings.

In de volgende secties, Agentselectie en Chatbeëindiging, worden deze overwegingen uitgebreid besproken.

Agentselectie

Bij oproepen met meerdere beurten wordt de selectie van agenten geleid door een selectie-strategie. Deze strategie wordt gedefinieerd door een basisklasse die kan worden uitgebreid om aangepast gedrag te implementeren dat is afgestemd op specifieke behoeften. Voor het gemak zijn er ook twee vooraf gedefinieerde concrete selectiestrategieën beschikbaar, die kant-en-klare benaderingen bieden voor het afhandelen van agentselectie tijdens gesprekken.

Indien bekend, kan een initiële agent worden opgegeven om steeds als eerste aan de beurt te zijn. Een geschiedenisbeperking kan ook worden gebruikt om het tokengebruik te beperken bij gebruik van een strategie die gebaseerd is op een KernelFunction.

API voor .NET-selectiestrategie:

// 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 voor Python-selectiestrategie:

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

Chatbeëindiging

Bij aanroepen met meerdere beurten bepaalt de beëindigingsstrategie wanneer de laatste beurt plaatsvindt. Deze strategie zorgt ervoor dat het gesprek eindigt op het juiste punt.

Deze strategie wordt gedefinieerd door een basisklasse die kan worden uitgebreid om aangepast gedrag te implementeren dat is afgestemd op specifieke behoeften. Voor het gemak zijn er ook verschillende vooraf gedefinieerde concrete selectiestrategieën beschikbaar, die kant-en-klare benaderingen bieden voor het definiëren van beëindigingscriteria voor een AgentChat gesprek.

API voor .NET-beëindigingsstrategie:

// 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 voor python-beëindigingsstrategie:

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

Voltooiingsstatus van chat opnieuw instellen

Ongeacht of AgentGroupChat wordt aangeroepen met behulp van de enkelvoudige of meervoudige benadering, wordt de status van AgentGroupChat bijgewerkt om aan te geven dat deze is voltooid zodra aan de beëindigingscriteria is voldaan. Dit zorgt ervoor dat het systeem herkent wanneer een gesprek volledig is afgesloten. Als u een AgentGroupChat-exemplaar wilt blijven gebruiken nadat deze de voltooide status heeft bereikt, moet deze status opnieuw worden ingesteld om verdere interacties mogelijk te maken. Zonder het opnieuw instellen zijn extra interacties of agentreacties niet mogelijk.

In het geval van een aanroep met meerdere beurten die de maximale draailimiet bereikt, stopt het systeem de aanroep van de agent, maar markeert het exemplaar niet als voltooid. Dit maakt het mogelijk om het gesprek uit te breiden zonder de voltooiingsstatus opnieuw in te stellen.

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

Volledige gesprekstoestand wissen

Wanneer u klaar bent met het gebruik van een AgentChat waarbij een OpenAIAssistant heeft deelgenomen, kan het nodig zijn om de externe thread te verwijderen die aan de assistent is gekoppeld. AgentChat ondersteunt het opnieuw instellen of wissen van de volledige gespreksstatus, waaronder het verwijderen van een externe threaddefinitie. Dit zorgt ervoor dat er geen resterende gespreksgegevens aan de assistent blijven gekoppeld zodra de chat is afgesloten.

Bij een volledige reset worden de agents die zich bij de AgentChat hebben aangesloten niet verwijderd en blijft de AgentChat in een toestand waarin het opnieuw kan worden gebruikt. Hierdoor kunnen interacties met dezelfde agents worden voortgezet zonder dat ze opnieuw hoeven te worden geïnitialiseerd, waardoor toekomstige gesprekken efficiënter worden.

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

Handleiding

Zie voor een end-to-end-voorbeeld voor het gebruik van AgentGroupChat voor Agent samenwerking:

Samenwerking tussen agents coördineren met behulp van AgentGroupChat

Delen via

Samenwerking tussen agenten verkennen in AgentChat

Wat is AgentChat?

Een AgentGroupChat aanmaken

Een AgentGroupChat creëren met een Agent:

Een Agent toevoegen aan een AgentGroupChat:

AgentGroupChat gebruiken