Utforska agentsamarbete i `AgentChat`

Artikel
03/06/2025

Viktig

Den här funktionen är i den experimentella fasen. Funktioner i det här skedet är fortfarande under utveckling och kan komma att ändras innan de går vidare till förhandsversionen eller lanseringsfasen.

Detaljerad API-dokumentation som rör den här diskussionen finns på:

Vad är `AgentChat`?

AgentChat tillhandahåller ett ramverk som möjliggör interaktion mellan flera agenter, även om de är av olika typer. Detta gör det möjligt för en ChatCompletionAgent och en OpenAIAssistantAgent att arbeta tillsammans i samma konversation. AgentChat definierar också startpunkter för att initiera samarbete mellan agenter, oavsett om det gäller flera svar eller ett enda agentsvar.

Som en abstrakt klass kan AgentChat underklasseras för att stödja anpassade scenarier.

En sådan underklass, AgentGroupChat, erbjuder en konkret implementering av AgentChatmed hjälp av en strategibaserad metod för att hantera konversationsdynamik.

Skapa en `AgentGroupChat`

Om du vill skapa en AgentGroupChatkan du antingen ange de deltagande agenterna eller skapa en tom chatt och därefter lägga till agentdeltagare. Konfigurering av chattinställningar och Strategier utförs också under AgentGroupChat initiering. De här inställningarna definierar hur konversationsdynamiken ska fungera i gruppen.

Skapa en `AgentGroupChat` med en `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])

Lägga till en `Agent` i en `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)

Använda `AgentGroupChat`

AgentChat stöder två driftlägen: Single-Turn och Multi-Turn. I single-turnutses en specifik agent för att ge ett svar. I multi-turnturas alla agenter i konversationen om att svara tills ett avslutningsvillkor uppfylls. I båda lägena kan agenter samarbeta genom att svara på varandra för att uppnå ett definierat mål.

Ange indata

Att lägga till ett ingångsmeddelande i en AgentChat följer samma mönster som för ett ChatHistory-objekt.

AgentGroupChat chat = new();

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

chat = AgentGroupChat()

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

Anrop av agent för en enda omgång

I ett anrop med flera turer måste systemet bestämma vilken agent som ska svara härnäst och när konversationen ska avslutas. Ett anrop med en enda tur returnerar däremot bara ett svar från den angivna agenten, vilket gör att anroparen kan hantera agentdeltagandet direkt.

När en agent har deltagit i AgentChat genom ett anrop med enkel tur läggs den till i uppsättningen med agenter berättigade till anrop med flera omgångar.

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

Anrop av fleromgångsagenter

Även om agentsamarbete kräver att ett system måste finnas på plats som inte bara avgör vilken agent som ska svara under varje tur, utan också utvärderar när konversationen har uppnått sitt avsedda mål, är det fortfarande enkelt att initiera samarbete i flera svängar.

Agentsvar returneras asynkront när de genereras, vilket gör att konversationen kan utvecklas i realtid.

API för .NET-körningsinställningar: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)

Åtkomst till chatthistorik

Den AgentChat konversationshistoriken är alltid tillgänglig, även om meddelanden levereras via anropsmönstret. Detta säkerställer att tidigare utbyten förblir tillgängliga under hela konversationen.

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

Eftersom olika agenttyper eller konfigurationer kan behålla sin egen version av konversationshistoriken är agentspecifik historik också tillgänglig genom att ange en agent. (Till exempel: OpenAIAssistant jämfört med 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)

Definiera `AgentGroupChat` beteende

Samarbete mellan agenter för att lösa komplexa uppgifter är ett grundläggande agentiskt mönster. För att kunna använda det här mönstret effektivt måste ett system finnas på plats som inte bara avgör vilken agent som ska svara under varje tur utan också utvärderar när konversationen har uppnått sitt avsedda mål. Detta kräver att du hanterar agentval och fastställer tydliga kriterier för konversationsavslut, vilket säkerställer sömlöst samarbete mellan agenter mot en lösning. Båda dessa aspekter styrs av egenskapen Körningsinställningar.

I följande avsnitt, Agentval och Chattavslut, beskrivs dessa överväganden i detalj.

Val av agent

I anrop med flera turer styrs valet av agent av en urvalsstrategi. Den här strategin definieras av en basklass som kan utökas för att implementera anpassade beteenden som är skräddarsydda för specifika behov. För enkelhetens skull är två fördefinierade konkreta urvalsstrategier också tillgängliga, som erbjuder färdiga metoder för att hantera agentval under konversationer.

Om det är känt kan en initial agent anges för att alltid ta den första turen. En historikreducerare kan också användas för att begränsa tokenanvändningen när du använder en strategi som baseras på en KernelFunction.

.NET Selection Strategy API:

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

Avslutning av chatt

I anrop med flera svängar avgör avslutningsstrategin när den sista svängen äger rum. Den här strategin säkerställer att konversationen avslutas vid rätt tidpunkt.

Den här strategin definieras av en basklass som kan utökas för att implementera anpassade beteenden som är skräddarsydda för specifika behov. För enkelhetens skull finns flera fördefinierade konkreta urvalsstrategier också tillgängliga, som erbjuder färdiga metoder för att definiera avslutningskriterier för en AgentChat konversationer.

.NET Selection Strategy API:

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

Återställa status för chattens färdigställning

Oavsett om AgentGroupChat anropas med hjälp av enstegs- eller flerstegsmetoden, uppdateras tillståndet för AgentGroupChat för att indikera att det slutförts så snart avslutningskriterierna är uppfyllda. Detta säkerställer att systemet känner igen när en konversation har slutförts helt. Om du vill fortsätta använda en AgentGroupChat instans när den har nått tillståndet Slutförd måste det här tillståndet återställas för att tillåta ytterligare interaktioner. Utan återställning är det inte möjligt att genomföra ytterligare interaktioner eller agentsvar.

Om det gäller ett anrop med flera omgångar som når maxgränsen, kommer systemet att upphöra med agentanropet men markera inte instansen som slutförd. På så sätt kan du utöka konversationen utan att behöva återställa slutförandetillståndet.

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

Rensa fullständigt konversationstillstånd

När du är klar med att använda en AgentChat där en OpenAIAssistant har deltagit kan det vara nödvändigt att ta bort den -tråd som är kopplad till -assistenten. AgentChat stöder återställning eller rensning av hela konversationstillståndet, vilket innefattar att ta bort alla fjärranslutna tråd definition. Detta säkerställer att inga kvarvarande konversationsdata förblir länkade till assistenten när chatten avslutas.

En fullständig återställning tar inte bort agenter som hade anslutit till AgentChat och lämnar AgentChat i ett tillstånd där det kan återanvändas. Detta möjliggör fortsatt interaktion med samma agenter utan att behöva initiera dem igen, vilket gör framtida konversationer mer effektiva.

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

Så här gör du

Här är ett från början till slut-exempel på att använda AgentGroupChat för Agent-samarbete:

Samordna agentsamarbete med hjälp av AgentGroupChat

Skapa en agent från en mall

Dela via

Utforska agentsamarbete i `AgentChat`

Vad är `AgentChat`?

Skapa en `AgentGroupChat`

Skapa en `AgentGroupChat` med en `Agent`:

Lägga till en `Agent` i en `AgentGroupChat`:

Använda `AgentGroupChat`

Ange indata

Anrop av agent för en enda omgång

Anrop av fleromgångsagenter

Åtkomst till chatthistorik

Definiera `AgentGroupChat` beteende

Val av agent

Avslutning av chatt

Återställa status för chattens färdigställning

Rensa fullständigt konversationstillstånd

Så här gör du

Ytterligare resurser

Dela via

Utforska agentsamarbete i AgentChat

Vad är AgentChat?

Skapa en AgentGroupChat

Skapa en AgentGroupChat med en Agent:

Lägga till en Agent i en AgentGroupChat:

Använda AgentGroupChat

Ange indata

Anrop av agent för en enda omgång

Anrop av fleromgångsagenter

Åtkomst till chatthistorik

Definiera AgentGroupChat beteende

Val av agent

Avslutning av chatt

Återställa status för chattens färdigställning

Rensa fullständigt konversationstillstånd

Så här gör du

Ytterligare resurser

Utforska agentsamarbete i `AgentChat`

Vad är `AgentChat`?

Skapa en `AgentGroupChat`

Skapa en `AgentGroupChat` med en `Agent`:

Lägga till en `Agent` i en `AgentGroupChat`:

Använda `AgentGroupChat`

Definiera `AgentGroupChat` beteende