ChatCompletionAgent Class

A Chat Completion Agent based on ChatCompletionClientBase. Features marked with this status are nearing completion and are considered stable for most purposes, but may still incur minor refinements or optimizations before achieving full general availability. Initialize a new instance of ChatCompletionAgent, specifying optional arguments including custom instructions, description, function choice behaviors, and a ChatCompletionClientBase service for specialized AI completions.

Constructor

ChatCompletionAgent(
  *,
  arguments: KernelArguments | None = None,
  description: str | None = None,
  function_choice_behavior: FunctionChoiceBehavior | None = None,
  id: str | None = None,
  instructions: str | None = None,
  kernel: Kernel | None = None,
  name: str | None = None,
  plugins: list[KernelPlugin | object] | dict[str, KernelPlugin | object] | None = None,
  prompt_template_config: PromptTemplateConfig | None = None,
  service: ChatCompletionClientBase | None = None
)

Parameters

Name	Description
arguments	The kernel arguments for the agent. Invoke method arguments take precedence over those provided here.
description	The description of the agent.
function_choice_behavior	Controls how the model may discover or call functions. Determines how and which plugins are advertised to the model.
id	The unique identifier for this agent. If not provided, a new GUID is auto-generated.
instructions	Instructions or guidelines for the agent. May override prompt_template_config if conflicting.
kernel	The Kernel instance. If both kernel and service are supplied and share a matching service_id or ai_model_id, the service has precedence. Otherwise the first registered AI service is used.
name	The friendly name of the agent.
plugins	A list or dict of plugins to add. If the kernel is also provided, these plugins overwrite or extend the existing ones.
prompt_template_config	The prompt template config. If instructions are also supplied, the template in this config takes precedence.
service	The ChatCompletionClientBase instance for specialized AI completions. If also present in the kernel with the same ID, it takes precedence.

Methods

configure_service	Configure or validate that the provided ChatCompletionClientBase is properly assigned to the kernel for usage.
create_channel	Create a ChatHistoryChannel bound to a specialized ChatHistoryAgentThread, optionally providing an existing ChatHistory object or a thread ID.
get_response	Get a response from the agent in non-streaming mode. Collects the final ChatMessageContent after processing all intermediate steps.
invoke	Invoke the agent in non-streaming mode, returning intermediate ChatMessageContent results as they become available in an async iterable.
invoke_stream	Invoke the agent in streaming mode, returning tokens or partial results as an async stream of StreamingChatMessageContent items.

configure_service

Configure or validate that the provided ChatCompletionClientBase is properly assigned to the kernel for usage.

configure_service() -> ChatCompletionAgent

Returns

Type	Description
	This instance, enabling fluent chaining.

create_channel

Create a ChatHistoryChannel bound to a specialized ChatHistoryAgentThread, optionally providing an existing ChatHistory object or a thread ID.

async create_channel(chat_history: ChatHistory | None = None, thread_id: str | None = None) -> AgentChannel

Parameters

Name	Description
chat_history	The chat history object for the channel, or None for a new ChatHistory. Default value: None
thread_id	The ID of the thread, or None to create a new one. Default value: None

Returns

Type	Description
	A newly created AgentChannel specialized for chat-based interactions.

get_response

Get a response from the agent in non-streaming mode. Collects the final ChatMessageContent after processing all intermediate steps.

async get_response(
  *,
  messages: str | ChatMessageContent | list[str | ChatMessageContent] | None = None,
  thread: AgentThread | None = None,
  arguments: KernelArguments | None = None,
  kernel: Kernel | None = None,
  **kwargs: Any
) -> AgentResponseItem[ChatMessageContent]

Parameters

Name	Description
messages	The input user content(s) for the conversation. Default value: None
thread	The specific ChatHistoryAgentThread, if any. Default value: None
arguments	Kernel arguments to override or extend agent defaults. Default value: None
kernel	The kernel instance to use. Default value: None
kwargs	Additional overrides or configuration for advanced usage.

Returns

Type	Description
	An AgentResponseItem containing the final ChatMessageContent from the model.

invoke

Invoke the agent in non-streaming mode, returning intermediate ChatMessageContent results as they become available in an async iterable.

async invoke(
  *,
  messages: str | ChatMessageContent | list[str | ChatMessageContent] | None = None,
  thread: AgentThread | None = None,
  arguments: KernelArguments | None = None,
  kernel: Kernel | None = None,
  **kwargs: Any
) -> AsyncIterable[AgentResponseItem[ChatMessageContent]]

Parameters

Name	Description
messages	The initial user content or sequence of messages. Default value: None
thread	The ChatHistoryAgentThread controlling the conversation context. Default value: None
arguments	Agent or model arguments. Default value: None
kernel	The kernel instance to use. Default value: None
kwargs	Optional advanced overrides or configuration.

Returns

Type	Description
	An async stream of AgentResponseItems containing ChatMessageContent, representing incremental conversation or tool invocation steps.

invoke_stream

Invoke the agent in streaming mode, returning tokens or partial results as an async stream of StreamingChatMessageContent items.

async invoke_stream(
  *,
  messages: str | ChatMessageContent | list[str | ChatMessageContent] | None = None,
  thread: AgentThread | None = None,
  arguments: KernelArguments | None = None,
  kernel: Kernel | None = None,
  **kwargs: Any
) -> AsyncIterable[AgentResponseItem[StreamingChatMessageContent]]

Parameters

Name	Description
messages	The user input(s) for the conversation or a list of messages. Default value: None
thread	The conversation thread instance (ChatHistoryAgentThread). Default value: None
arguments	Additional or overriding kernel arguments for the agent. Default value: None
kernel	The kernel instance. Default value: None
kwargs	Arbitrary advanced overrides or custom configuration.

Returns

Type	Description
	An async generator of AgentResponseItems with StreamingChatMessageContent, each containing partial segments of the conversation response.

Attributes

arguments

The agent's default KernelArguments.

arguments: KernelArguments | None

channel_type

The channel class to use for agent communication, set to ChatHistoryChannel by default.

channel_type: ClassVar[type[AgentChannel] | None] = ChatHistoryChannel

description

The textual description of the agent's purpose or scope.

description: str | None

function_choice_behavior

Determines how (and if) the chat completion will attempt to find or call functions provided by available plugins.

function_choice_behavior: FunctionChoiceBehavior | None

id

The unique identifier of the agent. If not provided, a new UUID will be generated.

id: str

instructions

The system instructions or meta-prompts guiding agent behavior.

instructions: str | None

is_release_candidate

Indicates that this agent is in a release_candidate development stage.

is_release_candidate = True

kernel

The kernel instance associated with this agent.

kernel: Kernel

name

The friendly or semantic name of the agent.

name: str

prompt_template

The optional template for generating prompts. Overridden by instructions if they differ.

prompt_template: PromptTemplateBase | None

service

A ChatCompletionClientBase-provided AI service. May be automatically registered with the kernel on initialization.

service: ChatCompletionClientBase | None