AzureAIAgent Class

Azure AI Agent class, enabling interaction with Azure-hosted AI Assistants using a specialized AIProjectClient. The agent leverages an AzureAIAgentModel configuration and can optionally override default parameters such as temperature, maximum tokens, or instructions. Initialize an AzureAIAgent service by providing at minimum an AIProjectClient and an AzureAIAgentModel.

Constructor

AzureAIAgent(
  *,
  arguments: KernelArguments | None = None,
  client: AIProjectClient,
  definition: AzureAIAgentModel,
  kernel: Kernel | None = None,
  plugins: list[KernelPlugin | object] | dict[str, KernelPlugin | object] | None = None,
  polling_options: RunPollingOptions | None = None,
  prompt_template_config: PromptTemplateConfig | None = None,
  **kwargs: Any
)

Keyword-Only Parameters

Name	Description
arguments	The KernelArguments to initialize the agent with.
client Required	The Azure AI Project client.
definition Required	The AzureAIAgentModel detailing the agent's config in Azure.
kernel	A Kernel instance for plugin usage.
plugins	A collection of plugins added to the kernel, which may override kernel-provided plugins if duplicates exist.
polling_options	The optional run polling configuration.
prompt_template_config	Optional prompt template. If provided along with instructions in the AzureAIAgentModel, the template config takes precedence.
kwargs	Additional keyword arguments appended to the agent's state.

Methods

create_client	A helper to create an AIProjectClient from a credential and connection string. Falls back to AzureAIAgentSettings if no connection string is provided.
get_response	Retrieve a single ChatMessageContent from the agent after a series of messages or instructions on the specified thread.
invoke	Invoke the agent in an async stream of incremental ChatMessageContent, returning each visible message in real time.
invoke_stream	Invoke the agent in streaming mode, returning partial tokens or messages as they are formed. Once complete, an optional callback captures the final structured messages in a ChatHistory object.
get_channel_keys	Returns keys that distinguish this agent's channel, such as agent name, ID, and scope.
create_channel	Create or reuse an AzureAIChannel with an optional thread ID. If no thread ID is specified, a new thread is created in the Azure AI Project.
add_chat_message	Add a user or system chat message to the specified thread.

create_client

A helper to create an AIProjectClient from a credential and connection string. Falls back to AzureAIAgentSettings if no connection string is provided.

static create_client(
  credential: DefaultAzureCredential,
  conn_str: str | None = None,
  **kwargs: Any
) -> AIProjectClient

Parameters

Name	Description
credential Required	The Azure credential.
conn_str	The optional connection string. Default value: None
kwargs	Additional arguments for customizing the client.

Returns

Type	Description
	A fully instantiated AIProjectClient.

get_response

Retrieve a single ChatMessageContent from the agent after a series of messages or instructions on the specified thread.

async get_response(
  *,
  messages: str | ChatMessageContent | list[str | ChatMessageContent] | None = None,
  thread: AgentThread | None = None,
  arguments: KernelArguments | None = None,
  kernel: Kernel | None = None,
  model: str | None = None,
  instructions_override: str | None = None,
  additional_instructions: str | None = None,
  additional_messages: list[ThreadMessageOptions] | None = None,
  tools: list[ToolDefinition] | None = None,
  temperature: float | None = None,
  top_p: float | None = None,
  max_prompt_tokens: int | None = None,
  max_completion_tokens: int | None = None,
  truncation_strategy: TruncationObject | None = None,
  response_format: str | AgentsApiResponseFormatMode | AgentsApiResponseFormat | ResponseFormatJsonSchemaType | None = None,
  parallel_tool_calls: bool | None = None,
  metadata: dict[str,str] | None = None,
  **kwargs: Any
) -> AgentResponseItem[ChatMessageContent]

Parameters

Name	Description
messages	One or more user messages to process. Default value: None
thread	The existing or new conversation thread. Default value: None
arguments	Kernel argument overrides. Default value: None
kernel	The kernel used for plugin invocation. Default value: None
model	The optional Azure model override. Default value: None
instructions_override	The override for default instructions. Default value: None
additional_instructions	Appended instructions for the agent. Default value: None
additional_messages	Additional messages appended to the request. Default value: None
tools	Tools or function calls the agent may use. Default value: None
temperature	Controls randomness or creativity level. Default value: None
top_p	Probability threshold controlling token sampling. Default value: None
max_prompt_tokens	The maximum tokens for the prompt. Default value: None
max_completion_tokens	The maximum tokens for the agent's completion. Default value: None
truncation_strategy	Strategy for truncating conversation. Default value: None
response_format	Desired agent response format (e.g., JSON). Default value: None
parallel_tool_calls	Whether the agent can call tools in parallel. Default value: None
metadata	Extra metadata for the request. Default value: None
kwargs	Additional advanced overrides.

Returns

Type	Description
	The final ChatMessageContent returned by the agent.

invoke

Invoke the agent in an async stream of incremental ChatMessageContent, returning each visible message in real time.

async invoke(
  *,
  messages: str | ChatMessageContent | list[str | ChatMessageContent] | None = None,
  thread: AgentThread | None = None,
  arguments: KernelArguments | None = None,
  kernel: Kernel | None = None,
  model: str | None = None,
  instructions_override: str | None = None,
  additional_instructions: str | None = None,
  additional_messages: list[ThreadMessageOptions] | None = None,
  tools: list[ToolDefinition] | None = None,
  temperature: float | None = None,
  top_p: float | None = None,
  max_prompt_tokens: int | None = None,
  max_completion_tokens: int | None = None,
  truncation_strategy: TruncationObject | None = None,
  response_format: str | AgentsApiResponseFormatMode | AgentsApiResponseFormat | ResponseFormatJsonSchemaType | None = None,
  parallel_tool_calls: bool | None = None,
  metadata: dict[str,str] | None = None,
  **kwargs: Any
) -> AsyncIterable[AgentResponseItem[ChatMessageContent]]

Parameters

Name	Description
messages	User message(s) to process. Default value: None
thread	The conversation thread context. Default value: None
arguments	Kernel argument overrides. Default value: None
kernel	Kernel instance for plugin calls. Default value: None
model	The optional Azure model override. Default value: None
instructions_override	Override for the default instructions. Default value: None
additional_instructions	Extra instructions appended to the conversation. Default value: None
additional_messages	Additional messages appended to the request. Default value: None
tools	Tools or function calls the agent may use. Default value: None
temperature	Creativity level controlling randomness. Default value: None
top_p	Probability threshold for token sampling. Default value: None
max_prompt_tokens	Maximum tokens allocated for the prompt. Default value: None
max_completion_tokens	Maximum tokens allocated for the completion. Default value: None
truncation_strategy	Strategy for conversation truncation. Default value: None
response_format	Desired response format (e.g. JSON). Default value: None
parallel_tool_calls	Whether agent can call multiple tools in parallel. Default value: None
metadata	Arbitrary metadata for the request. Default value: None
kwargs	Additional advanced overrides.

Returns

Type	Description
	An async stream of AgentResponseItems containing ChatMessageContent.

invoke_stream

Invoke the agent in streaming mode, returning partial tokens or messages as they are formed. Once complete, an optional callback captures the final structured messages in a ChatHistory object.

async invoke_stream(
  *,
  messages: str | ChatMessageContent | list[str | ChatMessageContent] | None = None,
  thread: AgentThread | None = None,
  arguments: KernelArguments | None = None,
  additional_instructions: str | None = None,
  additional_messages: list[ThreadMessageOptions] | None = None,
  instructions_override: str | None = None,
  kernel: Kernel | None = None,
  model: str | None = None,
  on_complete: Callable[[ChatHistory], None] | None = None,
  tools: list[ToolDefinition] | None = None,
  temperature: float | None = None,
  top_p: float | None = None,
  max_prompt_tokens: int | None = None,
  max_completion_tokens: int | None = None,
  truncation_strategy: TruncationObject | None = None,
  response_format: str | AgentsApiResponseFormatMode | AgentsApiResponseFormat | ResponseFormatJsonSchemaType | None = None,
  parallel_tool_calls: bool | None = None,
  metadata: dict[str,str] | None = None,
  **kwargs: Any
) -> AsyncIterable[AgentResponseItem[StreamingChatMessageContent]]

Parameters

Name	Description
messages	User message(s) or a list of ChatMessageContent to start with. Default value: None
thread	The conversation thread to continue or create. Default value: None
arguments	Kernel argument overrides. Default value: None
additional_instructions	Additional instructions appended to the conversation. Default value: None
additional_messages	Additional messages appended to the request. Default value: None
instructions_override	Overwrites default instructions for the agent. Default value: None
kernel	Kernel instance for plugin calls. Default value: None
model	Model override if not using default. Default value: None
on_complete	A callback invoked with a ChatHistory of fully formed messages after streaming ends. Default value: None
tools	Tools available to the agent for function calls. Default value: None
temperature	The creativity or randomness level. Default value: None
top_p	Probability threshold controlling token sampling. Default value: None
max_prompt_tokens	Maximum tokens in the prompt. Default value: None
max_completion_tokens	Maximum tokens for the completion content. Default value: None
truncation_strategy	Strategy to reduce conversation history if needed. Default value: None
response_format	Desired agent response format (JSON, text, etc). Default value: None
parallel_tool_calls	Allows multiple parallel tool invocations if True. Default value: None
metadata	Arbitrary metadata passed with the request. Default value: None
kwargs	Additional advanced overrides for the request.

Returns

Type	Description
	An async generator of partial or streaming messages from the Azure AI service.

get_channel_keys

Returns keys that distinguish this agent's channel, such as agent name, ID, and scope.

get_channel_keys() -> Iterable[str]

Returns

Type	Description
	A collection of string keys identifying this agent's channel.

create_channel

Create or reuse an AzureAIChannel with an optional thread ID. If no thread ID is specified, a new thread is created in the Azure AI Project.

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

Parameters

Name	Description
thread_id	The thread ID to attach to, or None for a new one. Default value: None

Returns

Type	Description
	An instance of AzureAIChannel bound to the specified thread.

add_chat_message

Add a user or system chat message to the specified thread.

async add_chat_message(thread_id: str, message: str | ChatMessageContent) -> ThreadMessage | None

Parameters

Name	Description
thread_id Required	The ID of the thread in Azure AI.
message Required	The text or ChatMessageContent to append.

Returns

Type	Description
	The newly created ThreadMessage, or None if creation failed.

Attributes

client

The Azure AI Project client used to interact with the agent's conversation and messages.

client: AIProjectClient

definition

The AzureAIAgentModel describing the underlying agent configuration in Azure.

definition: AzureAIAgentModel

polling_options

A RunPollingOptions instance controlling how the agent polls the service for completions, tool calls, or conversation updates.

polling_options: RunPollingOptions

channel_type

The default channel for this agent, set to AzureAIChannel.

channel_type: ClassVar[type[AgentChannel]] = AzureAIChannel