Microsoft Azure AI Foundry Assistants API

openapi: 3.2.0
info:
  title: Azure AI Assistants API
  version: v1
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
security:
- OAuth2Auth:
  - https://ai.azure.com/.default
tags:
- name: Assistants
paths:
  /assistants:
    get:
      operationId: ListAgents
      description: Gets a list of agents that were previously created.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: limit
        in: query
        description: A limit on the number of objects to be returned on one page. Limit can range between 1 and 100, and the default is 20.
        required: false
        schema:
          type: integer
          format: int32
          default: 20
      - name: order
        in: query
        description: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
        required: false
        x-ms-enum:
          name: ListSortOrder
          modelAsString: true
          values:
          - name: ascending
            value: asc
            description: Specifies an ascending sort order.
          - name: descending
            value: desc
            description: Specifies a descending sort order.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: after
        in: query
        description: A cursor for use in pagination. after 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 after=obj_foo in order to fetch the next page of the list.
        required: false
        schema:
          type: string
      - name: before
        in: query
        description: 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.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The requested list of agents.
          content:
            application/json:
              schema:
                type: object
                description: The response data for a requested list of items.
                properties:
                  data:
                    type: array
                    description: The requested list of items.
                    items:
                      $ref: '#/components/schemas/Agent'
                  last_id:
                    type: string
                    description: The last ID represented in this list.
                    x-ms-client-name: lastId
                  has_more:
                    type: boolean
                    description: A value indicating whether there are additional values available not captured in this list.
                    x-ms-client-name: hasMore
                required:
                - data
                - has_more
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      tags:
      - Assistants
      summary: List agents
      x-summary-source: derived
    post:
      operationId: CreateAgent
      description: Creates a new agent.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      responses:
        '200':
          description: The new agent instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentOptions'
        required: true
      tags:
      - Assistants
      summary: Create agent
      x-summary-source: derived
  /assistants/{assistantId}:
    get:
      operationId: GetAgent
      description: Retrieves an existing agent.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/GetAgentOptions'
      responses:
        '200':
          description: The requested agent instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      tags:
      - Assistants
      summary: Get agent
      x-summary-source: derived
    post:
      operationId: UpdateAgent
      description: Modifies an existing agent.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/UpdateAgentOptions.assistantId'
      responses:
        '200':
          description: The updated agent instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentOptions'
        required: true
      tags:
      - Assistants
      summary: Update agent
      x-summary-source: derived
    delete:
      operationId: DeleteAgent
      description: Deletes an agent.
      parameters:
      - $ref: '#/components/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - $ref: '#/components/parameters/DeleteAgentOptions'
      responses:
        '200':
          description: Status information about the requested deletion operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDeletionStatus'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentV1Error'
      tags:
      - Assistants
      summary: Delete agent
      x-summary-source: derived
components:
  schemas:
    ToolResources:
      type: object
      description: '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.'
      properties:
        code_interpreter:
          $ref: '#/components/schemas/CodeInterpreterToolResource'
          description: Resources to be used by the `code_interpreter` tool consisting of file IDs.
          x-ms-client-name: codeInterpreter
        file_search:
          $ref: '#/components/schemas/FileSearchToolResource'
          description: Resources to be used by the `file_search` tool consisting of vector store IDs.
          x-ms-client-name: fileSearch
        azure_ai_search:
          $ref: '#/components/schemas/AzureAISearchToolResource'
          description: Resources to be used by the `azure_ai_search` tool consisting of index IDs and names.
          x-ms-client-name: azureAISearch
    AzureAISearchQueryType:
      type: string
      description: Available query types for Azure AI Search tool.
      enum:
      - simple
      - semantic
      - vector
      - vector_simple_hybrid
      - vector_semantic_hybrid
      x-ms-enum:
        name: AzureAISearchQueryType
        modelAsString: true
        values:
        - name: simple
          value: simple
          description: Query type `simple`
        - name: semantic
          value: semantic
          description: Query type `semantic`
        - name: vector
          value: vector
          description: Query type `vector`
        - name: vector_simple_hybrid
          value: vector_simple_hybrid
          description: Query type `vector_simple_hybrid`
        - name: vector_semantic_hybrid
          value: vector_semantic_hybrid
          description: Query type `vector_semantic_hybrid`
    UpdateAgentOptions:
      type: object
      description: The request details to use when modifying an existing agent.
      properties:
        model:
          type: string
          description: The ID of the model to use.
        name:
          type:
          - string
          - 'null'
          description: The modified name for the agent to use.
        description:
          type:
          - string
          - 'null'
          description: The modified description for the agent to use.
        instructions:
          type:
          - string
          - 'null'
          description: The modified system instructions for the new agent to use.
        tools:
          type: array
          description: The modified collection of tools to enable for the agent.
          default: []
          items:
            $ref: '#/components/schemas/ToolDefinition'
        tool_resources:
          $ref: '#/components/schemas/ToolResources'
          description: '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.'
          x-ms-client-name: toolResources
        temperature:
          type:
          - number
          - 'null'
          format: float
          description: '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: 1
          minimum: 0
          maximum: 2
        top_p:
          type:
          - number
          - 'null'
          format: float
          description: '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: 1
          minimum: 0
          maximum: 1
          x-ms-client-name: topP
        response_format:
          $ref: '#/components/schemas/AgentsResponseFormatOption'
          description: The response format of the tool calls used by this agent.
          x-ms-client-name: responseFormat
        metadata:
          type:
          - object
          - 'null'
          description: 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.
          additionalProperties:
            type: string
    CodeInterpreterToolResource:
      type: object
      description: A set of resources that are used by the `code_interpreter` tool.
      properties:
        file_ids:
          type: array
          description: 'A list of file IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files

            associated with the tool.'
          default: []
          maxItems: 20
          items:
            type: string
          x-ms-client-name: fileIds
        data_sources:
          type: array
          description: The data sources to be used. This option is mutually exclusive with the `fileIds` property.
          maxItems: 20
          items:
            $ref: '#/components/schemas/VectorStoreDataSource'
          x-ms-client-name: dataSources
    CreateAgentOptions:
      type: object
      description: The request details to use when creating a new agent.
      properties:
        model:
          type: string
          description: The ID of the model to use.
        name:
          type:
          - string
          - 'null'
          description: The name of the new agent.
        description:
          type:
          - string
          - 'null'
          description: The description of the new agent.
        instructions:
          type:
          - string
          - 'null'
          description: The system instructions for the new agent to use.
        tools:
          type: array
          description: The collection of tools to enable for the new agent.
          default: []
          items:
            $ref: '#/components/schemas/ToolDefinition'
        tool_resources:
          $ref: '#/components/schemas/ToolResources'
          description: '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.'
          x-ms-client-name: toolResources
        temperature:
          type:
          - number
          - 'null'
          format: float
          description: '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: 1
          minimum: 0
          maximum: 2
        top_p:
          type:
          - number
          - 'null'
          format: float
          description: '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: 1
          minimum: 0
          maximum: 1
          x-ms-client-name: topP
        response_format:
          $ref: '#/components/schemas/AgentsResponseFormatOption'
          description: The response format of the tool calls used by this agent.
          x-ms-client-name: responseFormat
        metadata:
          type:
          - object
          - 'null'
          description: 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.
          additionalProperties:
            type: string
      required:
      - model
    AgentsResponseFormatOption: {}
    AzureAISearchToolResource:
      type: object
      description: A set of index resources used by the `azure_ai_search` tool.
      properties:
        indexes:
          type: array
          description: 'The indices attached to this agent. There can be a maximum of 1 index

            resource attached to the agent.'
          maxItems: 1
          items:
            $ref: '#/components/schemas/AISearchIndexResource'
          x-ms-client-name: indexList
    FileSearchToolResource:
      type: object
      description: A set of resources that are used by the `file_search` tool.
      properties:
        vector_store_ids:
          type: array
          description: 'The ID of the vector store attached to this agent. There can be a maximum of 1 vector

            store attached to the agent.'
          maxItems: 1
          items:
            type: string
          x-ms-client-name: vectorStoreIds
        vector_stores:
          type: array
          description: '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.'
          maxItems: 1
          items:
            $ref: '#/components/schemas/VectorStoreConfigurations'
          x-ms-client-name: vectorStores
    VectorStoreConfiguration:
      type: object
      description: 'Vector storage configuration is the list of data sources, used when multiple

        files can be used for the enterprise file search.'
      properties:
        data_sources:
          type: array
          description: Data sources
          items:
            $ref: '#/components/schemas/VectorStoreDataSource'
          x-ms-client-name: dataSources
      required:
      - data_sources
    AgentErrorDetail:
      type: object
      description: Describes the error information returned by the agents API.
      properties:
        message:
          type:
          - string
          - 'null'
          description: Human-readable description of the error.
        type:
          type:
          - string
          - 'null'
          description: Error type identifier (e.g. `invalid_request_error`).
        param:
          type:
          - string
          - 'null'
          description: Name of the parameter that caused the error, if applicable.
        code:
          type:
          - string
          - 'null'
          description: Machine-readable error code.
    AgentV1Error:
      type: object
      description: Error payload returned by the agents API.
      properties:
        error:
          $ref: '#/components/schemas/AgentErrorDetail'
          description: Represents the error.
      required:
      - error
    VectorStoreDataSourceAssetType:
      type: string
      description: '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.'
      enum:
      - uri_asset
      - id_asset
      x-ms-enum:
        name: VectorStoreDataSourceAssetType
        modelAsString: true
        values:
        - name: uri_asset
          value: uri_asset
          description: Azure URI
        - name: id_asset
          value: id_asset
          description: The data ID
    AISearchIndexResource:
      type: object
      description: A AI Search Index resource.
      properties:
        index_connection_id:
          type: string
          description: An index connection id in an IndexResource attached to this agent.
          x-ms-client-name: indexConnectionId
        index_name:
          type: string
          description: The name of an index in an IndexResource attached to this agent.
          x-ms-client-name: indexName
        query_type:
          $ref: '#/components/schemas/AzureAISearchQueryType'
          description: Type of query in an AIIndexResource attached to this agent.
          x-ms-client-name: queryType
        top_k:
          type: integer
          format: int32
          description: Number of documents to retrieve from search and present to the model.
          x-ms-client-name: topK
        filter:
          type: string
          description: filter string for search resource.
        index_asset_id:
          type: string
          description: Index asset id for search resource.
          x-ms-client-name: indexAssetId
    VectorStoreDataSource:
      type: object
      description: 'The structure, containing Azure asset URI path and the asset type of the file used as a data source

        for the enterprise file search.'
      properties:
        uri:
          type: string
          description: Asset URI.
          x-ms-client-name: assetIdentifier
        type:
          $ref: '#/components/schemas/VectorStoreDataSourceAssetType'
          description: The asset type
          x-ms-client-name: assetType
      required:
      - uri
      - type
    AgentDeletionStatus:
      type: object
      description: The status of an agent deletion operation.
      properties:
        id:
          type: string
          description: The ID of the resource specified for deletion.
        deleted:
          type: boolean
          description: A value indicating whether deletion was successful.
        object:
          type: string
          description: The object type, which is always 'assistant.deleted'.
          enum:
          - assistant.deleted
          x-ms-enum:
            modelAsString: false
      required:
      - id
      - deleted
      - object
    VectorStoreConfigurations:
      type: object
      description: The structure, containing the list of vector storage configurations i.e. the list of azure asset IDs.
      properties:
        name:
          type: string
          description: Name
          x-ms-client-name: storeName
        configuration:
          $ref: '#/components/schemas/VectorStoreConfiguration'
          description: Configurations
          x-ms-client-name: storeConfiguration
      required:
      - name
      - configuration
    ToolDefinition:
      type: object
      description: An abstract representation of an input tool definition that an agent can use.
      properties:
        type:
          type: string
          description: The object type.
      discriminator:
        propertyName: type
      required:
      - type
    Agent:
      type: object
      description: Represents an agent that can call the model and use tools.
      properties:
        id:
          type: string
          description: The identifier, which can be referenced in API endpoints.
        object:
          type: string
          description: The object type, which is always assistant.
          enum:
          - assistant
          x-ms-enum:
            modelAsString: false
        created_at:
          type: integer
          format: unixtime
          description: The Unix timestamp, in seconds, representing when this object was created.
          x-ms-client-name: createdAt
        name:
          type:
          - string
          - 'null'
          description: The name of the agent.
        description:
          type:
          - string
          - 'null'
          description: The description of the agent.
        model:
          type: string
          description: The ID of the model to use.
        instructions:
          type:
          - string
          - 'null'
          description: The system instructions for the agent to use.
        tools:
          type: array
          description: The collection of tools enabled for the agent.
          default: []
          items:
            $ref: '#/components/schemas/ToolDefinition'
        tool_resources:
          $ref: '#/components/schemas/ToolResources'
          description: '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.'
          x-ms-client-name: toolResources
        temperature:
          type:
          - number
          - 'null'
          format: float
          description: '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: 1
          minimum: 0
          maximum: 2
        top_p:
          type:
          - number
          - 'null'
          format: float
          description: '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: 1
          minimum: 0
          maximum: 1
          x-ms-client-name: topP
        response_format:
          $ref: '#/components/schemas/AgentsResponseFormatOption'
          description: The response format of the tool calls used by this agent.
          x-ms-client-name: responseFormat
        metadata:
          type:
          - object
          - 'null'
          description: 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.
          additionalProperties:
            type: string
      required:
      - id
      - object
      - created_at
      - name
      - description
      - model
      - instructions
      - tools
      - tool_resources
      - temperature
      - top_p
      - metadata
  parameters:
    GetAgentOptions:
      name: assistantId
      in: path
      description: Identifier of the agent.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    DeleteAgentOptions:
      name: assistantId
      in: path
      description: Identifier of the agent.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    UpdateAgentOptions.assistantId:
      name: assistantId
      in: path
      description: The ID of the agent to modify.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
    Azure.Core.Foundations.ApiVersionParameter:
      name: api-version
      in: query
      description: The API version to use for this operation.
      required: true
      x-ms-parameter-location: method
      x-ms-client-name: apiVersion
      schema:
        type: string
        minLength: 1
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://ai.azure.com/.default: ''
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    in: path
    description: 'Project endpoint in the form of: https://<aiservices-id>.services.ai.azure.com/api/projects/<project-name>'
    required: true
    type: string
    format: uri
    x-ms-skip-url-encoding: true