Condividi tramite

Creare un agente da un modello di kernel semantico

  • Articolo

Importante

Questa funzionalità si trova nella fase di candidato al rilascio. Le funzionalità in questa fase sono quasi complete e generalmente stabili, anche se possono subire miglioramenti o ottimizzazioni minori prima di raggiungere la disponibilità generale completa.

Modelli di prompt nel kernel semantico

Il ruolo di un agente è principalmente modellato dalle istruzioni ricevute, che ne determinano il comportamento e le azioni. Analogamente alla chiamata di un prompt, le istruzioni di un Kernelagente possono includere parametri basato su modelli, sia valori che funzioni, che vengono sostituiti dinamicamente durante l'esecuzione. Ciò consente risposte flessibili e in grado di supportare il contesto, consentendo all'agente di regolare l'output in base all'input in tempo reale.

Inoltre, un agente può essere configurato direttamente usando una configurazione del modello di richiesta, fornendo agli sviluppatori un modo strutturato e riutilizzabile per definirne il comportamento. Questo approccio offre uno strumento potente per la standardizzazione e la personalizzazione delle istruzioni degli agenti, garantendo la coerenza tra vari casi d'uso mantenendo al tempo stesso l'adattabilità dinamica.

Gli agenti non sono attualmente disponibili in Java.

Istruzioni dell'agente come modello

La creazione di un agente con parametri di modello offre maggiore flessibilità consentendo la personalizzazione delle istruzioni in base a scenari o requisiti diversi. Questo approccio consente di personalizzare il comportamento dell'agente sostituendo valori o funzioni specifici nel modello, rendendolo adattabile a un'ampia gamma di attività o contesti. Sfruttando i parametri del modello, gli sviluppatori possono progettare agenti più versatili che possono essere configurati per soddisfare casi d'uso diversi senza dover modificare la logica di base.

Agente di completamento chat

// Initialize a Kernel with a chat-completion service
Kernel kernel = ...;

ChatCompletionAgent agent =
    new()
    {
        Kernel = kernel,
        Name = "StoryTeller",
        Instructions = "Tell a story about {{$topic}} that is {{$length}} sentences long.",
        Arguments = new KernelArguments()
        {
            { "topic", "Dog" },
            { "length", "3" },
        }
    };

agent = ChatCompletionAgent(
    service=AzureChatCompletion(), # or other supported AI Services
    name="StoryTeller",
    instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.",
    arguments=KernelArguments(topic="Dog", length="2"),
)

Gli agenti non sono attualmente disponibili in Java.

Agente assistente OpenAI

Le istruzioni basate su modelli sono particolarmente potenti quando si utilizzano con un oggetto OpenAIAssistantAgent. Con questo approccio, è possibile creare e riutilizzare più volte una singola definizione di assistente, ogni volta con valori di parametro diversi personalizzati per attività o contesti specifici. Ciò consente una configurazione più efficiente, consentendo allo stesso framework assistente di gestire un'ampia gamma di scenari mantenendo al tempo stesso la coerenza nel comportamento principale.

// Retrieve an existing assistant definition by identifier
AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri("<your endpoint>"));
AssistantClient assistantClient = client.GetAssistantClient();
Assistant assistant = await client.GetAssistantAsync();
OpenAIAssistantAgent agent = new(assistant, assistantClient, new KernelPromptTemplateFactory(), PromptTemplateConfig.SemanticKernelTemplateFormat)
{
    Arguments = new KernelArguments()
    {
        { "topic", "Dog" },
        { "length", "3" },
    }
}

# Create the client using Azure OpenAI resources and configuration
client, model = AzureAssistantAgent.setup_resources()

# Retrieve the assistant definition from the server based on the assistant ID
definition = await client.beta.assistants.retrieve(
    assistant_id="your-assistant-id",
)

# Create the AzureAssistantAgent instance using the client and the assistant definition
agent = AzureAssistantAgent(
    client=client,
    definition=definition,
    arguments=KernelArguments(topic="Dog", length="3"),
)

Gli agenti non sono attualmente disponibili in Java.

Definizione dell'agente da un modello di prompt

La stessa configurazione del modello di richiesta usata per creare una funzione prompt del kernel può essere usata anche per definire un agente. Ciò consente un approccio unificato nella gestione di richieste e agenti, promuovendo la coerenza e il riutilizzo tra componenti diversi. Esternalizzando le definizioni degli agenti dalla codebase, questo metodo semplifica la gestione di più agenti, semplificando l'aggiornamento e la gestione senza richiedere modifiche alla logica sottostante. Questa separazione migliora anche la flessibilità, consentendo agli sviluppatori di modificare il comportamento dell'agente o introdurre nuovi agenti semplicemente aggiornando la configurazione, invece di modificare il codice stesso.

Modello YAML

name: GenerateStory
template: |
  Tell a story about {{$topic}} that is {{$length}} sentences long.
template_format: semantic-kernel
description: A function that generates a story about a topic.
input_variables:
  - name: topic
    description: The topic of the story.
    is_required: true
  - name: length
    description: The number of sentences in the story.
    is_required: true

Inizializzazione dell'agente

// Read YAML resource
string generateStoryYaml = File.ReadAllText("./GenerateStory.yaml");
// Convert to a prompt template config
PromptTemplateConfig templateConfig = KernelFunctionYaml.ToPromptTemplateConfig(generateStoryYaml);

// Create agent with Instructions, Name and Description 
// provided by the template config.
ChatCompletionAgent agent =
    new(templateConfig)
    {
        Kernel = this.CreateKernelWithChatCompletion(),
        // Provide default values for template parameters
        Arguments = new KernelArguments()
        {
            { "topic", "Dog" },
            { "length", "3" },
        }
    };

import yaml

from semantic_kernel.prompt_template import PromptTemplateConfig

# Read the YAML file
with open("./GenerateStory.yaml", "r", encoding="utf-8") as file:
    generate_story_yaml = file.read()

# Parse the YAML content
data = yaml.safe_load(generate_story_yaml)

# Use the parsed data to create a PromptTemplateConfig object
prompt_template_config = PromptTemplateConfig(**data)

agent = ChatCompletionAgent(
    service=AzureChatCompletion(), # or other supported AI services
    prompt_template_config=prompt_template_config,
    arguments=KernelArguments(topic="Dog", length="3"),
)

Gli agenti non sono attualmente disponibili in Java.

Sovrascrittura dei valori del modello per la chiamata diretta

Quando si richiama direttamente un agente, senza usare AgentChat, i parametri dell'agente possono essere sottoposti a override in base alle esigenze. Ciò consente un maggiore controllo e personalizzazione del comportamento dell'agente durante attività specifiche, consentendo di modificarne le istruzioni o le impostazioni in tempo reale in base a requisiti specifici.

// Initialize a Kernel with a chat-completion service
Kernel kernel = ...;

ChatCompletionAgent agent =
    new()
    {
        Kernel = kernel,
        Name = "StoryTeller",
        Instructions = "Tell a story about {{$topic}} that is {{$length}} sentences long.",
        Arguments = new KernelArguments()
        {
            { "topic", "Dog" },
            { "length", "3" },
        }
    };

// Create a ChatHistory object to maintain the conversation state.
ChatHistory chat = [];

KernelArguments overrideArguments =
    new()
    {
        { "topic", "Cat" },
        { "length", "3" },
    });

// Generate the agent response(s)
await foreach (ChatMessageContent response in agent.InvokeAsync(chat, overrideArguments))
{
  // Process agent response(s)...
}

agent = ChatCompletionAgent(
    service=AzureChatCompletion(),
    name="StoryTeller",
    instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.",
    arguments=KernelArguments(topic="Dog", length="2"),
)

# Create a chat history to maintain the conversation state
chat = ChatHistory()

override_arguments = KernelArguments(topic="Cat", length="3")

# Two ways to get a response from the agent

# Get the response which returns a ChatMessageContent directly
response = await agent.get_response(chat, arguments=override_arguments)

# or use the invoke method to return an AsyncIterable of ChatMessageContent
async for response in agent.invoke(chat, arguments=override_arguments):
    # process agent response(s)...

Gli agenti non sono attualmente disponibili in Java.

Guida

Per un esempio end-to-end per la creazione di un agente da un modello di prompt, vedi:

Configurazione degli agenti con plug-in