Handleiding: Chatvoltooiingsagent

Waarschuwing

De Semantic Kernel Agent Framework bevindt zich in preview en kan worden gewijzigd.

Overzicht

In dit voorbeeld verkennen we het configureren van een invoegtoepassing voor toegang tot de GitHub-API en geven we templatized instructies voor een chatvoltooiingsagent om vragen over een GitHub-opslagplaats te beantwoorden. De aanpak wordt stapsgewijs uitgesplitst om de belangrijkste onderdelen van het coderingsproces te verlichten. Als onderdeel van de taak levert de agent documentvermeldingen in het antwoord.

Streaming wordt gebruikt om de antwoorden van de agent te leveren. Dit biedt realtime-updates wanneer de taak vordert.

Aan de slag

Voordat u doorgaat met functiecodering, moet u ervoor zorgen dat uw ontwikkelomgeving volledig is ingesteld en geconfigureerd.

Begin met het maken van een consoleproject . Neem vervolgens de volgende pakketverwijzingen op om ervoor te zorgen dat alle vereiste afhankelijkheden beschikbaar zijn.

Gebruik de dotnet opdracht om pakketafhankelijkheden toe te voegen vanaf de opdrachtregel:

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

Als u NuGet-pakketten beheert in Visual Studio, controleert u of Include prerelease deze optie is ingeschakeld.

Het projectbestand (.csproj) moet de volgende PackageReference definities bevatten:

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

Het Agent Framework is experimenteel en vereist waarschuwingsonderdrukking. Dit kan worden verwerkt als een eigenschap in het projectbestand (.csproj):

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

Kopieer bovendien de GitHub-invoegtoepassing en -modellen (GitHubPlugin.csen) uitLearnResources. Voeg deze bestanden toe aan uw projectmap.

Begin met het maken van een map die uw script (.py bestand) en de voorbeeldbronnen bevat. Neem de volgende importbewerkingen boven aan het .py bestand op:

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
from semantic_kernel.functions.kernel_arguments import KernelArguments

# 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

Kopieer bovendien de GitHub-invoegtoepassing en -modellen (github.py) uit Semantic KernelLearnResources Project. Voeg deze bestanden toe aan uw projectmap.

Agents zijn momenteel niet beschikbaar in Java.

Configuratie

Voor dit voorbeeld is een configuratie-instelling vereist om verbinding te maken met externe services. U moet instellingen definiëren voor Open AI of Azure Open AI en ook voor GitHub.

Opmerking: Zie voor informatie over persoonlijke GitHub-toegangstokens: Uw persoonlijke toegangstokens beheren.

# 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>"

De volgende klasse wordt gebruikt in alle agentvoorbeelden. Zorg ervoor dat u deze in uw project opneemt om de juiste functionaliteit te garanderen. Deze klasse fungeert als een fundamenteel onderdeel voor de volgende voorbeelden.

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();
    }
}

De snelste manier om aan de slag te gaan met de juiste configuratie om de voorbeeldcode uit te voeren, is door een .env bestand te maken in de hoofdmap van uw project (waar uw script wordt uitgevoerd).

Configureer de volgende instellingen in uw .env bestand voor Azure OpenAI of 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=""

Zodra deze zijn geconfigureerd, worden de vereiste variabelen door de respectieve AI-serviceklassen opgehaald en gebruikt tijdens het instantiëring.

Agents zijn momenteel niet beschikbaar in Java.

Coderen

Het coderingsproces voor dit voorbeeld omvat:

1. Setup : instellingen en de invoegtoepassing initialiseren.
2. Agentdefinitie: maak de agent voor chatvoltooiing met templatized instructies en plug-in.
3. De chatlus: schrijf de lus die de interactie van de gebruiker/agent aanstuurt.

De volledige voorbeeldcode wordt weergegeven in de sectie Definitief . Raadpleeg deze sectie voor de volledige implementatie.

Instellingen

Voordat u een chatvoltooiingsagent maakt, moeten de configuratie-instellingen, invoegtoepassingen en kernel worden geïnitialiseerd.

Initialiseer de Settings klasse waarnaar wordt verwezen in de vorige sectie Configuratie .

Settings settings = new();

Agents zijn momenteel niet beschikbaar in Java.

Initialiseer de invoegtoepassing met behulp van de instellingen.

Hier wordt een bericht weergegeven om de voortgang aan te geven.

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 zijn momenteel niet beschikbaar in Java.

Initialiseer nu een Kernel exemplaar met een IChatCompletionService en de GitHubPlugin eerder gemaakte instantie.

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 zijn momenteel niet beschikbaar in Java.

Agentdefinitie

Ten slotte zijn we klaar om een chatvoltooiingsagent te instantiëren met de instructies, de bijbehorende kernel en de standaardargumentenen uitvoeringsinstellingen. In dit geval willen we dat de invoegtoepassingsfuncties automatisch worden uitgevoerd.

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: {{$now}}. 
        """,
    arguments=KernelArguments(
        settings=AzureAIPromptExecutionSettings(function_choice_behavior=FunctionChoiceBehavior.Auto()),
        repository="microsoft/semantic-kernel",
    ),
)

Agents zijn momenteel niet beschikbaar in Java.

De chatlus

Ten slotte kunnen we de interactie tussen de gebruiker en de agent coördineren. Begin met het maken van een chatgeschiedenisobject om de gespreksstatus te behouden en een lege lus te maken.

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 zijn momenteel niet beschikbaar in Java.

We gaan nu gebruikersinvoer vastleggen in de vorige lus. In dit geval wordt lege invoer genegeerd en wordt de term EXIT aangegeven dat het gesprek is voltooid. Geldige invoer wordt als gebruikersberichttoegevoegd aan de chatgeschiedenis.

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 zijn momenteel niet beschikbaar in Java.

Als u een agentreactie op gebruikersinvoer wilt genereren, roept u de agent aan met behulp van argumenten om de laatste sjabloonparameter op te geven waarmee de huidige datum en tijd worden opgegeven.

Het antwoord van de agent wordt vervolgens aan de gebruiker weergegeven.

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}");
}

from datetime import datetime

arguments = KernelArguments(
    now=datetime.now().strftime("%Y-%m-%d %H:%M")
)

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

Agents zijn momenteel niet beschikbaar in Java.

Definitief

Als u alle stappen samenbrengt, hebben we de uiteindelijke code voor dit voorbeeld. Hieronder vindt u de volledige implementatie.

Probeer deze voorgestelde invoer te gebruiken:

1. Wat is mijn gebruikersnaam?
2. Beschrijf de repository.
3. Beschrijf het nieuwste probleem dat in de repository is aangemaakt.
4. Vermeld de tien belangrijkste problemen die in de afgelopen week zijn gesloten.
5. Hoe zijn deze problemen gelabeld?
6. Vermeld de vijf meest recent geopende problemen met het label Agents

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.functions.kernel_arguments import KernelArguments
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")

    # 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: {{$now}}. 
            """,
        arguments=KernelArguments(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))

        arguments = KernelArguments(
            now=datetime.now().strftime("%Y-%m-%d %H:%M")
        )

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


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

Agents zijn momenteel niet beschikbaar in Java.

Procedure: Code-interpreter voor ai-assistentagent openen