Implementation:Microsoft Semantic kernel ChatCompletionAgent

Overview

ChatCompletionAgent is the primary agent implementation in Microsoft Semantic Kernel that wraps an IChatCompletionService as an autonomous, named agent with system instructions and optional plugin-based tool calling. It is defined in dotnet/src/Agents/Core/ChatCompletionAgent.cs (lines 26-454) and inherits from the base ChatHistoryKernelAgent class.

This implementation page documents the constructor pattern, properties, and initialization behavior of the ChatCompletionAgent class.

Principle page: Chat Completion Agent Creation

Principle:Microsoft_Semantic_kernel_Chat_Completion_Agent_Creation

Code Reference

Source file: dotnet/src/Agents/Core/ChatCompletionAgent.cs:L26-454

Class Definition

public sealed class ChatCompletionAgent : ChatHistoryKernelAgent
{
    public string? Name { get; set; }
    public string? Instructions { get; set; }
    public Kernel Kernel { get; set; }
    public KernelArguments? Arguments { get; set; }
}

Constructor and Object Initializer

ChatCompletionAgent uses C# object initializer syntax rather than a parameterized constructor. All properties are optional and can be set at initialization time:

ChatCompletionAgent agent = new()
{
    Name = "Parrot",
    Instructions = "Repeat the user message in the voice of a pirate and then end with a parrot sound.",
    Kernel = kernel,
    Arguments = new KernelArguments(executionSettings)
};

Key Properties

Property	Type	Required	Description
Name	string?	No	A human-readable identifier for the agent. Used in multi-agent scenarios to distinguish responses by author.
Instructions	string?	No	The system prompt that defines the agent's personality, constraints, and behavioral guidelines. Prepended as a system message to every invocation.
Kernel	Kernel	Yes (for invocation)	The kernel instance providing the IChatCompletionService and any registered plugins. Must have at least one chat completion service registered.
Arguments	KernelArguments?	No	Execution settings including PromptExecutionSettings that control model behavior (temperature, max tokens, tool choice, etc.).

I/O Contract

Input (Construction)

The ChatCompletionAgent accepts the following during construction:

Input: Object initializer with optional properties
├── Name: string?           → Agent identity label
├── Instructions: string?   → System prompt / behavioral definition
├── Kernel: Kernel          → Service container with IChatCompletionService + plugins
└── Arguments: KernelArguments? → Execution settings (temperature, max_tokens, etc.)

Output (Created Agent)

The constructed agent is a fully configured ChatCompletionAgent instance ready for invocation:

Output: ChatCompletionAgent instance
├── Can be invoked via InvokeAsync(message, thread?, options?)
├── Can be added to orchestrations (Concurrent, GroupChat, Handoff)
├── Plugins accessible via agent.Kernel.Plugins
└── Thread-safe for concurrent invocations across different threads

Internal Behavior on Invocation

When InvokeAsync is called, the agent internally:

1. Retrieves the IChatCompletionService from this.Kernel.
2. Constructs a ChatHistory by prepending Instructions as a system message.
3. Appends the thread's existing messages (if a thread is provided).
4. Appends the new user message.
5. Calls the chat completion service with the assembled history and Arguments.
6. Yields each response item as an AgentResponseItem<ChatMessageContent>.

Usage Examples

Minimal Agent

// Simplest possible agent — uses default settings
ChatCompletionAgent agent = new()
{
    Kernel = kernel
};

Named Agent with Instructions

ChatCompletionAgent agent = new()
{
    Name = "Parrot",
    Instructions = "Repeat the user message in the voice of a pirate and then end with a parrot sound.",
    Kernel = kernel
};

Agent with Execution Settings

ChatCompletionAgent agent = new()
{
    Name = "Analyst",
    Instructions = "You are a data analyst. Provide precise, factual answers with citations.",
    Kernel = kernel,
    Arguments = new KernelArguments(
        new PromptExecutionSettings
        {
            ExtensionData = new Dictionary<string, object>
            {
                ["temperature"] = 0.1,
                ["max_tokens"] = 4096
            }
        })
};

Agent with Plugins Attached

Kernel kernel = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("gpt-4o", apiKey)
    .Build();

// Attach plugins before or after agent creation
kernel.Plugins.Add(KernelPluginFactory.CreateFromType<TimePlugin>());
kernel.Plugins.Add(KernelPluginFactory.CreateFromType<WeatherPlugin>());

ChatCompletionAgent agent = new()
{
    Name = "Assistant",
    Instructions = "You are a helpful assistant. Use available tools to answer questions.",
    Kernel = kernel
};

Multiple Agents for Orchestration

ChatCompletionAgent writer = new()
{
    Name = "Writer",
    Instructions = "You are a creative writer. Produce engaging prose on the given topic.",
    Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
    Name = "Reviewer",
    Instructions = "You are a literary critic. Review the provided text and suggest improvements.",
    Kernel = kernel
};

// Both agents can now be passed to an orchestration
ConcurrentOrchestration orchestration = new(writer, reviewer);

Related Pages

• Chat Completion Agent Creation (Principle) -- The conceptual foundation for agent creation.
• Agent Kernel Plugins Add (Implementation) -- Attaching plugins to an agent's kernel.
• Agent InvokeAsync (Implementation) -- Invoking the created agent.
• ChatHistoryAgentThread (Implementation) -- Managing conversation state for agent invocations.
• Orchestration Patterns (Implementation) -- Using agents in multi-agent orchestrations.

Requires Environment

• Environment:Microsoft_Semantic_kernel_OpenAI_API_Environment

Uses Heuristic

• Heuristic:Microsoft_Semantic_kernel_Experimental_Feature_Opt_In