Get Agent - Get Agent

Service:: AI Foundry

API Version:: v1

Retrieves an existing agent.

GET {endpoint}/assistants/{assistantId}?api-version=v1

URI Parameters

Name	In	Required	Type	Description
assistantId	path	True	string	Identifier of the agent.
endpoint	path	True	string (uri)	Project endpoint in the form of: https://<aiservices-id>.services.ai.azure.com/api/projects/<project-name>
api-version	query	True	string minLength: 1	The API version to use for this operation.

Responses

Name	Type	Description
200 OK	Agent	The requested agent instance.
Other Status Codes	AgentV1Error	An unexpected error response.

Security

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes

Name	Description
https://ai.azure.com/.default

Examples

GetAgent_MaximumSet

GetAgent_MinimumSet

GetAgent_MaximumSet

Sample request

HTTP

GET {endpoint}/assistants/dneldjoxvbteazvgvanfumjkn?api-version=v1

Sample response

Status code:: 200

{
  "id": "ldgcuidjvzrp",
  "object": "assistant",
  "created_at": 1,
  "name": "mldxpytbtdtrukktpciqtkcttk",
  "description": "qvci",
  "model": "farpqexpvlgrwtjwawkbryjrxmt",
  "instructions": "csqxezmbgdisjpndkhvxbrbwpeftb",
  "tools": [
    {
      "type": "ToolDefinition"
    }
  ],
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv",
        "lrxbwhmsewnzmfushighvgbv"
      ],
      "data_sources": [
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        },
        {
          "uri": "jtookuzhwojyylbips",
          "type": "uri_asset"
        }
      ]
    },
    "file_search": {
      "vector_store_ids": [
        "ezeljyggzgyvliaif"
      ],
      "vector_stores": [
        {
          "name": "jtpzxxafdiapssaxxruzkitbpmdovh",
          "configuration": {
            "data_sources": [
              {
                "uri": "jtookuzhwojyylbips",
                "type": "uri_asset"
              }
            ]
          }
        }
      ]
    },
    "azure_ai_search": {
      "indexes": [
        {
          "index_connection_id": "nfeoncaophxqnhmsewmckkwbyv",
          "index_name": "nidrehbyzdpvelcltqqloq",
          "query_type": "simple",
          "top_k": 4,
          "filter": "hrfico",
          "index_asset_id": "wybmymisqviehjpplxbrjtmaxejq"
        }
      ]
    }
  },
  "temperature": 24,
  "top_p": 20,
  "metadata": {
    "key6403": "cafmabfintoktvmzcbkzrimxe"
  }
}

GetAgent_MinimumSet

Sample request

HTTP

GET {endpoint}/assistants/dneldjoxvbteazvgvanfumjkn?api-version=v1

Sample response

Status code:: 200

{
  "id": "ldgcuidjvzrp",
  "object": "assistant",
  "created_at": 1,
  "name": "mldxpytbtdtrukktpciqtkcttk",
  "description": "qvci",
  "model": "farpqexpvlgrwtjwawkbryjrxmt",
  "instructions": "csqxezmbgdisjpndkhvxbrbwpeftb",
  "tools": [
    {
      "type": "ToolDefinition"
    }
  ],
  "tool_resources": {},
  "temperature": 24,
  "top_p": 20,
  "metadata": {}
}

Definitions

Name	Description
Agent	Represents an agent that can call the model and use tools.
AgentErrorDetail	Describes the error information returned by the agents API.
AgentV1Error	Error payload returned by the agents API.
AISearchIndexResource	A AI Search Index resource.
AzureAISearchQueryType	Available query types for Azure AI Search tool.
AzureAISearchToolDefinition	The input definition information for an Azure AI search tool as used to configure an agent.
AzureAISearchToolResource	A set of index resources used by the `azure_ai_search` tool.
AzureFunctionBinding	The structure for keeping storage queue name and URI.
AzureFunctionDefinition	The definition of Azure function.
AzureFunctionStorageQueue	The structure for keeping storage queue name and URI.
AzureFunctionToolDefinition	The input definition information for a azure function tool as used to configure an agent.
BingGroundingSearchConfiguration	Search configuration for Bing Grounding
BingGroundingSearchToolParameters	The bing grounding search tool parameters.
BingGroundingToolDefinition	The input definition information for a bing grounding search tool as used to configure an agent.
CodeInterpreterToolDefinition	The input definition information for a code interpreter tool as used to configure an agent.
CodeInterpreterToolResource	A set of resources that are used by the `code_interpreter` tool.
ConnectedAgentDetails	Information for connecting one agent to another as a tool
ConnectedAgentToolDefinition	The input definition information for a connected agent tool which defines a domain specific sub-agent
FileSearchRankingOptions	Ranking options for file search.
FileSearchToolDefinition	The input definition information for a file search tool as used to configure an agent.
FileSearchToolDefinitionDetails	Options overrides for the file search tool.
FileSearchToolResource	A set of resources that are used by the `file_search` tool.
FunctionDefinition	The input definition information for a function.
FunctionToolDefinition	The input definition information for a function tool as used to configure an agent.
OpenApiAnonymousAuthDetails	Security details for OpenApi anonymous authentication
OpenApiAuthType	Authentication type for OpenApi endpoint. Allowed types are: Anonymous (no authentication required) Connection (requires connection_id to endpoint, as setup in AI Foundry) Managed_Identity (requires audience for identity based auth)
OpenApiConnectionAuthDetails	Security details for OpenApi connection authentication
OpenApiConnectionSecurityScheme	Security scheme for OpenApi managed_identity authentication
OpenApiFunctionDefinition	The input definition information for an openapi function.
OpenApiManagedAuthDetails	Security details for OpenApi managed_identity authentication
OpenApiManagedSecurityScheme	Security scheme for OpenApi managed_identity authentication
OpenApiToolDefinition	The input definition information for an OpenAPI tool as used to configure an agent.
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.
VectorStoreConfiguration	Vector storage configuration is the list of data sources, used when multiple files can be used for the enterprise file search.
VectorStoreConfigurations	The structure, containing the list of vector storage configurations i.e. the list of azure asset IDs.
VectorStoreDataSource	The structure, containing Azure asset URI path and the asset type of the file used as a data source for the enterprise file search.
VectorStoreDataSourceAssetType	Type of vector storage asset. Asset type may be a uri_asset, in this case it should contain asset URI ID, in the case of id_asset it should contain the data ID.

Agent

Object

Represents an agent that can call the model and use tools.

Name	Type	Default value	Description
created_at	integer (unixtime)		The Unix timestamp, in seconds, representing when this object was created.
description	string		The description of the agent.
id	string		The identifier, which can be referenced in API endpoints.
instructions	string		The system instructions for the agent to use.
metadata	object		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.
model	string		The ID of the model to use.
name	string		The name of the agent.
object	enum: assistant		The object type, which is always assistant.
response_format	AgentsResponseFormatOption		The response format of the tool calls used by this agent.
temperature	number (float)	1	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.
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.
tools	ToolDefinition[]: AzureAISearchToolDefinition[] AzureFunctionToolDefinition[] BingGroundingToolDefinition[] CodeInterpreterToolDefinition[] ConnectedAgentToolDefinition[] FileSearchToolDefinition[] FunctionToolDefinition[] OpenApiToolDefinition[]	[]	The collection of tools enabled for the agent.
top_p	number (float)	1	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.

AgentErrorDetail

Object

Describes the error information returned by the agents API.

Name	Type	Description
code	string	Machine-readable error code.
message	string	Human-readable description of the error.
param	string	Name of the parameter that caused the error, if applicable.
type	string	Error type identifier (e.g. `invalid_request_error`).

AgentV1Error

Object

Error payload returned by the agents API.

Name	Type	Description
error	AgentErrorDetail	Represents the error.

AISearchIndexResource

Object

A AI Search Index resource.

Name	Type	Description
filter	string	filter string for search resource.
index_asset_id	string	Index asset id for search resource.
index_connection_id	string	An index connection id in an IndexResource attached to this agent.
index_name	string	The name of an index in an IndexResource attached to this agent.
query_type	AzureAISearchQueryType	Type of query in an AIIndexResource attached to this agent.
top_k	integer (int32)	Number of documents to retrieve from search and present to the model.

AzureAISearchQueryType

Enumeration

Available query types for Azure AI Search tool.

Value	Description
simple	Query type `simple`
semantic	Query type `semantic`
vector	Query type `vector`
vector_simple_hybrid	Query type `vector_simple_hybrid`
vector_semantic_hybrid	Query type `vector_semantic_hybrid`

AzureAISearchToolDefinition

Object

The input definition information for an Azure AI search tool as used to configure an agent.

Name	Type	Description
type	string: azure_ai_search	The object type.

AzureAISearchToolResource

Object

A set of index resources used by the azure_ai_search tool.

Name	Type	Description
indexes	AISearchIndexResource[]	The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent.

AzureFunctionBinding

Object

The structure for keeping storage queue name and URI.

Name	Type	Description
storage_queue	AzureFunctionStorageQueue	Storage queue.
type	enum: storage_queue	The type of binding, which is always 'storage_queue'.

AzureFunctionDefinition

Object

The definition of Azure function.

Name	Type	Description
function	FunctionDefinition	The definition of azure function and its parameters.
input_binding	AzureFunctionBinding	Input storage queue. The queue storage trigger runs a function as messages are added to it.
output_binding	AzureFunctionBinding	Output storage queue. The function writes output to this queue when the input items are processed.

AzureFunctionStorageQueue

Object

The structure for keeping storage queue name and URI.

Name	Type	Description
queue_name	string	The name of an Azure function storage queue.
queue_service_endpoint	string	URI to the Azure Storage Queue service allowing you to manipulate a queue.

AzureFunctionToolDefinition

Object

The input definition information for a azure function tool as used to configure an agent.

Name	Type	Description
azure_function	AzureFunctionDefinition	The definition of the concrete function that the function tool should call.
type	string: azure_function	The object type.

BingGroundingSearchConfiguration

Object

Search configuration for Bing Grounding

Name	Type	Description
connection_id	string	Connection id for grounding with bing search
count	integer (int64)	The number of search results to return in the bing api response
freshness	string	Filter search results by a specific time range. Accepted values: https://learn.microsoft.com/bing/search-apis/bing-web-search/reference/query-parameters
market	string	The market where the results come from.
set_lang	string	The language to use for user interface strings when calling Bing API.

BingGroundingSearchToolParameters

Object

The bing grounding search tool parameters.

Name	Type	Description
search_configurations	BingGroundingSearchConfiguration[]	The search configurations attached to this tool. There can be a maximum of 1 search configuration resource attached to the tool.

BingGroundingToolDefinition

Object

The input definition information for a bing grounding search tool as used to configure an agent.

Name	Type	Description
bing_grounding	BingGroundingSearchToolParameters	The bing grounding search tool parameters.
type	string: bing_grounding	The object type.

CodeInterpreterToolDefinition

Object

The input definition information for a code interpreter tool as used to configure an agent.

Name	Type	Description
type	string: code_interpreter	The object type.

CodeInterpreterToolResource

Object

A set of resources that are used by the code_interpreter tool.

Name	Type	Default value	Description
data_sources	VectorStoreDataSource[]		The data sources to be used. This option is mutually exclusive with the `fileIds` property.
file_ids	string[]	[]	A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool.

ConnectedAgentDetails

Object

Information for connecting one agent to another as a tool

Name	Type	Description
description	string	A description of what the agent does, used by the model to choose when and how to call the agent.
id	string	The identifier of the child agent.
name	string	The name of the agent to be called.

ConnectedAgentToolDefinition

Object

The input definition information for a connected agent tool which defines a domain specific sub-agent

Name	Type	Description
connected_agent	ConnectedAgentDetails	The sub-agent to connect
type	string: connected_agent	The object type.

FileSearchRankingOptions

Object

Ranking options for file search.

Name	Type	Description
ranker	string	File search ranker.
score_threshold	number (float)	Ranker search threshold.

FileSearchToolDefinition

Object

The input definition information for a file search tool as used to configure an agent.

Name	Type	Description
file_search	FileSearchToolDefinitionDetails	Options overrides for the file search tool.
type	string: file_search	The object type.

FileSearchToolDefinitionDetails

Object

Options overrides for the file search tool.

Name Type Description

max_num_results

Name	Type	Description
max_num_results	integer (int32) minimum: 1 maximum: 50	The maximum number of results the file search tool should output. The default is 20 for gpt-4* models and 5 for gpt-3.5-turbo. This number should be between 1 and 50 inclusive. Note that the file search tool may output fewer than `max_num_results` results. See the file search tool documentation for more information.
ranking_options	FileSearchRankingOptions	Ranking options for file search.

integer (int32)

minimum: 1
maximum: 50

The maximum number of results the file search tool should output. The default is 20 for gpt-4* models and 5 for gpt-3.5-turbo. This number should be between 1 and 50 inclusive.

Note that the file search tool may output fewer than max_num_results results. See the file search tool documentation for more information.

ranking_options

FileSearchRankingOptions

Ranking options for file search.

FileSearchToolResource

Object

A set of resources that are used by the file_search tool.

Name	Type	Description
vector_store_ids	string[]	The ID of the vector store attached to this agent. There can be a maximum of 1 vector store attached to the agent.
vector_stores	VectorStoreConfigurations[]	The list of vector store configuration objects from Azure. This list is limited to one element. The only element of this list contains the list of azure asset IDs used by the search tool.

FunctionDefinition

Object

The input definition information for a function.

Name	Type	Description
description	string	A description of what the function does, used by the model to choose when and how to call the function.
name	string	The name of the function to be called.
parameters		The parameters the functions accepts, described as a JSON Schema object.

FunctionToolDefinition

Object

The input definition information for a function tool as used to configure an agent.

Name	Type	Description
function	FunctionDefinition	The definition of the concrete function that the function tool should call.
type	string: function	The object type.

OpenApiAnonymousAuthDetails

Object

Security details for OpenApi anonymous authentication

Name	Type	Description
type	string: anonymous	The type of authentication, must be anonymous/connection/managed_identity

OpenApiAuthType

Enumeration

Authentication type for OpenApi endpoint. Allowed types are:

Anonymous (no authentication required)
Connection (requires connection_id to endpoint, as setup in AI Foundry)
Managed_Identity (requires audience for identity based auth)

Value	Description
anonymous
connection
managed_identity

OpenApiConnectionAuthDetails

Object

Security details for OpenApi connection authentication

Name	Type	Description
security_scheme	OpenApiConnectionSecurityScheme	Connection auth security details
type	string: connection	The type of authentication, must be anonymous/connection/managed_identity

OpenApiConnectionSecurityScheme

Object

Security scheme for OpenApi managed_identity authentication

Name	Type	Description
connection_id	string	Connection id for Connection auth type

OpenApiFunctionDefinition

Object

The input definition information for an openapi function.

Name	Type	Description
auth	OpenApiAuthDetails: OpenApiAnonymousAuthDetails OpenApiConnectionAuthDetails OpenApiManagedAuthDetails	Open API authentication details
default_params	string[]	List of OpenAPI spec parameters that will use user-provided defaults
description	string	A description of what the function does, used by the model to choose when and how to call the function.
functions	FunctionDefinition[]	List of function definitions used by OpenApi tool
name	string	The name of the function to be called.
spec		The openapi function shape, described as a JSON Schema object.

OpenApiManagedAuthDetails

Object

Security details for OpenApi managed_identity authentication

Name	Type	Description
security_scheme	OpenApiManagedSecurityScheme	Connection auth security details
type	string: managed_identity	The type of authentication, must be anonymous/connection/managed_identity

OpenApiManagedSecurityScheme

Object

Security scheme for OpenApi managed_identity authentication

Name	Type	Description
audience	string	Authentication scope for managed_identity auth type

OpenApiToolDefinition

Object

The input definition information for an OpenAPI tool as used to configure an agent.

Name	Type	Description
openapi	OpenApiFunctionDefinition	The openapi function definition.
type	string: openapi	The object type.

ToolResources

Object

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.

Name	Type	Description
azure_ai_search	AzureAISearchToolResource	Resources to be used by the `azure_ai_search` tool consisting of index IDs and names.
code_interpreter	CodeInterpreterToolResource	Resources to be used by the `code_interpreter` tool consisting of file IDs.
file_search	FileSearchToolResource	Resources to be used by the `file_search` tool consisting of vector store IDs.

VectorStoreConfiguration

Object

Vector storage configuration is the list of data sources, used when multiple files can be used for the enterprise file search.

Name	Type	Description
data_sources	VectorStoreDataSource[]	Data sources

VectorStoreConfigurations

Object

The structure, containing the list of vector storage configurations i.e. the list of azure asset IDs.

Name	Type	Description
configuration	VectorStoreConfiguration	Configurations
name	string	Name

VectorStoreDataSource

Object

The structure, containing Azure asset URI path and the asset type of the file used as a data source for the enterprise file search.

Name	Type	Description
type	VectorStoreDataSourceAssetType	The asset type
uri	string	Asset URI.

VectorStoreDataSourceAssetType

Enumeration

Type of vector storage asset. Asset type may be a uri_asset, in this case it should contain asset URI ID, in the case of id_asset it should contain the data ID.

Value	Description
uri_asset	Azure URI
id_asset	The data ID

Share via

Get Agent - Get Agent

URI Parameters

Responses

Security

OAuth2Auth

Scopes

Examples

GetAgent_MaximumSet

Sample request

Sample response

GetAgent_MinimumSet

Sample request

Sample response

Definitions

Agent

AgentErrorDetail

AgentV1Error

AISearchIndexResource

AzureAISearchQueryType

AzureAISearchToolDefinition

AzureAISearchToolResource

AzureFunctionBinding

AzureFunctionDefinition

AzureFunctionStorageQueue

AzureFunctionToolDefinition

BingGroundingSearchConfiguration

BingGroundingSearchToolParameters

BingGroundingToolDefinition

CodeInterpreterToolDefinition

CodeInterpreterToolResource

ConnectedAgentDetails

ConnectedAgentToolDefinition

FileSearchRankingOptions

FileSearchToolDefinition

FileSearchToolDefinitionDetails

FileSearchToolResource

FunctionDefinition

FunctionToolDefinition

OpenApiAnonymousAuthDetails

OpenApiAuthType

OpenApiConnectionAuthDetails

OpenApiConnectionSecurityScheme

OpenApiFunctionDefinition

OpenApiManagedAuthDetails

OpenApiManagedSecurityScheme

OpenApiToolDefinition

ToolResources

VectorStoreConfiguration

VectorStoreConfigurations

VectorStoreDataSource

VectorStoreDataSourceAssetType