Exploring the Semantic Kernel ChatCompletionAgent

• ChatCompletionAgent
• Microsoft.SemanticKernel.Agents
• IChatCompletionService
• Microsoft.SemanticKernel.ChatCompletion

• ChatCompletionAgent

Agents are currently unavailable in Java.

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:

• AzureChatCompletion
• OpenAIChatCompletion

Agents are currently unavailable in Java.

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

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

Install the semantic-kernel package:

pip install semantic-kernel

Agents are currently unavailable in Java.

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

There are two ways to create a ChatCompletionAgent:

1. By providing the chat completion service directly:

# Create the agent by directly providing the chat completion service
agent = ChatCompletionAgent(
    service=AzureChatCompletion(),  # your chat completion service instance
    name="<agent name>",
    instructions="<agent instructions>",
)

2. By creating a Kernel first, adding the service to it, then providing the kernel:

# Define the kernel
kernel = Kernel()

# Add the chat completion service to the kernel
kernel.add_service(AzureChatCompletion())

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

The first method is useful when you already have a chat completion service ready. The second method is beneficial when you need a kernel that manages multiple services or additional functionalities.

Agents are currently unavailable in Java.

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

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

Agents are currently unavailable in Java.

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

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)

Agents are currently unavailable in Java.