Criar um agente a partir de um modelo de kernel semântico

Importante

Este recurso está na fase de candidato a lançamento. Os recursos neste estágio estão quase completos e geralmente estáveis, embora possam passar por pequenos refinamentos ou otimizações antes de atingir a disponibilidade geral total.

Modelos de Comando no Semantic Kernel

O papel de um agente é principalmente moldado pelas instruções que recebe, que ditam o seu comportamento e ações. Semelhante a invocar um Kernelprompt, as instruções de um agente podem incluir parâmetros de modelo — valores e funções — que são substituídos dinamicamente durante a execução. Isso permite respostas flexíveis e sensíveis ao contexto, permitindo que o agente ajuste sua saída com base na entrada em tempo real.

Além disso, um agente pode ser configurado diretamente usando uma Configuração de Modelo de Prompt, fornecendo aos desenvolvedores uma maneira estruturada e reutilizável de definir seu comportamento. Essa abordagem oferece uma ferramenta poderosa para padronizar e personalizar as instruções do agente, garantindo a consistência em vários casos de uso e, ao mesmo tempo, mantendo a adaptabilidade dinâmica.

APIs relacionadas:

• PromptTemplateConfig
• KernelFunctionYaml.FromPromptYaml
• IPromptTemplateFactory
• KernelPromptTemplateFactory
• Guiador
• Prontidão
• Líquido

• prompt_template_config
• kernel_prompt_template
• jinja2_prompt_template
• handlebars_prompt_template

Os agentes estão atualmente indisponíveis em Java.

Instruções do agente como modelo

A criação de um agente com parâmetros de modelo oferece maior flexibilidade, permitindo que suas instruções sejam facilmente personalizadas com base em diferentes cenários ou requisitos. Essa abordagem permite que o comportamento do agente seja adaptado substituindo valores ou funções específicas no modelo, tornando-o adaptável a uma variedade de tarefas ou contextos. Ao aproveitar os parâmetros do modelo, os desenvolvedores podem projetar agentes mais versáteis que podem ser configurados para atender a diversos casos de uso sem a necessidade de modificar a lógica principal.

Agente de conclusão de bate-papo

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

Os agentes estão atualmente indisponíveis em Java.

Agente Assistente da OpenAI

As instruções pré-definidas são especialmente poderosas ao trabalhar com um OpenAIAssistantAgent. Com esta abordagem, uma única definição de assistente pode ser criada e reutilizada várias vezes, cada vez com diferentes valores de parâmetros adaptados a tarefas ou contextos específicos. Isso possibilita uma configuração mais eficiente, permitindo que a mesma estrutura de assistente virtual se encarregue de uma ampla gama de cenários, enquanto mantém a consistência no seu comportamento essencial.

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

Os agentes estão atualmente indisponíveis em Java.

Definição de agente a partir de um modelo de prompt

A mesma configuração de modelo de prompt usada para criar uma função de prompt do kernel também pode ser aproveitada para definir um agente. Isso permite uma abordagem unificada no gerenciamento de prompts e agentes, promovendo consistência e reutilização entre diferentes componentes. Ao externalizar as definições de agente da base de código, esse método simplifica o gerenciamento de vários agentes, tornando-os mais fáceis de atualizar e manter sem exigir alterações na lógica subjacente. Essa separação também aumenta a flexibilidade, permitindo que os desenvolvedores modifiquem o comportamento do agente ou introduzam novos agentes simplesmente atualizando a configuração, em vez de ajustar o código em si.

Modelo 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

Inicialização do 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"),
)

Os agentes estão atualmente indisponíveis em Java.

Sobrepondo os valores do modelo para invocação direta

Ao invocar um agente diretamente, sem usar AgentChat, os parâmetros do agente podem ser substituídos conforme necessário. Isso permite um maior controle e personalização do comportamento do agente durante tarefas específicas, permitindo que você modifique suas instruções ou configurações em tempo real para atender a requisitos específicos.

// 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)...

Os agentes estão atualmente indisponíveis em Java.

Procedimentos

Para obter um exemplo completo de criação de um agente a partir de um modelo de prompt , consulte:

• Como fazer: ChatCompletionAgent

Configurando agentes com plug-ins