Dela via

Konfigurera agenter med semantiska kernel-plugin-program

Viktigt!

Den här funktionen är i release candidate-stadiet. Funktionerna i det här skedet är nästan fullständiga och i allmänhet stabila, även om de kan genomgå mindre förbättringar eller optimeringar innan de når full allmän tillgänglighet.

Funktioner och plugin-program i semantisk kernel

Funktionsanrop är ett kraftfullt verktyg som gör det möjligt för utvecklare att lägga till anpassade funktioner och utöka funktionerna i AI-program. Den semantiska kernel-plugin-arkitekturen erbjuder ett flexibelt ramverk som stöder funktionsanrop. För en Agentbygger integreringen av plugin-program och funktionsanrop på den här grundläggande semantiska kernelfunktionen.

När den har konfigurerats väljer en agent när och hur en tillgänglig funktion ska anropas, precis som vid all användning utanför Agent Framework.

Tips/Råd

API-referens:

Tips/Råd

API-referens:

Tips/Råd

API-referens:

Lägga till plugin-program i en agent

Alla plugin-program som är tillgängliga för en Agent hanteras i respektive Kernel instans. Den här konfigurationen gör det möjligt för var och Agent en att komma åt distinkta funktioner baserat på dess specifika roll.

Plugins kan läggas till Kernel antingen före eller efter att den har Agent skapats. Processen för att initiera plugin-program följer samma mönster som används för alla semantiska kernelimplementeringar, vilket möjliggör konsekvens och användarvänlighet vid hantering av AI-funktioner.

Anmärkning

För en ChatCompletionAgentmåste funktionsanropsläget vara explicit aktiverat. OpenAIAssistant agenten baseras alltid på automatiska funktionsanrop.

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

Det finns två sätt att skapa ett ChatCompletionAgent med plugin-program.

Metod 1: Ange plugin-program via konstruktorn

Du kan skicka en lista med plugin-program direkt till konstruktorn:

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

Tips/Råd

Som standard är automatiskt funktionsanrop aktiverat. Om du vill inaktivera det anger du function_choice_behavior argumentet till function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=False) i konstruktorn. Med den här inställningen sänds plugin-program till modellen, men de anropas inte automatiskt. Om körningsinställningarna anger samma service_id eller ai_model_id som AI-tjänstkonfigurationen har funktionsanropsbeteendet som definierats i körningsinställningarna (via KernelArguments) företräde framför funktionsvalsbeteendet som anges i konstruktorn.

Metod 2: Konfigurera kerneln manuellt

Om ingen kernel tillhandahålls via konstruktorn skapas en automatiskt under modellverifieringen. Alla plugin-program som skickas har företräde och läggs till i kerneln. Följ dessa steg för mer detaljerad kontroll över kernelns tillstånd:

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

Tips/Råd

Om en service_id inte anges när du lägger till en tjänst i kerneln är standardvärdet default. När du konfigurerar flera AI-tjänster i kerneln rekommenderar vi att du särskiljer dem med argumentet service_id . På så sätt kan du hämta körningsinställningar för en specifik service_id och koppla dessa inställningar till önskad tjänst.

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

Lägga till funktioner i en agent

Ett plugin-program är den vanligaste metoden för att konfigurera funktionsanrop. Enskilda funktioner kan dock också tillhandahållas oberoende av varandra, inklusive promptfunktioner.

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

Begränsningar för agentfunktionsanrop

När du anropar enChatCompletionAgent direkt stöds alla funktionsvalsbeteenden. Men när du använder ett OpenAIAssistant, är endast automatiska funktionsanrop tillgängliga för närvarande.

Så gör du

Ett exempel från slutpunkt till slutpunkt för att använda funktionsanrop finns i:

Nästa steg

Så här strömmar du agentsvar