A Szemantikus Kernel ChatCompletionAgent felfedezése

Jótanács

A jelen vitafórumhoz kapcsolódó részletes API-dokumentáció a következő címen érhető el:

• ChatCompletionAgent
• Microsoft.SemanticKernel.Agents
• IChatCompletionService
• Microsoft.SemanticKernel.ChatCompletion

Jótanács

A jelen vitafórumhoz kapcsolódó részletes API-dokumentáció a következő címen érhető el:

• ChatCompletionAgent

Jótanács

A jelen vitafórumhoz kapcsolódó részletes API-dokumentáció a következő címen érhető el:

• ChatCompletionAgent

Csevegés befejezése a Szemantic Kernelben

A csevegés befejezése alapvetően a csevegésalapú interakció protokollja egy AI-modellel, ahol a csevegési előzmények megmaradnak, és minden kéréssel együtt megjelennek a modellben. A Szemantikus Kernel AI-szolgáltatások egységes keretrendszert kínálnak a különböző AI-modellek csevegés-befejezési képességeinek integrálásához.

Egy ChatCompletionAgent felhasználhatja ezen AI-szolgáltatások bármelyikét válaszok generálására, akár egy felhasználónak, akár egy másik ügynöknek irányítva azokat.

A fejlesztési környezet előkészítése

A ChatCompletionAgentfejlesztésének folytatásához konfigurálja a fejlesztői környezetet a megfelelő csomagokkal.

Adja hozzá a Microsoft.SemanticKernel.Agents.Core csomagot a projekthez:

dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease

Telepítse a semantic-kernel csomagot:

pip install semantic-kernel

Fontos

Attól függően, hogy melyik AI-szolgáltatást használja a ChatCompletionAgentszolgáltatás részeként, előfordulhat, hogy további csomagokat kell telepítenie. Kérjük, ellenőrizze a szükséges kiegészítőt az alábbi oldalon

<dependency>
    <groupId>com.microsoft.semantic-kernel</groupId>
    <artifactId>semantickernel-agents-core</artifactId>
    <version>[LATEST]</version>
</dependency>

ChatCompletionAgent létrehozása

A ChatCompletionAgent alapvetően AI-szolgáltatáson alapszik. A ChatCompletionAgent létrehozása egy Kernel-példány létrehozásával kezdődik, amely egy vagy több csevegés-kiegészítő szolgáltatást tartalmaz, majd az ügynök példányosítása következik egy Kernel-példányra mutató hivatkozással.

// Initialize a Kernel with a chat-completion service
IKernelBuilder builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(/*<...configuration parameters>*/);

Kernel kernel = builder.Build();

// Create the agent
ChatCompletionAgent agent =
    new()
    {
        Name = "SummarizationAgent",
        Instructions = "Summarize user input",
        Kernel = kernel
    };

Kétféleképpen hozhat létre ChatCompletionAgent:

1. A csevegés befejezésére szolgáló szolgáltatás közvetlen biztosításával

from semantic_kernel.agents import ChatCompletionAgent

# Create the agent by directly providing the chat completion service
agent = ChatCompletionAgent(
    service=AzureChatCompletion(),  # your chat completion service instance
    name="<agent name>",
    instructions="<agent instructions>",
)

2. Először hozzon létre egy Kernelt, adja hozzá a szolgáltatást, majd adja meg a kernelt

# Define the kernel
kernel = Kernel()

# Add the chat completion service to the kernel
kernel.add_service(AzureChatCompletion())

# Create the agent using the kernel
agent = ChatCompletionAgent(
  kernel=kernel, 
  name="<agent name>", 
  instructions="<agent instructions>",
)

Az első módszer akkor hasznos, ha már készen áll egy csevegés-befejezési szolgáltatás. A második módszer akkor hasznos, ha olyan kernelre van szüksége, amely több szolgáltatást vagy további funkciót kezel.

// Initialize a Kernel with a chat-completion service
var chatCompletion = OpenAIChatCompletion.builder()
        .withOpenAIAsyncClient(client) // OpenAIAsyncClient with configuration parameters
        .withModelId(MODEL_ID)
        .build();

var kernel = Kernel.builder()
        .withAIService(ChatCompletionService.class, chatCompletion)
        .build();

// Create the agent
var agent = ChatCompletionAgent.builder()
        .withKernel(kernel)
        .build();

AI-szolgáltatás kiválasztása

A Szemantikus Kernel szolgáltatások közvetlen AI-szolgáltatások használatával azonos módon működnek, a ChatCompletionAgent szolgáltatásválasztó specifikációját támogatja. A szolgáltatásválasztó azonosítja, hogy melyik AI-szolgáltatást célozza meg, amikor a Kernel több elemet tartalmaz.

Megjegyzés:

Ha több AI-szolgáltatás van jelen, és nincs szolgáltatásválasztó, a rendszer ugyanazt az alapértelmezett logikát alkalmazza az ügynökre, amelyet a külső AI-szolgáltatások használatakor talál. Agent Framework

IKernelBuilder builder = Kernel.CreateBuilder();

// Initialize multiple chat-completion services.
builder.AddAzureOpenAIChatCompletion(/*<...service configuration>*/, serviceId: "service-1");
builder.AddAzureOpenAIChatCompletion(/*<...service configuration>*/, serviceId: "service-2");

Kernel kernel = builder.Build();

ChatCompletionAgent agent =
    new()
    {
        Name = "<agent name>",
        Instructions = "<agent instructions>",
        Kernel = kernel,
        Arguments = // Specify the service-identifier via the KernelArguments
          new KernelArguments(
            new OpenAIPromptExecutionSettings() 
            { 
              ServiceId = "service-2" // The target service-identifier.
            })
    };

from semantic_kernel.connectors.ai.open_ai import (
    AzureChatCompletion,
    AzureChatPromptExecutionSettings,
)

# Define the Kernel
kernel = Kernel()

# Add the AzureChatCompletion AI service to the Kernel
kernel.add_service(AzureChatCompletion(service_id="service1"))
kernel.add_service(AzureChatCompletion(service_id="service2"))

settings = AzureChatPromptExecutionSettings(service_id="service2")

# Create the agent
agent = ChatCompletionAgent(
  kernel=kernel, 
  name="<agent name>", 
  instructions="<agent instructions>",
  arguments=KernelArguments(settings=settings)
)

A funkció jelenleg nem érhető el a Javában.

Beszélgetés ChatCompletionAgent

A ChatCompletionAgent való kommunikáció egy ChatHistory-példányon alapul, nem különbözik a Csevegésbefejező mesterséges intelligencia szolgáltatástól .

Egyszerűen meghívhatja az ügynököt a felhasználói üzenettel.

// Define agent
ChatCompletionAgent agent = ...;

// Generate the agent response(s)
await foreach (ChatMessageContent response in agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "<user input>")))
{
  // Process agent response(s)...
}

Az ügynökkel folytatott beszélgetéshez is használhat egy AgentThread-t. Itt egy ChatHistoryAgentThreadhasználunk.

A ChatHistoryAgentThread egy opcionális ChatHistory objektumot is használhat bemenetként a konstruktoron keresztül, ha egy korábbi beszélgetést folytat. (nem látható)

// Define agent
ChatCompletionAgent agent = ...;

AgentThread thread = new ChatHistoryAgentThread();

// Generate the agent response(s)
await foreach (ChatMessageContent response in agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "<user input>"), thread))
{
  // Process agent response(s)...
}

Többféleképpen is lehet beszélgetni egy ChatCompletionAgent-val.

A legegyszerűbb az get_responsehívása és várakozása:

# Define agent
agent = ChatCompletionAgent(...)

# Generate the agent response
response = await agent.get_response(messages="user input")
# response is an `AgentResponseItem[ChatMessageContent]` object

Ha azt szeretné, hogy az ügynök megőrizze a beszélgetések előzményeit a hívások között, az alábbi módon adja át a ChatHistoryAgentThread:

# Define agent
agent = ChatCompletionAgent(...)

# Generate the agent response(s)
response = await agent.get_response(messages="user input")

# Generate another response, continuing the conversation thread from the first response.
response2 = await agent.get_response(messages="user input", thread=response.thread)
# process agent response(s)

A invoke metódus meghívása egy AsyncIterableAgentResponseItem[ChatMessageContent]-t ad vissza.

# Define agent
agent = ChatCompletionAgent(...)

# Define the thread
thread = ChatHistoryAgentThread()

# Generate the agent response(s)
async for response in agent.invoke(messages="user input", thread=thread):
  # process agent response(s)

A ChatCompletionAgent támogatja a streamelést is, amelyben a invoke_stream metódus egy AsyncIterable-t ad vissza a StreamingChatMessageContent típusból.

# Define agent
agent = ChatCompletionAgent(...)

# Define the thread
thread = ChatHistoryAgentThread()

# Generate the agent response(s)
async for response in agent.invoke_stream(messages="user input", thread=thread):
  # process agent response(s)

ChatCompletionAgent agent = ...;

// Generate the agent response(s)
agent.invokeAsync(new ChatMessageContent<>(AuthorRole.USER, "<user input>")).block();

Az ügynökkel folytatott beszélgetéshez is használhat egy AgentThread-t. Itt egy ChatHistoryAgentThreadhasználunk.

A ChatHistoryAgentThread konstruktoron keresztül bemenetként is használhatja az ChatHistory objektumot, ha egy korábbi beszélgetést folytat. (nem látható)

// Define agent
ChatCompletionAgent agent = ...;

AgentThread thread = new ChatHistoryAgentThread();

// Generate the agent response(s)
agent.invokeAsync(new ChatMessageContent<>(AuthorRole.USER, "<user input>"), thread).block();

Köztes üzenetek kezelése egy ChatCompletionAgent

A Szemantikus Kernel ChatCompletionAgent egy olyan ügynök meghívására lett kialakítva, amely megfelel a felhasználói lekérdezéseknek vagy kérdéseknek. A meghívás során az ügynök végrehajthat eszközöket a végső válasz lehívásához. A folyamat során létrehozott köztes üzenetek eléréséhez a hívók megadhatnak egy visszahívási függvényt, amely kezeli a FunctionCallContent vagy FunctionResultContent példányokat.

A visszahívási ChatCompletionAgent dokumentáció hamarosan elérhető lesz.

A on_intermediate_message vagy agent.invoke(...) visszahívás konfigurálása lehetővé teszi a hívó számára az ügynök végső válaszának kialakítása során generált köztes üzenetek fogadását.

import asyncio
from typing import Annotated

from semantic_kernel.agents.chat_completion.chat_completion_agent import ChatCompletionAgent, ChatHistoryAgentThread
from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion
from semantic_kernel.contents import FunctionCallContent, FunctionResultContent
from semantic_kernel.contents.chat_message_content import ChatMessageContent
from semantic_kernel.functions import kernel_function


# Define a sample plugin for the sample
class MenuPlugin:
    """A sample Menu Plugin used for the concept sample."""

    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"


# This callback function will be called for each intermediate message
# Which will allow one to handle FunctionCallContent and FunctionResultContent
# If the callback is not provided, the agent will return the final response
# with no intermediate tool call steps.
async def handle_intermediate_steps(message: ChatMessageContent) -> None:
    for item in message.items or []:
        if isinstance(item, FunctionCallContent):
            print(f"Function Call:> {item.name} with arguments: {item.arguments}")
        elif isinstance(item, FunctionResultContent):
            print(f"Function Result:> {item.result} for function: {item.name}")
        else:
            print(f"{message.role}: {message.content}")


async def main() -> None:
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="Assistant",
        instructions="Answer questions about the menu.",
        plugins=[MenuPlugin()],
    )

    # Create a thread for the agent
    # If no thread is provided, a new thread will be
    # created and returned with the initial response
    thread: ChatHistoryAgentThread = None

    user_inputs = [
        "Hello",
        "What is the special soup?",
        "How much does that cost?",
        "Thank you",
    ]

    for user_input in user_inputs:
        print(f"# User: '{user_input}'")
        async for response in agent.invoke(
            messages=user_input,
            thread=thread,
            on_intermediate_message=handle_intermediate_steps,
        ):
            print(f"# {response.role}: {response}")
            thread = response.thread


if __name__ == "__main__":
    asyncio.run(main())

Az alábbiak az ügynökhívási folyamatból származó mintakimenetet szemléltetik:

User: 'Hello'
AuthorRole.ASSISTANT: Hi there! How can I assist you today?
User: 'What is the special soup?'
Function Call:> MenuPlugin-get_specials with arguments: {}
Function Result:> 
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        for function: MenuPlugin-get_specials
AuthorRole.ASSISTANT: The special soup today is Clam Chowder. Would you like to know anything else from the menu?
User: 'How much does that cost?'
Function Call:> MenuPlugin-get_item_price with arguments: {"menu_item":"Clam Chowder"}
Function Result:> $9.99 for function: MenuPlugin-get_item_price
AuthorRole.ASSISTANT: The Clam Chowder costs $9.99. Would you like to know more about the menu or anything else?
User: 'Thank you'
AuthorRole.ASSISTANT: You're welcome! If you have any more questions, feel free to ask. Enjoy your day!

A funkció jelenleg nem érhető el a Javában.

Deklaratív specifikáció

Hamarosan megjelenik a deklaratív specifikációk használatára vonatkozó dokumentáció.

Fontos

Ez a funkció a kísérleti fázisban van. Az ebben a szakaszban található funkciók fejlesztés alatt állnak, és változhatnak, mielőtt továbblépnek az előzetes verzióra vagy a kiadásra jelölt fázisra.

A ChatCompletionAgent közvetlenül egy YAML deklaratív specifikációból hozható létre. Ezzel a módszerrel strukturált és hordozható módon határozhatja meg az ügynök alapvető tulajdonságait, utasításait és elérhető funkcióit (beépülő moduljait). A YAML használatával egyetlen dokumentumban ismertetheti az ügynök nevét, leírását, utasítását, eszközkészletét és modellparamétereit, így az ügynök konfigurációja könnyen naplózható és reprodukálható.

Megjegyzés:

A deklaratív YAML-ben megadott eszközöknek vagy függvényeknek már létezniük kell a Kernel-példányban az ügynök létrehozásakor. Az ügynökbetöltő nem hoz létre új függvényeket a specifikációból; ehelyett megkeresi a hivatkozott beépülő modulokat és függvényeket a kernelben található azonosítójuk alapján. Ha egy szükséges beépülő modul vagy függvény nem található a kernelben, az ügynök felépítése során hibaüzenet jelenik meg.

Példa: ChatCompletionAgent létrehozása egy YAML-specifikációból

import asyncio
from typing import Annotated

from semantic_kernel import Kernel
from semantic_kernel.agents import AgentRegistry, ChatHistoryAgentThread
from semantic_kernel.agents.chat_completion.chat_completion_agent import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.functions import kernel_function

# Define a plugin with kernel functions
class MenuPlugin:
    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"

# YAML spec for the agent
AGENT_YAML = """
type: chat_completion_agent
name: Assistant
description: A helpful assistant.
instructions: Answer the user's questions using the menu functions.
tools:
  - id: MenuPlugin.get_specials
    type: function
  - id: MenuPlugin.get_item_price
    type: function
model:
  options:
    temperature: 0.7
"""

USER_INPUTS = [
    "Hello",
    "What is the special soup?",
    "What does that cost?",
    "Thank you",
]

async def main():
    kernel = Kernel()
    kernel.add_plugin(MenuPlugin(), plugin_name="MenuPlugin")

    agent: ChatCompletionAgent = await AgentRegistry.create_from_yaml(
        AGENT_YAML, kernel=kernel, service=OpenAIChatCompletion()
    )

    thread: ChatHistoryAgentThread | None = None

    for user_input in USER_INPUTS:
        print(f"# User: {user_input}")
        response = await agent.get_response(user_input, thread=thread)
        print(f"# {response.name}: {response}")
        thread = response.thread

    await thread.delete() if thread else None

if __name__ == "__main__":
    asyncio.run(main())

Ez a funkció nem érhető el.

Útmutató

Végponttól végpontig példáért lásd: ChatCompletionAgent

• útmutató: ChatCompletionAgent

Következő lépések

Fedezd fel a Copilot Studio ügynökét