Share via

AgentsClient Class

AgentsClient provides a high-level, user-friendly interface for managing and interacting with AI agents in Azure AI Agents service.

Constructor

AgentsClient(endpoint: str, credential: TokenCredential, **kwargs: Any)

Parameters

Name Description
endpoint
Required
str

Project endpoint in the form of: https://<aiservices-id>.services.ai.azure.com/api/projects/<project-name>. Required.
credential
Required
TokenCredential

Credential used to authenticate requests to the service. Required.

Methods

close
create_agent

Creates a new agent with various configurations, delegating to the generated operations.
create_thread_and_process_run

Creates a new agent thread and run in one call, then polls until the run enters a terminal state, executing any required tool calls via the provided ToolSet.
create_thread_and_run

Creates a new agent thread and immediately starts a run using the specified parameters.
delete_agent

Deletes an agent.
enable_auto_function_calls

Enables tool calls to be executed automatically during runs.create_and_process or runs.stream. If this is not set, functions must be called manually. If automatic function calls fail, the agents will receive error messages allowing it to retry with another function call or figure out the answer with its knowledge.
get_agent

Retrieves an existing agent.
list_agents

Gets a list of agents that were previously created.
send_request

Runs the network request through the client's chained policies.


>>> from azure.core.rest import HttpRequest
>>> request = HttpRequest("GET", "https://www.example.org/")
<HttpRequest [GET], url: 'https://www.example.org/'>
>>> response = client.send_request(request)
<HttpResponse: 200 OK>

For more information on this code flow, see https://aka.ms/azsdk/dpcodegen/python/send_request
update_agent

Modifies an existing agent.

close 

close() -> None

create_agent

Creates a new agent with various configurations, delegating to the generated operations.

create_agent(*, model: str, content_type: str = 'application/json', name: str | None = None, description: str | None = None, instructions: str | None = None, tools: List[_models.ToolDefinition] | None = None, tool_resources: _models.ToolResources | None = None, temperature: float | None = None, top_p: float | None = None, response_format: '_types.AgentsResponseFormatOption' | None = None, metadata: Dict[str, str] | None = None, **kwargs: Any) -> _models.Agent

Parameters

Name Description
body
Union[<xref:JSON>, IO[bytes]]

A complete agent configuration as JSON or binary stream. Required if model is not provided.

Keyword-Only Parameters

Name Description
model
str

The deployment name or ID of the Azure AI model that the agent will use. Required if body is not provided.

Default value: <object object at 0x000001E3080CE650>
name
Optional[str]

A human-readable name for the agent that helps identify its purpose or role.

Default value: None
description
Optional[str]

A detailed description explaining the agent's intended purpose and capabilities.

Default value: None
instructions
Optional[str]

System-level instructions that define the agent's behavior and personality.

Default value: None
tools
Optional[List[ToolDefinition]]

A list of tool definitions that specify the capabilities available to the agent.

Default value: None
tool_resources
Optional[ToolResources]

Resources required by the agent's tools, such as file IDs or vector store IDs.

Default value: None
toolset
Optional[<xref:_models.ToolSet>]

A pre-configured collection of tools and their associated resources that provides both tool definitions and resources in a single object. This is a convenient alternative to manually specifying tools and tool_resources separately.

Default value: None
temperature
Optional[float]

Controls response randomness (0-2). Higher values produce more creative responses.

Default value: None
top_p
Optional[float]

Nucleus sampling parameter controlling response diversity by probability mass.

Default value: None
response_format
Optional[Union[str, AgentsResponseFormatMode, AgentsResponseFormat, ResponseFormatJsonSchemaType]]

Specifies the format for the responses, particularly for tool calls. Can be a string, response format mode, or structured response format object that defines how the agent should structure its outputs.

Default value: None
metadata
Optional[Dict[str, str]]

Custom key-value pairs for storing additional information about the agent.

Default value: None
content_type
str

The MIME type of the request body when using body parameter.

Default value: application/json

Returns

Type Description
Agent

A newly created agent object with the specified configuration.

Exceptions

Type Description
HttpResponseError for HTTP errors during agent creation.

create_thread_and_process_run

Creates a new agent thread and run in one call, then polls until the run enters a terminal state, executing any required tool calls via the provided ToolSet.

create_thread_and_process_run(*, agent_id: str = <object object>, thread: ~azure.ai.agents.models._models.AgentThreadCreationOptions | None = None, model: str | None = None, instructions: str | None = None, toolset: ~azure.ai.agents.models._patch.ToolSet | 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: ~azure.ai.agents.models._models.TruncationObject | None = None, tool_choice: str | ~azure.ai.agents.models._enums.AgentsToolChoiceOptionMode | ~azure.ai.agents.models._models.AgentsNamedToolChoice | None = None, response_format: str | ~azure.ai.agents.models._enums.AgentsResponseFormatMode | ~azure.ai.agents.models._models.AgentsResponseFormat | ~azure.ai.agents.models._models.ResponseFormatJsonSchemaType | None = None, parallel_tool_calls: bool | None = None, metadata: ~typing.Dict[str, str] | None = None, polling_interval: int = 1, **kwargs: ~typing.Any) -> ThreadRun

Keyword-Only Parameters

Name Description
agent_id
str

The unique identifier of the agent to run. Required if body is unset.

Default value: <object object at 0x000001E3080CE650>
thread
AgentThreadCreationOptions

Options for creating the new thread (initial messages, metadata, tool resources).

Default value: None
model
str, <xref:optional>

Optional override of the model deployment name to use for this run.

Default value: None
instructions
str, <xref:optional>

Optional override of the system instructions for this run.

Default value: None
toolset
<xref:azure.ai.agents._tools.ToolSet>, <xref:optional>

A ToolSet instance containing both .definitions and .resources for tools. If provided, its definitions/resources are used; otherwise no tools are passed.

Default value: None
temperature
float, <xref:optional>

Sampling temperature for the model (0.0-2.0), higher is more random.

Default value: None
top_p
float, <xref:optional>

Nucleus sampling value (0.0-1.0), alternative to temperature.

Default value: None
max_prompt_tokens
int, <xref:optional>

Maximum total prompt tokens across turns; run ends "incomplete" if exceeded.

Default value: None
max_completion_tokens
int, <xref:optional>

Maximum total completion tokens across turns; run ends "incomplete" if exceeded.

Default value: None
truncation_strategy
TruncationObject, <xref:optional>

Strategy for dropping old messages when context window overflows.

Default value: None
tool_choice
str or <xref:azure.ai.agents.models.AgentsToolChoiceOption>, <xref:optional>

Controls which tool (if any) the model is allowed to call.

Default value: None
response_format
Optional[Union[str, AgentsResponseFormatMode, AgentsResponseFormat, ResponseFormatJsonSchemaType]]

Specifies the format for the responses, particularly for tool calls. Can be a string, response format mode, or structured response format object that defines how the agent should structure its outputs.

Default value: None
parallel_tool_calls
bool, <xref:optional>

If True, allows tool calls to be executed in parallel.

Default value: None
metadata
dict[str, str], <xref:optional>

Optional metadata (up to 16 key/value pairs) to attach to the run.

Default value: None
polling_interval
int, <xref:optional>

Seconds to wait between polling attempts for run status. Default is 1.

Default value: 1

Returns

Type Description
ThreadRun

The final ThreadRun object, in a terminal state (succeeded, failed, or cancelled).

Exceptions

Type Description
HttpResponseError

If the underlying REST call to create the thread+run or to poll fails.

create_thread_and_run

Creates a new agent thread and immediately starts a run using the specified parameters.

create_thread_and_run(*, agent_id: str, content_type: str = 'application/json', thread: _models.AgentThreadCreationOptions | None = None, model: str | None = None, instructions: str | None = None, tools: List[_models.ToolDefinition] | None = None, tool_resources: _models.ToolResources | 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: _models.TruncationObject | None = None, tool_choice: '_types.AgentsToolChoiceOption' | None = None, response_format: '_types.AgentsResponseFormatOption' | None = None, parallel_tool_calls: bool | None = None, metadata: Dict[str, str] | None = None, **kwargs: Any) -> _models.ThreadRun

Parameters

Name Description
body
<xref:JSON> or IO[bytes]

Either a JSON payload (dict) or a binary stream (IO[bytes]). Use JSON overload for dict bodies and binary overload for IO[bytes].

Keyword-Only Parameters

Name Description
agent_id
str

The ID of the agent for which the thread should be created. Required when not using the JSON/body overload.

Default value: <object object at 0x000001E3080CE650>
thread
AgentThreadCreationOptions

The details used to create the new thread. If none provided, an empty thread is created.

Default value: None
model
str

Override the model the agent uses for this run.

Default value: None
instructions
str

Override the system instructions for this run.

Default value: None
tools
list[ToolDefinition]

Override the list of enabled tools for this run.

Default value: None
tool_resources
ToolResources

Override the tools the agent can use for this run.

Default value: None
temperature
float

Sampling temperature between 0 and 2. Higher = more random.

Default value: None
top_p
float

Nucleus sampling parameter between 0 and 1.

Default value: None
max_prompt_tokens
int

Max prompt tokens to use across the run.

Default value: None
max_completion_tokens
int

Max completion tokens to use across the run.

Default value: None
truncation_strategy
TruncationObject

Strategy for dropping old messages as context grows.

Default value: None
tool_choice
str or AgentsToolChoiceOptionMode or AgentsNamedToolChoice

Controls which tool the model will call.

Default value: None
response_format
Optional[Union[str, AgentsResponseFormatMode, AgentsResponseFormat, ResponseFormatJsonSchemaType]]

Specifies the format for the responses, particularly for tool calls. Can be a string, response format mode, or structured response format object that defines how the agent should structure its outputs.

Default value: None
parallel_tool_calls
bool

If True, tools will be invoked in parallel.

Default value: None
metadata
dict[str, str]

Up to 16 key/value pairs for structured metadata on the run.

Default value: None

Returns

Type Description
ThreadRun

ThreadRun. The ThreadRun is compatible with MutableMapping.

Exceptions

Type Description
ValueError

If the combination of arguments is invalid.
HttpResponseError

delete_agent

Deletes an agent.

delete_agent(agent_id: str, **kwargs: Any) -> None

Parameters

Name Description
agent_id
Required
str

Identifier of the agent. Required.

Returns

Type Description
None

Exceptions

Type Description
HttpResponseError

enable_auto_function_calls

Enables tool calls to be executed automatically during runs.create_and_process or runs.stream. If this is not set, functions must be called manually. If automatic function calls fail, the agents will receive error messages allowing it to retry with another function call or figure out the answer with its knowledge.

enable_auto_function_calls(tools: Set[Callable[[...], Any]] | FunctionTool | ToolSet, max_retry: int = 10) -> None

Parameters

Name Description
tools
Required
Union[Set[Callable[..., Any]], <xref:_models.AsyncFunctionTool>, <xref:_models.AsyncToolSet>]

A function tool, toolset, or a set of callable functions.
max_retry
int

Maximum number of errors allowed and retry per run or stream. Default value is 10.

Default value: 10

get_agent

Retrieves an existing agent.

get_agent(agent_id: str, **kwargs: Any) -> Agent

Parameters

Name Description
agent_id
Required
str

Identifier of the agent. Required.

Returns

Type Description
Agent

Agent. The Agent is compatible with MutableMapping

Exceptions

Type Description
HttpResponseError

list_agents

Gets a list of agents that were previously created.

list_agents(*, limit: int | None = None, order: str | ListSortOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[Agent]

Keyword-Only Parameters

Name Description
limit
int

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. Default value is None.

Default value: None
order
str or ListSortOrder

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order. Known values are: "asc" and "desc". Default value is None.

Default value: None
before
str

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. Default value is None.

Default value: None

Returns

Type Description
ItemPaged[Agent]

An iterator like instance of Agent

Exceptions

Type Description
HttpResponseError

send_request

Runs the network request through the client's chained policies.


>>> from azure.core.rest import HttpRequest
>>> request = HttpRequest("GET", "https://www.example.org/")
<HttpRequest [GET], url: 'https://www.example.org/'>
>>> response = client.send_request(request)
<HttpResponse: 200 OK>

For more information on this code flow, see https://aka.ms/azsdk/dpcodegen/python/send_request

send_request(request: HttpRequest, *, stream: bool = False, **kwargs: Any) -> HttpResponse

Parameters

Name Description
request
Required
HttpRequest

The network request you want to make. Required.

Keyword-Only Parameters

Name Description
stream
bool

Whether the response payload will be streamed. Defaults to False.

Default value: False

Returns

Type Description
HttpResponse

The response of your network call. Does not do error handling on your response.

update_agent

Modifies an existing agent.

update_agent(agent_id: str, *, content_type: str = 'application/json', model: str | None = None, name: str | None = None, description: str | None = None, instructions: str | None = None, tools: List[_models.ToolDefinition] | None = None, tool_resources: _models.ToolResources | None = None, temperature: float | None = None, top_p: float | None = None, response_format: '_types.AgentsResponseFormatOption' | None = None, metadata: Dict[str, str] | None = None, **kwargs: Any) -> _models.Agent

Parameters

Name Description
agent_id
Required
str

The ID of the agent to modify. Required.
body
<xref:JSON> or IO[bytes]

Is either a JSON type or a IO[bytes] type. Required.

Keyword-Only Parameters

Name Description
model
str

The ID of the model to use. Default value is None.

Default value: None
name
str

The modified name for the agent to use. Default value is None.

Default value: None
description
str

The modified description for the agent to use. Default value is None.

Default value: None
instructions
str

The modified system instructions for the new agent to use. Default value is None.

Default value: None
tools
list[ToolDefinition]

The modified collection of tools to enable for the agent. Default value is None.

Default value: None
tool_resources
ToolResources

A set of resources that are used by the agent's tools. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs. Default value is None.

Default value: None
toolset
ToolSet

A pre-configured collection of tools and their associated resources that provides both tool definitions and resources in a single object. This is a convenient alternative to manually specifying tools and tool_resources separately.

Default value: None
temperature
float

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. Default value is None.

Default value: None
top_p
float

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both. Default value is None.

Default value: None
response_format
Optional[Union[str, AgentsResponseFormatMode, AgentsResponseFormat, ResponseFormatJsonSchemaType]]

Specifies the format for the responses, particularly for tool calls. Can be a string, response format mode, or structured response format object that defines how the agent should structure its outputs.

Default value: None
content_type
str

Body Parameter content-type. Content type parameter for JSON body. Default value is "application/json".

Default value: application/json
metadata
dict[str, str]

A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length. Default value is None.

Default value: None

Returns

Type Description
Agent

Agent. The Agent is compatible with MutableMapping

Exceptions

Type Description
HttpResponseError