Freigeben über

Konfigurieren von Agents mit semantischen Kernel-Plug-Ins

Wichtig

Dieses Feature befindet sich in der Veröffentlichungskandidatenphase. Features in dieser Phase sind nahezu vollständig und allgemein stabil, obwohl sie kleinere Verfeinerungen oder Optimierungen durchlaufen können, bevor sie die vollständige allgemeine Verfügbarkeit erreichen.

Funktionen und Plugins im semantischen Kernel

Funktionsaufrufe sind ein leistungsfähiges Tool, mit dem Entwickler benutzerdefinierte Funktionen hinzufügen und die Funktionen von KI-Anwendungen erweitern können. Die Semantische Kernel-Plug-In-Architektur bietet ein flexibles Framework zur Unterstützung von Funktionsaufrufen. Für ein Agent basiert die Integration von Plug-Ins und Funktionsaufrufen auf diesem grundlegenden semantischen Kernel-Feature.

Nach der Konfiguration wählt ein Agent aus, wann und wie eine verfügbare Funktion aufgerufen werden soll, wie es in jeder Verwendung außerhalb der Agent Framework tun würde.

Tipp

API-Referenz:

Tipp

API-Referenz:

Tipp

API-Referenz:

Hinzufügen von Plug-Ins zu einem Agent

Jedes Plug-In, das für ein Agent verfügbar ist, wird innerhalb seiner jeweiligen Kernel Instanz verwaltet. Dieses Setup ermöglicht es jedem Agent, auf unterschiedliche Funktionen zuzugreifen, die auf seiner spezifischen Rolle basieren.

Plug-Ins können Kernel entweder hinzugefügt werden, bevor oder nachdem Agent erstellt wurde. Der Prozess der Initialisierung von Plug-Ins folgt denselben Mustern, die für jede semantische Kernelimplementierung verwendet werden, was Konsistenz und Benutzerfreundlichkeit bei der Verwaltung von KI-Funktionen ermöglicht.

Hinweis

Für eine ChatCompletionAgentFunktion muss der Funktionsaufrufmodus explizit aktiviert sein. Der OpenAIAssistant Agent basiert immer auf automatischen Funktionsaufrufen.

// Factory method to produce an agent with a specific role.
// Could be incorporated into DI initialization.
ChatCompletionAgent CreateSpecificAgent(Kernel kernel, string credentials)
{
    // Clone kernel instance to allow for agent specific plug-in definition
    Kernel agentKernel = kernel.Clone();

    // Import plug-in from type
    agentKernel.ImportPluginFromType<StatelessPlugin>();

    // Import plug-in from object
    agentKernel.ImportPluginFromObject(new StatefulPlugin(credentials));

    // Create the agent
    return
        new ChatCompletionAgent()
        {
            Name = "<agent name>",
            Instructions = "<agent instructions>",
            Kernel = agentKernel,
            Arguments = new KernelArguments(
                new OpenAIPromptExecutionSettings()
                {
                    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
                })
        };
}

Es gibt zwei Möglichkeiten, ein ChatCompletionAgent mit Plugins zu erstellen.

Methode 1: Angeben von Plug-Ins über den Konstruktor

Sie können direkt eine Liste der Plug-Ins an den Konstruktor übergeben:

from semantic_kernel.agents import ChatCompletionAgent

# Create the Chat Completion Agent instance by specifying a list of plugins
agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    instructions="<instructions>",
    plugins=[SamplePlugin()]
)

Tipp

Standardmäßig ist der Aufruf automatischer Funktionen aktiviert. Um es zu deaktivieren, setzen Sie das Argument function_choice_behavior im Konstruktor auf function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=False). Mit dieser Einstellung werden Plug-Ins an das Modell übertragen, aber sie werden nicht automatisch aufgerufen. Wenn Ausführungseinstellungen die gleiche service_id oder ai_model_id wie die AI-Dienstkonfiguration angeben, hat das in den Ausführungseinstellungen (via KernelArguments) definierte Funktionsaufrufverhalten Vorrang vor dem im Konstruktor festgelegten Funktionsauswahlverhalten.

Methode 2: Manuelles Konfigurieren des Kernels

Wenn kein Kernel über den Konstruktor bereitgestellt wird, wird während der Modellüberprüfung automatisch ein Kernel erstellt. Alle Plug-Ins, die übergeben wurden, haben Vorrang und werden dem Kernel hinzugefügt. Führen Sie die folgenden Schritte aus, um eine genauere Kontrolle über den Kernelstatus zu erfahren:

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.kernel import Kernel

# Create the instance of the Kernel
kernel = Kernel()

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

# Get the AI Service settings
settings = kernel.get_prompt_execution_settings_from_service_id()

# Configure the function choice behavior to auto invoke kernel functions
settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

# Add the Plugin to the Kernel
kernel.add_plugin(SamplePlugin(), plugin_name="<plugin name>")

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

Tipp

Wenn bei der Hinzufügung eines Dienstes zum Kernel kein service_id angegeben wird, wird standardmäßig default verwendet. Beim Konfigurieren mehrerer KI-Dienste im Kernel empfiehlt es sich, diese mithilfe des service_id Arguments zu unterscheiden. Auf diese Weise können Sie Ausführungseinstellungen für eine bestimmte Einstellung service_id abrufen und diese Einstellungen an den gewünschten Dienst binden.

var chatCompletion = OpenAIChatCompletion.builder()
    .withModelId("<model-id>")
    .withOpenAIAsyncClient(new OpenAIClientBuilder()
            .credential(new AzureKeyCredential("<api-key>"))
            .endpoint("<endpoint>")
            .buildAsyncClient())
    .build();

Kernel kernel = Kernel.builder()
    .withAIService(ChatCompletionService.class, chatCompletion)
    .withPlugin(KernelPluginFactory.createFromObject(new SamplePlugin(), "<plugin name>"))
    .build();

var agent = ChatCompletionAgent.builder()
    .withKernel(kernel)
    .withName("<agent name>")
    .withInstructions("<agent instructions>")
    .build();

Hinzufügen von Funktionen zu einem Agent

Ein Plug-In ist der am häufigsten verwendete Ansatz zum Konfigurieren von Funktionsaufrufen. Einzelne Funktionen, einschließlich von Aufforderungsfunktionen, können jedoch auch unabhängig bereitgestellt werden.

// Factory method to product an agent with a specific role.
// Could be incorporated into DI initialization.
ChatCompletionAgent CreateSpecificAgent(Kernel kernel)
{
    // Clone kernel instance to allow for agent specific plug-in definition
    Kernel agentKernel = kernel.Clone();

    // Create plug-in from a static function
    var functionFromMethod = agentKernel.CreateFunctionFromMethod(StatelessPlugin.AStaticMethod);

    // Create plug-in from a prompt
    var functionFromPrompt = agentKernel.CreateFunctionFromPrompt("<your prompt instructions>");

    // Add to the kernel
    agentKernel.ImportPluginFromFunctions("my_plugin", [functionFromMethod, functionFromPrompt]);

    // Create the agent
    return
        new ChatCompletionAgent()
        {
            Name = "<agent name>",
            Instructions = "<agent instructions>",
            Kernel = agentKernel,
            Arguments = new KernelArguments(
                new OpenAIPromptExecutionSettings()
                {
                    FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
                })
        };
}

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings
from semantic_kernel.functions import KernelFunctionFromPrompt
from semantic_kernel.kernel import Kernel

# Create the instance of the Kernel
kernel = Kernel()

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

# Create the AI Service settings
settings = AzureChatPromptExecutionSettings()

# Configure the function choice behavior to auto invoke kernel functions
settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

# Add the Plugin to the Kernel
kernel.add_function(
    plugin_name="<plugin_name>",
    function=KernelFunctionFromPrompt(
        function_name="<function_name>",
        prompt="<your prompt instructions>",
    )
)

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

var chatCompletion = OpenAIChatCompletion.builder()
    .withModelId("<model-id>")
    .withOpenAIAsyncClient(new OpenAIClientBuilder()
            .credential(new AzureKeyCredential("<api-key>"))
            .endpoint("<endpoint>")
            .buildAsyncClient())
    .build();

// Create function from method
var functionFromMethod = KernelFunction.createFromMethod(SamplePlugin.class.getMethod("method"), new SamplePlugin());

// Create function from prompt
var functionFromPrompt = KernelFunction.createFromPrompt("<your prompt instructions>");

// Create the kernel with a plugin from the two functions
Kernel kernel = Kernel.builder()
    .withAIService(ChatCompletionService.class, chatCompletion)
    .withPlugin(KernelPluginFactory.createFromFunctions("SamplePlugin", List.of(functionFromMethod, functionFromPrompt)))
    .build();

InvocationContext invocationContext = InvocationContext.builder()
    .withFunctionChoiceBehavior(FunctionChoiceBehavior.auto(true))
    .build();

// Create the agent
var agent = ChatCompletionAgent.builder()
    .withKernel(kernel)
    .withName("<agent name>")
    .withInstructions("<agent instructions>")
    .withInvocationContext(invocationContext)
    .build();

Einschränkungen bei den Aufrufen von Agentenfunktionen

Beim direkten Aufrufen einerChatCompletionAgent Funktion werden alle Funktionsauswahlverhalten unterstützt. Bei der Verwendung eines OpenAIAssistant ist derzeit jedoch nur der automatische Funktionsaufruf verfügbar.

Vorgehensweise

Ein End-to-End-Beispiel für die Verwendung von Funktionsaufrufen finden Sie unter:

Nächste Schritte

So übertragen Sie Agentenantworten

  • Last updated on