Skip to content

chat-completion-agent.md

Latest commit

 

History

History
313 lines (213 loc) · 9.78 KB

chat-completion-agent.md

File metadata and controls

313 lines (213 loc) · 9.78 KB
title Exploring the Semantic Kernel ChatCompletionAgent
description An exploration of the definition, behaviors, and usage patterns for a Chat Completion Agent
zone_pivot_groups programming-languages
author crickman
ms.topic tutorial
ms.author crickman
ms.date 09/13/2024
ms.service semantic-kernel

Exploring the Semantic Kernel ChatCompletionAgent

Important

This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability.

Detailed API documentation related to this discussion is available at:

::: zone pivot="programming-language-csharp"

::: zone-end

::: zone pivot="programming-language-python"

::: zone-end

::: zone pivot="programming-language-java"

Agents are currently unavailable in Java.

::: zone-end

Chat Completion in Semantic Kernel

Chat Completion is fundamentally a protocol for a chat-based interaction with an AI model where the chat-history maintained and presented to the model with each request. Semantic Kernel AI services offer a unified framework for integrating the chat-completion capabilities of various AI models.

A chat completion agent can leverage any of these AI services to generate responses, whether directed to a user or another agent.

::: zone pivot="programming-language-csharp"

For .NET, chat-completion AI Services are based on the IChatCompletionService interface.

For .NET, some of AI services that support models with chat-completion include:

Model Semantic Kernel AI Service
Azure OpenAI Microsoft.SemanticKernel.Connectors.AzureOpenAI
Gemini Microsoft.SemanticKernel.Connectors.Google
HuggingFace Microsoft.SemanticKernel.Connectors.HuggingFace
Mistral Microsoft.SemanticKernel.Connectors.MistralAI
OpenAI Microsoft.SemanticKernel.Connectors.OpenAI
Onnx Microsoft.SemanticKernel.Connectors.Onnx

::: zone-end

::: zone pivot="programming-language-python"

::: zone-end

::: zone pivot="programming-language-java"

Agents are currently unavailable in Java.

::: zone-end

Preparing Your Development Environment

To proceed with developing an AzureAIAgent, configure your development environment with the appropriate packages.

::: zone pivot="programming-language-csharp"

Add the Microsoft.SemanticKernel.Agents.Core package to your project:

dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease

::: zone-end

::: zone pivot="programming-language-python"

Install the semantic-kernel package:

pip install semantic-kernel

::: zone-end

::: zone pivot="programming-language-java"

Agents are currently unavailable in Java.

::: zone-end

Creating a ChatCompletionAgent

A chat completion agent is fundamentally based on an AI services. As such, creating an chat completion agent starts with creating a Kernel instance that contains one or more chat-completion services and then instantiating the agent with a reference to that Kernel instance.

::: zone pivot="programming-language-csharp"

// Initialize a Kernel with a chat-completion service
IKernelBuilder builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(/*<...configuration parameters>*/);

Kernel kernel = builder.Build();

// Create the agent
ChatCompletionAgent agent =
    new()
    {
        Name = "SummarizationAgent",
        Instructions = "Summarize user input",
        Kernel = kernel
    };

::: zone-end

::: zone pivot="programming-language-python"

# Define the Kernel
kernel = Kernel()

# Add the AzureChatCompletion AI Service to the Kernel
kernel.add_service(AzureChatCompletion())

# Create the agent
agent = ChatCompletionAgent(
  kernel=kernel, 
  name="<agent name>", 
  instructions="<agent instructions>",
)

::: zone-end

::: zone pivot="programming-language-java"

Agents are currently unavailable in Java.

::: zone-end

AI Service Selection

No different from using Semantic Kernel AI services directly, a ChatCompletionAgent supports the specification of a service-selector. A service-selector identifies which AI service to target when the Kernel contains more than one.

Note: If multiple AI services are present and no service-selector is provided, the same default logic is applied for the agent that you'd find when using an AI services outside of the Agent Framework

::: zone pivot="programming-language-csharp"

IKernelBuilder builder = Kernel.CreateBuilder();

// Initialize multiple chat-completion services.
builder.AddAzureOpenAIChatCompletion(/*<...service configuration>*/, serviceId: "service-1");
builder.AddAzureOpenAIChatCompletion(/*<...service configuration>*/, serviceId: "service-2");

Kernel kernel = builder.Build();

ChatCompletionAgent agent =
    new()
    {
        Name = "<agent name>",
        Instructions = "<agent instructions>",
        Kernel = kernel,
        Arguments = // Specify the service-identifier via the KernelArguments
          new KernelArguments(
            new OpenAIPromptExecutionSettings() 
            { 
              ServiceId = "service-2" // The target service-identifier.
            });
    };

::: zone-end

::: zone pivot="programming-language-python"

from semantic_kernel.connectors.ai.open_ai import (
    AzureChatCompletion,
    AzureChatPromptExecutionSettings,
)

# Define the Kernel
kernel = Kernel()

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

settings = AzureChatPromptExecutionSettings(service_id="service2")

# Create the agent
agent = ChatCompletionAgent(
  kernel=kernel, 
  name="<agent name>", 
  instructions="<agent instructions>",
  arguments=KernelArguments(settings=settings)
)

::: zone-end

::: zone pivot="programming-language-java"

Agents are currently unavailable in Java.

::: zone-end

Conversing with ChatCompletionAgent

::: zone pivot="programming-language-csharp"

Conversing with your ChatCompletionAgent is based on a ChatHistory instance, no different from interacting with a Chat Completion AI service.

// Define agent
ChatCompletionAgent agent = ...;

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

// Add a user message to the conversation
chat.Add(new ChatMessageContent(AuthorRole.User, "<user input>"));

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

::: zone-end

::: zone pivot="programming-language-python"

There are multiple ways to converse with a ChatCompletionAgent.

The easiest is to call and await get_response:

# Define agent
agent = ChatCompletionAgent(...)
  
# Define the chat history
chat = ChatHistory()

# Add the user message
chat.add_user_message(user_input)
# Generate the agent response
response = await agent.get_response(chat)
# response is a `ChatMessageContent` object

Otherwise, calling the invoke method returns an AsyncIterable of ChatMessageContent.

# Define agent
agent = ChatCompletionAgent(...)
  
# Define the chat history
chat = ChatHistory()

# Add the user message
chat.add_user_message(user_input)

# Generate the agent response(s)
async for response in agent.invoke(chat):
  # process agent response(s)

The ChatCompletionAgent also supports streaming in which the invoke_stream method returns an AsyncIterable of StreamingChatMessageContent:

# Define agent
agent = ChatCompletionAgent(...)
  
# Define the chat history
chat = ChatHistory()

# Add the user message
chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=input))

# Generate the agent response(s)
async for response in agent.invoke_stream(chat):
  # process agent response(s)

::: zone-end

::: zone pivot="programming-language-java"

Agents are currently unavailable in Java.

::: zone-end

How-To:

For an end-to-end example for a ChatCompletionAgent, see:

[!div class="nextstepaction"] Exploring the OpenAI Assistant Agent