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 on the specified thread with a stream of incremental StreamingChatMessageContent responses.

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: AgentsApiResponseFormatOption | None = None, parallel_tool_calls: bool | None = None, metadata: dict[str, str] | None = None, **kwargs: Any) -> AgentResponseItem[ChatMessageContent]

Parameters

Name	Description
messages	Input message(s) to process.
thread	Agent thread context.
arguments	Kernel arguments.
kernel	Kernel to use.
model	Model identifier.
instructions_override	Overrides the default instructions.
additional_instructions	Appends extra instructions to the prompt.
additional_messages	Appends additional messages to the thread.
tools	Tool definitions used in the request.
temperature	Controls response randomness.
top_p	Controls nucleus sampling.
max_prompt_tokens	Max number of tokens allowed in prompt.
max_completion_tokens	Max number of tokens in the output.
truncation_strategy	Truncation strategy for long prompts.
response_format	Desired format for the response.
parallel_tool_calls	Enable parallel tool execution.
metadata	Metadata passed to the agent.
kwargs	Additional arguments.

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: AgentsApiResponseFormatOption | None = None, parallel_tool_calls: bool | None = None, metadata: dict[str, str] | None = None, **kwargs: Any) -> AsyncIterable[AgentResponseItem[ChatMessageContent]]

Parameters

Name	Description
messages	Input message(s) to process.
thread	Agent thread context.
arguments	Kernel arguments.
kernel	Kernel to use.
model	Model identifier.
instructions_override	Overrides the default instructions.
additional_instructions	Appends extra instructions to the prompt.
additional_messages	Appends additional messages to the thread.
tools	Tool definitions used in the request.
temperature	Controls response randomness.
top_p	Controls nucleus sampling.
max_prompt_tokens	Max number of tokens allowed in prompt.
max_completion_tokens	Max number of tokens in the output.
truncation_strategy	Truncation strategy for long prompts.
response_format	Desired format for the response.
parallel_tool_calls	Enable parallel tool execution.
metadata	Metadata passed to the agent.
kwargs	Additional arguments.

Returns

Type	Description
	Yields incremental ChatMessageContent responses from the agent.

invoke_stream

Invoke the agent on the specified thread with a stream of incremental StreamingChatMessageContent responses.

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: AgentsApiResponseFormatOption | None = None, parallel_tool_calls: bool | None = None, metadata: dict[str, str] | None = None, **kwargs: Any) -> AsyncIterable[AgentResponseItem[StreamingChatMessageContent]]

Parameters

Name	Description
messages	Input messages to send to the agent. Can be a string, ChatMessageContent, or list of either.
thread	Optional thread to continue from. A new thread is created if none is provided.
arguments	Optional KernelArguments passed to the agent.
additional_instructions	Optional additional instructions to append to the system prompt.
additional_messages	List of additional messages to append to the conversation.
instructions_override	Overrides the default instructions specified in the agent definition or prompt config.
kernel	Optional Kernel instance used for plugin invocations.
model	Optional model name to override the agent’s default.
on_complete	Optional callback function that receives the full ChatHistory once the stream completes.
tools	List of ToolDefinition objects specifying tools available to the agent.
temperature	Controls the randomness of the output. Lower is more deterministic.
top_p	Controls nucleus sampling. The model considers the results of the tokens with top_p probability mass.
max_prompt_tokens	Maximum number of tokens allowed in the prompt.
max_completion_tokens	Maximum number of tokens to generate in the completion.
truncation_strategy	Defines how to handle input prompts that exceed the token limit.
response_format	Specifies the format of the output, such as text or JSON.
parallel_tool_calls	If true, the agent can call multiple tools in parallel.
metadata	Optional metadata dictionary attached to the request.
kwargs	Additional keyword arguments passed to the agent runtime.

Returns

Type	Description
	An async iterable yielding StreamingChatMessageContent responses from the agent.