Freigeben über

Gewusst wie: Chat-Vervollständigungs-Agent (Experimental)

  • Artikel

Warnung

Das semantische Kernel-Agent-Framework ist experimentell, befindet sich noch in der Entwicklung und unterliegt Änderungen.

Übersicht

In diesem Beispiel werden wir das Konfigurieren eines Plug-Ins für den Zugriff auf die GitHub-API untersuchen und vorlagenisierte Anweisungen für einen Chat-Abschluss-Agent bereitstellen, um Fragen zu einem GitHub-Repository zu beantworten. Der Ansatz wird schrittweise auf ein hohes Licht auf die wichtigsten Teile des Codierungsprozesses aufgeteilt. Als Teil der Aufgabe stellt der Agent Dokumentzitate innerhalb der Antwort bereit.

Streaming wird verwendet, um die Antworten des Agents zu übermitteln. Dadurch werden Echtzeitaktualisierungen bereitgestellt, während der Vorgang fortschreitet.

Erste Schritte

Bevor Sie mit der Featurecodierung fortfahren, stellen Sie sicher, dass Ihre Entwicklungsumgebung vollständig eingerichtet und konfiguriert ist.

Erstellen Sie zunächst ein Konsolenprojekt . Schließen Sie dann die folgenden Paketverweise ein, um sicherzustellen, dass alle erforderlichen Abhängigkeiten verfügbar sind.

Verwenden Sie den dotnet Befehl, um Paketabhängigkeiten aus der Befehlszeile hinzuzufügen:

dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease

Wenn Sie NuGet-Pakete in Visual Studio verwalten, stellen Sie sicher, dass Include prerelease sie aktiviert ist.

Die Projektdatei (.csproj) sollte die folgenden PackageReference Definitionen enthalten:

  <ItemGroup>
    <PackageReference Include="Azure.Identity" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" Version="<stable>" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="<stable>" />
    <PackageReference Include="Microsoft.SemanticKernel.Agents.Core" Version="<latest>" />
    <PackageReference Include="Microsoft.SemanticKernel.Connectors.AzureOpenAI" Version="<latest>" />
  </ItemGroup>

Das Agent Framework ist experimentell und erfordert eine Warnunterdrückung. Dies kann als Eigenschaft in der Projektdatei adressiert werden (.csproj):

  <PropertyGroup>
    <NoWarn>$(NoWarn);CA2007;IDE1006;SKEXP0001;SKEXP0110;OPENAI001</NoWarn>
  </PropertyGroup>

Kopieren Sie außerdem das GitHub-Plug-In und modelle (GitHubPlugin.cs und GitHubModels.cs) aus dem semantischen KernelprojektLearnResources. Fügen Sie diese Dateien in Ihrem Projektordner hinzu.

Erstellen Sie zunächst einen Ordner, der Ihr Skript (.py Datei) und die Beispielressourcen enthält. Fügen Sie die folgenden Importe am Anfang der .py Datei ein:

import asyncio
import os
import sys
from datetime import datetime

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.contents.chat_history import ChatHistory
from semantic_kernel.contents.chat_message_content import ChatMessageContent
from semantic_kernel.contents.utils.author_role import AuthorRole
from semantic_kernel.kernel import Kernel

# Adjust the sys.path so we can use the GitHubPlugin and GitHubSettings classes
# This is so we can run the code from the samples/learn_resources/agent_docs directory
# If you are running code from your own project, you may not need need to do this.
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

from plugins.GithubPlugin.github import GitHubPlugin, GitHubSettings  # noqa: E402

Kopieren Sie außerdem das GitHub-Plug-In und -Modelle (github.py) aus dem semantischen KernelprojektLearnResources. Fügen Sie diese Dateien in Ihrem Projektordner hinzu.

Agents sind derzeit in Java nicht verfügbar.

Konfiguration

In diesem Beispiel ist konfigurationseinstellung erforderlich, um eine Verbindung mit Remotediensten herzustellen. Sie müssen Einstellungen für Open AI oder Azure Open AI und auch für GitHub definieren.

Hinweis: Informationen zu GitHub Personal Access Tokens finden Sie unter: Verwalten Ihrer persönlichen Zugriffstoken.

# Open AI
dotnet user-secrets set "OpenAISettings:ApiKey" "<api-key>"
dotnet user-secrets set "OpenAISettings:ChatModel" "gpt-4o"

# Azure Open AI
dotnet user-secrets set "AzureOpenAISettings:ApiKey" "<api-key>" # Not required if using token-credential
dotnet user-secrets set "AzureOpenAISettings:Endpoint" "<model-endpoint>"
dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o"

# GitHub
dotnet user-secrets set "GitHubSettings:BaseUrl" "https://api.github.com"
dotnet user-secrets set "GitHubSettings:Token" "<personal access token>"

Die folgende Klasse wird in allen Agent-Beispielen verwendet. Achten Sie darauf, sie in Ihr Projekt einzuschließen, um die ordnungsgemäße Funktionalität sicherzustellen. Diese Klasse dient als grundlegende Komponente für die folgenden Beispiele.

using System.Reflection;
using Microsoft.Extensions.Configuration;

namespace AgentsSample;

public class Settings
{
    private readonly IConfigurationRoot configRoot;

    private AzureOpenAISettings azureOpenAI;
    private OpenAISettings openAI;

    public AzureOpenAISettings AzureOpenAI => this.azureOpenAI ??= this.GetSettings<Settings.AzureOpenAISettings>();
    public OpenAISettings OpenAI => this.openAI ??= this.GetSettings<Settings.OpenAISettings>();

    public class OpenAISettings
    {
        public string ChatModel { get; set; } = string.Empty;
        public string ApiKey { get; set; } = string.Empty;
    }

    public class AzureOpenAISettings
    {
        public string ChatModelDeployment { get; set; } = string.Empty;
        public string Endpoint { get; set; } = string.Empty;
        public string ApiKey { get; set; } = string.Empty;
    }

    public TSettings GetSettings<TSettings>() =>
        this.configRoot.GetRequiredSection(typeof(TSettings).Name).Get<TSettings>()!;

    public Settings()
    {
        this.configRoot =
            new ConfigurationBuilder()
                .AddEnvironmentVariables()
                .AddUserSecrets(Assembly.GetExecutingAssembly(), optional: true)
                .Build();
    }
}

Die schnellste Möglichkeit, mit der richtigen Konfiguration zu beginnen, um den Beispielcode auszuführen, besteht darin, eine .env Datei im Stammverzeichnis Ihres Projekts zu erstellen (wo Ihr Skript ausgeführt wird).

Konfigurieren Sie die folgenden Einstellungen in Ihrer .env Datei für Azure OpenAI oder OpenAI:

AZURE_OPENAI_API_KEY="..."
AZURE_OPENAI_ENDPOINT="https://..."
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..."
AZURE_OPENAI_API_VERSION="..."

OPENAI_API_KEY="sk-..."
OPENAI_ORG_ID=""
OPENAI_CHAT_MODEL_ID=""

Nach der Konfiguration werden die entsprechenden KI-Dienstklassen die erforderlichen Variablen abholen und während der Instanziierung verwenden.

Agents sind derzeit in Java nicht verfügbar.

Codieren

Der Codierungsprozess für dieses Beispiel umfasst:

  1. Setup – Initialisieren von Einstellungen und dem Plug-In.
  2. Agentdefinition – Erstellen Sie den Chat-Vervollständigungs-Agent mit templatisierten Anweisungen und Plug-Ins.
  3. Die Chatschleife – Schreiben Sie die Schleife , die die Benutzer-/Agent-Interaktion steuert.

Der vollständige Beispielcode wird im Abschnitt "Final " bereitgestellt. Weitere Informationen finden Sie in diesem Abschnitt für die vollständige Implementierung.

Setup

Vor dem Erstellen eines Chat-Vervollständigungs-Agents müssen die Konfigurationseinstellungen, Plug-Ins und Kernel initialisiert werden.

Initialisieren Sie die Klasse, auf die Settings im vorherigen Konfigurationsabschnitt verwiesen wird.

Settings settings = new();

Agents sind derzeit in Java nicht verfügbar.

Initialisieren Sie das Plug-In mithilfe seiner Einstellungen.

Hier wird eine Meldung angezeigt, um den Fortschritt anzuzeigen.

Console.WriteLine("Initialize plugins...");
GitHubSettings githubSettings = settings.GetSettings<GitHubSettings>();
GitHubPlugin githubPlugin = new(githubSettings);

gh_settings = GitHubSettings(
    token="<PAT value>"
)
kernel.add_plugin(GitHubPlugin(settings=gh_settings), plugin_name="github")

Agents sind derzeit in Java nicht verfügbar.

Initialisieren Sie nun eine Kernel Instanz mit einer IChatCompletionService und der GitHubPlugin zuvor erstellten Instanz.

Console.WriteLine("Creating kernel...");
IKernelBuilder builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
    settings.AzureOpenAI.ChatModelDeployment,
    settings.AzureOpenAI.Endpoint,
    new AzureCliCredential());

builder.Plugins.AddFromObject(githubPlugin);

Kernel kernel = builder.Build();

kernel = Kernel()

# Add the AzureChatCompletion AI Service to the Kernel
service_id = "agent"
kernel.add_service(AzureChatCompletion(service_id=service_id))

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

Agents sind derzeit in Java nicht verfügbar.

Agentdefinition

Schließlich können wir einen Chat-Vervollständigungs-Agent mit den zugehörigen Anweisungen, dem zugeordneten Kernel und den Standardargumenten und Ausführungseinstellungen instanziieren. In diesem Fall möchten wir die Plug-In-Funktionen automatisch ausführen lassen.

Console.WriteLine("Defining agent...");
ChatCompletionAgent agent =
    new()
    {
        Name = "SampleAssistantAgent",
        Instructions =
            """
            You are an agent designed to query and retrieve information from a single GitHub repository in a read-only manner.
            You are also able to access the profile of the active user.

            Use the current date and time to provide up-to-date details or time-sensitive responses.

            The repository you are querying is a public repository with the following name: {{$repository}}

            The current date and time is: {{$now}}. 
            """,
        Kernel = kernel,
        Arguments =
            new KernelArguments(new AzureOpenAIPromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() })
            {
                { "repository", "microsoft/semantic-kernel" }
            }
    };

Console.WriteLine("Ready!");

agent = ChatCompletionAgent(
    service_id="agent",
    kernel=kernel,
    name="SampleAssistantAgent",
    instructions=f"""
        You are an agent designed to query and retrieve information from a single GitHub repository in a read-only 
        manner.
        You are also able to access the profile of the active user.

        Use the current date and time to provide up-to-date details or time-sensitive responses.

        The repository you are querying is a public repository with the following name: microsoft/semantic-kernel

        The current date and time is: {current_time}. 
        """,
    execution_settings=settings,
)

Agents sind derzeit in Java nicht verfügbar.

Die Chatschleife

Schließlich können wir die Interaktion zwischen dem Benutzer und dem Agent koordinieren. Erstellen Sie zunächst ein Chatverlaufsobjekt , um den Unterhaltungsstatus beizubehalten und eine leere Schleife zu erstellen.

ChatHistory history = [];
bool isComplete = false;
do
{
    // processing logic here
} while (!isComplete);

history = ChatHistory()
is_complete: bool = False
while not is_complete:
    # processing logic here

Agents sind derzeit in Java nicht verfügbar.

Lassen Sie uns nun Benutzereingaben innerhalb der vorherigen Schleife erfassen. In diesem Fall wird leere Eingabe ignoriert, und der Ausdruck EXIT signalisiert, dass die Unterhaltung abgeschlossen ist. Gültige Eingaben werden dem Chatverlauf als Benutzernachricht hinzugefügt.

Console.WriteLine();
Console.Write("> ");
string input = Console.ReadLine();
if (string.IsNullOrWhiteSpace(input))
{
    continue;
}
if (input.Trim().Equals("EXIT", StringComparison.OrdinalIgnoreCase))
{
    isComplete = true;
    break;
}

history.Add(new ChatMessageContent(AuthorRole.User, input));

Console.WriteLine();

user_input = input("User:> ")
if not user_input:
    continue

if user_input.lower() == "exit":
    is_complete = True
    break

history.add_message(ChatMessageContent(role=AuthorRole.USER, content=user_input))

Agents sind derzeit in Java nicht verfügbar.

Um eine Agent-Antwort auf Benutzereingaben zu generieren, rufen Sie den Agent mithilfe von Arguments auf, um den endgültigen Vorlagenparameter bereitzustellen, der das aktuelle Datum und die aktuelle Uhrzeit angibt.

Die Agent-Antwort wird dann dem Benutzer angezeigt.

DateTime now = DateTime.Now;
KernelArguments arguments =
    new()
    {
        { "now", $"{now.ToShortDateString()} {now.ToShortTimeString()}" }
    };
await foreach (ChatMessageContent response in agent.InvokeAsync(history, arguments))
{
    Console.WriteLine($"{response.Content}");
}

Demnächst

Agents sind derzeit in Java nicht verfügbar.

Endphase

Alle Schritte zusammenzuführen, haben wir den endgültigen Code für dieses Beispiel. Die vollständige Implementierung wird unten bereitgestellt.

using System;
using System.Threading.Tasks;
using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Plugins;

namespace AgentsSample;

public static class Program
{
    public static async Task Main()
    {
        // Load configuration from environment variables or user secrets.
        Settings settings = new();

        Console.WriteLine("Initialize plugins...");
        GitHubSettings githubSettings = settings.GetSettings<GitHubSettings>();
        GitHubPlugin githubPlugin = new(githubSettings);

        Console.WriteLine("Creating kernel...");
        IKernelBuilder builder = Kernel.CreateBuilder();

        builder.AddAzureOpenAIChatCompletion(
            settings.AzureOpenAI.ChatModelDeployment,
            settings.AzureOpenAI.Endpoint,
            new AzureCliCredential());

        builder.Plugins.AddFromObject(githubPlugin);

        Kernel kernel = builder.Build();

        Console.WriteLine("Defining agent...");
        ChatCompletionAgent agent =
            new()
            {
                Name = "SampleAssistantAgent",
                Instructions =
                        """
                        You are an agent designed to query and retrieve information from a single GitHub repository in a read-only manner.
                        You are also able to access the profile of the active user.

                        Use the current date and time to provide up-to-date details or time-sensitive responses.

                        The repository you are querying is a public repository with the following name: {{$repository}}

                        The current date and time is: {{$now}}. 
                        """,
                Kernel = kernel,
                Arguments =
                    new KernelArguments(new AzureOpenAIPromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() })
                    {
                        { "repository", "microsoft/semantic-kernel" }
                    }
            };

        Console.WriteLine("Ready!");

        ChatHistory history = [];
        bool isComplete = false;
        do
        {
            Console.WriteLine();
            Console.Write("> ");
            string input = Console.ReadLine();
            if (string.IsNullOrWhiteSpace(input))
            {
                continue;
            }
            if (input.Trim().Equals("EXIT", StringComparison.OrdinalIgnoreCase))
            {
                isComplete = true;
                break;
            }

            history.Add(new ChatMessageContent(AuthorRole.User, input));

            Console.WriteLine();

            DateTime now = DateTime.Now;
            KernelArguments arguments =
                new()
                {
                    { "now", $"{now.ToShortDateString()} {now.ToShortTimeString()}" }
                };
            await foreach (ChatMessageContent response in agent.InvokeAsync(history, arguments))
            {
                // Display response.
                Console.WriteLine($"{response.Content}");
            }

        } while (!isComplete);
    }
}

import asyncio
import os
import sys
from datetime import datetime

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.contents.chat_history import ChatHistory
from semantic_kernel.contents.chat_message_content import ChatMessageContent
from semantic_kernel.contents.utils.author_role import AuthorRole
from semantic_kernel.kernel import Kernel

# Adjust the sys.path so we can use the GitHubPlugin and GitHubSettings classes
# This is so we can run the code from the samples/learn_resources/agent_docs directory
# If you are running code from your own project, you may not need need to do this.
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

from plugins.GithubPlugin.github import GitHubPlugin, GitHubSettings  # noqa: E402

###################################################################
# The following sample demonstrates how to create a simple,       #
# ChatCompletionAgent to use a GitHub plugin to interact          #
# with the GitHub API.                                            #
###################################################################


async def main():
    kernel = Kernel()

    # Add the AzureChatCompletion AI Service to the Kernel
    service_id = "agent"
    kernel.add_service(AzureChatCompletion(service_id=service_id))

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

    # Set your GitHub Personal Access Token (PAT) value here
    gh_settings = GitHubSettings(token="<PAT value>")
    kernel.add_plugin(plugin=GitHubPlugin(gh_settings), plugin_name="GithubPlugin")

    current_time = datetime.now().isoformat()

    # Create the agent
    agent = ChatCompletionAgent(
        service_id="agent",
        kernel=kernel,
        name="SampleAssistantAgent",
        instructions=f"""
            You are an agent designed to query and retrieve information from a single GitHub repository in a read-only 
            manner.
            You are also able to access the profile of the active user.

            Use the current date and time to provide up-to-date details or time-sensitive responses.

            The repository you are querying is a public repository with the following name: microsoft/semantic-kernel

            The current date and time is: {current_time}. 
            """,
        execution_settings=settings,
    )

    history = ChatHistory()
    is_complete: bool = False
    while not is_complete:
        user_input = input("User:> ")
        if not user_input:
            continue

        if user_input.lower() == "exit":
            is_complete = True
            break

        history.add_message(ChatMessageContent(role=AuthorRole.USER, content=user_input))

        async for response in agent.invoke(history=history):
            print(f"{response.content}")


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

Agents sind derzeit in Java nicht verfügbar.

How-To: Open AI Assistant Agent Code Interpreter