The Assistants API offers a robust framework for developers to create AI assistants tailored to their applications. With the API, you can seamlessly integrate conversational agents, define custom actions, and leverage pre-built tools to enhance user experiences.

For a quick introduction and hands-on experience with assistants see Assistant in Action under getting started.

Comparison with Traditional Models

AI assistants offer a significant advantage over traditional models, especially in terms of speed and flexibility. With a 10x speed improvement, assistants can generate responses, execute actions, and retrieve information much faster, streamlining workflows and saving valuable time.

Assistants excel in use cases where:

  • Real-time interaction is required, such as customer support or live chat.
  • Complex, multi-step tasks need to be executed, like scheduling, task automation, or data retrieval.
  • Custom workflows are needed, leveraging dynamic tool integration to fit specific needs.

By combining speed with customizability, assistants outshine traditional models in dynamic, user-interactive environments.

What You Can Do with a Custom AI Assistant

  • Get Up-to-Date Information: Ask questions like, “What is the current weather in my city?”
  • Do a Web Search: Request current SEO updates.
  • Generate Images: Create images in threads via Flux.
  • Automate Your Workflow: Book a meeting with your team for next Tuesday at 10 a.m.
  • And More

Assistant’s Workflow

Tune Assistant Workflow is powered by a function call model which holds the capacity to semantically check for any potential calls to a function instead of the usual llm operations, and further if there are Tune Assistant Tools defined executes them on a priority over the existing OpenAI Format Tools.

1. Normal Query (Tools = OFF)

  • Request: A simple query, e.g., “What is 2 + 2?”
  • Process:
    • The request is sent to the function model.
    • The function model processes the request using only the language model (LLM) without any additional tools.
    • The response is generated and sent directly back to the user.

2. Search Internet (Tools = ON)

  • Request: A more complex query that requires external information, e.g., “What movies are playing…”
  • Process:
    • The request is sent to the function model.
    • The function model identifies that this query requires a specific tool (“find_movies”) to fetch real-time data.
    • It checks if a Tune Tool is available for this operation.
      • If “Yes”, it proceeds with running the Tune Tool.
      • The tool performs its operation (e.g., searching for current movie listings).
      • Results from the tool are processed by the response model.
      • Finally, the response is delivered back to the user.

3. Custom Functions

  • Request: Similar complex query requiring specific operations, e.g., “What movies are playing…”
  • Process:
    • The request is sent to the function model.
    • The function model identifies that this query requires a specific tool (“find_movies”).
    • It checks if a Tune Tool is available for this operation.
      • If “No”, it handles like a normal function call using only LLM or default methods without any additional tools.
      • Directly generates and sends back a response to the user.

Getting Started

To begin working with AI assistants, you have two options:

  1. Interactive Assistant Playground: Prototype and test Assistant functionality quickly without writing code.
  2. Integrate with the Assistant API:: Build Assistant functionality directly into your applications. View Assistant API reference doc)

Create an AI Assistant in Minutes using Tune Assistant Playground

  1. Build an Assistant by Providing a Model ID: This ID will be used in all APIs.

  2. Set Specific Instructions: Define the instructions that the assistant needs to follow.

  3. Choose the Response Model: Select a model that combines responses from multiple tools to generate the final output.

  4. Select the Function Calling Model: Pick a model that enables the assistant to decide which function to call.

  5. Pre-Set Tools: Equip your assistant with tools such as:

    • Search: Enable the assistant to perform web searches (note: it cannot visit the search results).
    • Image Generation: Allow the assistant to generate creative images.
  6. Specify Actions: Define the actions your assistant can perform. Actions serve as messengers between your LLMs and external applications, helping you:

    • Interact with External Apps: Connect with outside applications using RESTful APIs by providing an OpenAPI spec.
    • Retrieve Data: Fetch information from external applications, such as recent orders.
    • Take Actions: Perform tasks in other applications, like sending an email.
  7. Function Calling: Describe your function to the model. Function calling allows you to access real-time data and execute custom functions within a specific context, enabling the assistant to perform tasks that go beyond simple text-based conversations.

    Large Language Models (LLMs) that Support Function Calling

    • OpenAI: GPT-3.5 Turbo, GPT-4
    • Google: Gemini
    • Anthropic: Claude
    • Cohere: Command R, Command R+
    • Mistral: Small, Large, Mixtral 8x22B
    • NexusRaven
    • Gorilla OpenFunctions
    • Nous Hermes 2 Pro

Create an AI Assistant using API

This section focuses on using the Assistants API to create and manage assistants in detail.

Interaction Methods

The Assistants API offers two primary ways to interact with your AI assistants:

  1. Threads: Ideal for maintaining context in longer conversations.
  2. Chat: Perfect for quick, real-time interactions.

API Basics

To create a new assistant, send a POST request to the /v1/assistants endpoint. You’ll need to provide the following essential information:

  • Assistant name
  • Function calling model
  • Response model

Prerequisites

  • Tune API key: Use x-tune-key in the header. You can access your API keys here, under your profile.
  • Organization ID: Use X-Org-Id in the header. If not provided, the default organization is used. You can find your organization ID here.

Tool Usage During Inference

By default, some LLMs on Tune Studio use built-in tools for common tasks like data retrieval and factual queries. However, custom tools take priority. When an inference is made, the assistant checks for matching custom tools first. If no match is found, it falls back on default tools.

  • Custom Tools First: Custom tools always execute before default tools for the same action.
  • Default Tools as Fallback: If no custom tool is defined, default tools handle the request.
  • Custom Overrides: Custom tools override any default tool for the same function.

Custom Actions and Functions can be fine-tuned dynamically during inference to suit specific needs.

Creating a Basic Assistant

Required Fields:

  • Model name: Must be unique within your organization. Changing the model name in the future will affect associated APIs.
  • Function model: Can be a public model available in Tune or any deployed model on Tune that supports function-calling.
  • Response model: Similar to the function model, it can be a public or deployed model.

Not all models support function calling. Some models excel at function calling, while others are better for generating responses.

Example Request

curl -X POST "https://studio.tune.app/v1/assistants" \
 -H 'accept: application/json' \
 -H 'content-type: application/json' \
 -H 'x-tune-key: <YOUR-TUNE-KEY>' \
 -H 'X-Org-Id: <YOUR-ORG-ID>' \
 -d '{
  "modelName": "exampleassistant",
  "functionModel": {
    "modelId": "MODEL_ID"
  },
  "responseModel": {
    "modelId": "MODEL_ID"
  }
}'

Customizing Function and Response Models

You can customize the behavior of your function and response models by adjusting the following parameters:

  • temperature: Accepts a floating-point value between 0 and 1.

  • topP: Accepts a probability floating-point between 0 and 1.

    Example Request with Customization

    curl -X POST "https://studio.tune.app/v1/assistants" \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H 'x-tune-key: <YOUR-TUNE-KEY>' \
     -H 'X-Org-Id: <YOUR-ORG-ID>' \
     -d '{
      "modelName": "exampleassistant1",
      "functionModel": {
        "modelId": "MODEL_ID",
        "temperature": 0.5,
        "topP": 0.9
      },
      "responseModel": {
        "modelId": "MODEL_ID",
        "temperature": 0.5,
        "topP": 0.9
      }
    }'
    

    Best Practices for Temperature Settings:

    The temperature setting controls randomness in the assistant’s output. Lower values result in more focused and deterministic responses, while higher values increase creativity.

    • Low (0.1–0.3): Use for factual and precise tasks, like answering technical queries.
    • Medium (0.4–0.7): A balance between accuracy and creativity.
    • High (0.8+): Suitable for creative tasks, where diverse and unexpected responses are useful.

    Experiment with different values to find the best fit for your use case.

Adding Description and Instructions

Enhance your assistant with additional information:

  • Assistant Name: A meaningful name to help team members identify the assistant (for reference only).

  • Description: Provides context about the assistant (for reference only).

  • Instructions: Custom instructions to control the assistant’s behavior and define its goals.

    Example Request with Metadata

    curl -X POST "https://studio.tune.app/v1/assistants" \
     -H "accept: application/json" \
     -H "content-type: application/json" \
     -H "x-tune-key: <YOUR-TUNE-KEY>" \
     -H 'X-Org-Id: <YOUR-ORG-ID>' \
     -d '{
      "assistantName": "Go-lang-assistant",
      "modelName": "exampleassistant",
      "description": "The Go-lang Assistant is a powerful tool for Go developers, allowing them to write, run, and debug Go code directly within the Assistant interface",
      "instructions": "You are a software developer and solely use golang. You just give the code without any explanation on how it works. Bias towards the most efficient solution.",
      "functionModel": {
        "modelId": "MODEL_ID"
      },
      "responseModel": {
        "modelId": "MODEL_ID"
      }
    }'
    

Creating an Assistant with Tune Tools

Tune currently supports two built-in tools: web search and image generation. To use these tools, you can include them in the tools array of your request with the name “web_search” or “generate_image” and type “tune”.

Web Search Tool

To enable web search for your assistant, use the following example:

curl -X POST "https://studio.tune.app/v1/assistant" \
 -H "accept: application/json" \
 -H "content-type: application/json" \
 -H "x-tune-key: <YOUR-TUNE-KEY>" \
 -H "X-Org-Id: <YOUR-ORG-ID>" \
 -d '{
   "modelName": "exampleassistant",
   "functionModel": {
     "modelId": "MODEL_ID"
   },
   "responseModel": {
     "modelId": "MODEL_ID"
   },
   "tools": [
     {
       "name": "web_search",
       "type": "tune"
     }
   ]
 }'

Image Generation Tool

To enable image generation for your assistant, use the following example:

curl -X POST "https://studio.tune.app/v1/assistant" \
 -H "accept: application/json" \
 -H "content-type: application/json" \
 -H "x-tune-key: <YOUR-TUNE-KEY>" \
 -H "X-Org-Id: <YOUR-ORG-ID>" \
 -d '{
   "modelName": "exampleassistant6",
   "functionModel": {
     "modelId": "MODEL_ID"
   },
   "responseModel": {
     "modelId": "MODEL_ID"
   },
   "tools": [
     {
       "name": "generate_image",
       "type": "tune"
     }
   ]
 }'

Creating an Assistant with Custom Tools

You can add custom functions to your assistant by including tools with the type “user_function”.

Ensure that your function adheres to the schema format specified. Use the required field to specify mandatory parameters that cannot be left blank.

Here’s an example of creating an assistant with a custom tool for getting stock information:

curl -X POST "https://studio.tune.app/v1/assistant" \
 -H "accept: application/json" \
 -H "content-type: application/json" \
 -H "x-tune-key: <YOUR-TUNE-KEY>" \
 -H "X-Org-Id: <YOUR-ORG-ID>" \
 -d '{
   "modelName": "exampleassistant",
   "functionModel": {
     "modelId": "MODEL_ID"
   },
   "responseModel": {
     "modelId": "MODEL_ID"
   },
   "tools": [
     {
       "type": "user_function",
       "function": {
         "name": "get_stock",
         "description": "Get stock information based on symbol.",
         "parameters": {
           "type": "object",
           "properties": {
             "symbol": {
               "type": "string",
               "description": "The symbol to get stock information for."
             }
           },
           "required": ["symbol"]
         }
       }
     }
   ]
 }'

Creating an Assistant with Actions

To integrate external APIs and services into your assistant, you can use the tune_action tool type. This allows you to define actions based on OpenAPI specifications.

Required fields for creating an action

  • tools: An array of tools, where each tool represents an action that can be performed by the assistant.
  • type: Specifies the type of tool, which should be “tune_action” for external API integrations.
  • name: Specifies the name of the action.
  • openapiSpec: Specifies the OpenAPI specification for the action. This specification defines the API endpoint, request and response bodies, and other details.
  • openapiActionData: Specifies additional data required for the action, such as API keys or headers.

Example: Creating an Assistant with a Search Action

Here’s an example of creating an assistant with a search action using the Google Serper API:

 curl -X POST "https://studio.tune.app/v1/assistant" \
     -H "accept: application/json" \
     -H "content-type: application/json" \
     -H "x-tune-key: <YOUR-TUNE-KEY>" \
     -H "X-Org-Id: <YOUR-ORG-ID>" \
     -d '{
  "modelName": "exampleassistant",
  "functionModel": {
    "modelId": "MODEL_ID"
  },
  "responseModel": {
    "modelId": "MODEL_ID"
  },
  "tools": [
    {
      "type": "tune_action",
      "name": "performSearch",
      "openapiSpec": {
        "openapi": "3.0.0",
        "info": {
          "title": "Google Serper API",
          "version": "1.0.0",
          "description": "API to perform search queries."
        },
        "servers": [
          {
            "url": "https://google.serper.dev"
          }
        ],
        "paths": {
          "/search": {
            "post": {
              "operationId": "performSearch",
              "summary": "Perform a search query",
              "requestBody": {
                "content": {
                  "application/json": {
                    "schema": {
                      "type": "object",
                      "properties": {
                        "q": {
                          "type": "string",
                          "description": "The search query string"
                        }
                      },
                      "required": [
                        "q"
                      ]
                    },
                    "example": {
                      "q": "apple inc"
                    }
                  }
                },
                "required": true
              },
              "responses": {
                "200": {
                  "description": "Successful response",
                  "content": {
                    "application/json": {
                      "schema": {
                        "type": "string"
                      },
                      "example": "Result of the search query"
                    }
                  }
                },
                "default": {
                  "description": "Unexpected error"
                }
              },
              "security": [
                {
                  "apiKeyAuth": []
                }
              ]
            }
          }
        },
        "components": {
          "securitySchemes": {
            "apiKeyAuth": {
              "type": "apiKey",
              "in": "header",
              "name": "X-API-KEY"
            }
          }
        }
      },
      "openapiActionData": {
        "headers": {
          "X-API-KEY": "Your serper api key"
        }
      }
    }
  ]
}'

Get an Assistant

This API endpoint retrieves an assistant . You can use this endpoint to fetch the details of an existing assistant. The response will contain the details of the assistant, including its model name and tools.

 curl -X POST "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
 -H "accept: application/json"\
 -H "content-type: application/json"\
 -H "x-tune-key: <YOUR-TUNE-KEY>" \
 -H "X-Org-Id: <YOUR-ORG-ID>" \

Delete an Assistant

This API endpoint retrieves an assistant. You can use this endpoint to fetch the details of an existing assistant. The response will contain the details of the assistant, including its model name and tools.

 curl -X DELETE "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
 -H "accept: application/json"\
 -H "content-type: application/json"\
 -H "x-tune-key: <YOUR-TUNE-KEY>" \
 -H "X-Org-Id: <YOUR-ORG-ID>" \

List an Assistant

This API endpoint lists assistants. You can use this endpoint to fetch a list of assistants, including their names, IDs, and other details. The response will contain a list of assistants, and you can use the limit, order, after, and before query parameters to control the results.

 curl -X GET "https://studio.tune.app/v1/assistants?limit=10&order=asc&after=<PAGINATION_TOKEN_FETCHING_NEXT_PAGE>&before=<PAGINATION_TOKEN_FETCHING_PREVIOUS_PAGE>" \
 -H "accept: application/json"\
 -H "content-type: application/json"\
 -H "x-tune-key: <YOUR-TUNE-KEY>" \
 -H "X-Org-Id: <YOUR-ORG-ID>" \

Query Parameters

  • limit: The maximum number of assistants to return (default: 10)
  • order: The order in which to return the assistants (default: asc)
  • after:: The pagination token for fetching the next page (optional)
  • before: The pagination token for fetching the previous page (optional)

Modifying an Assistant

This guide explains how to modify an existing assistant using the API.

To update an existing assistant, send a PATCH request to:

  https://studio.tune.app/v1/assistants/{assistantId}

Request headers

Include the following headers in your request:

  • accept: application/json
  • content-type: application/json
  • x-tune-key: <YOUR-TUNE-KEY>
  • X-Org-Id: <YOUR-ORG-ID>

Request body

The request body should include:

  1. An assistant object with the fields you want to update.
  2. An updateMask specifying which fields to update.
You can update multiple fields at once by including them in the assistant object and listing them in the updateMask.

Modifiable Fields

You can modify the following fields:

  • assistantName
  • modelName
  • description
  • instructions
  • functionModel
  • responseModel
  • tools

Modifying Assistant Name:

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "assistantName": "sampleAssistant"
  },
  "updateMask": "assistantName"
}'

Modifying Model Name:

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "modelName": "sample-assistant"
  },
  "updateMask": "modelName"
}'
Changing the modelName will change all integrated models.

Modifying Description:

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "description": "Built on top of large language models, I can understand and respond to a wide range of questions and topics."
  },
  "updateMask": "description"
}'

Modifying Instructions:

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "instructions": "You will be provided with a piece of Python code, and your task is to find and fix bugs in it."
  },
  "updateMask": "instructions"
}'

Modifying Function Model:

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "functionModel": {
      "modelId": "MODEL_ID",
      "temperature": 0.5,
      "topP": 0.5
    }
  },
  "updateMask": "functionModel"
}'
When modifying functionModel, you can only update the entire model configuration, not individual fields like temperature or top-p.

Modifying Response Model:

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "responseModel": {
      "modelId": "MODEL_ID",
      "temperature": 0.5,
      "topP": 0.5
    }
  },
  "updateMask": "responseModel"
}'
Similar to functionModel, when modifying responseModel, you can only update the entire model configuration, not individual fields.

Replacing Tools

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "tools": [
      {
        "name": "web_search",
        "type": "tune"
      },
      {
        "type": "user_function",
        "function": {
          "name": "get_stock",
          "description": "Get stock information based on symbol.",
          "parameters": {
            "type": "object",
            "properties": {
              "symbol": {
                "type": "string",
                "description": "The symbol to get stock information for."
              }
            },
            "required": ["symbol"]
          }
        }
      },
      {
        "type": "tune_action",
        "name": "performSearch",
        "openapiSpec": "{ ... }",
        "openapiActionData": {
          "headers": "{\"X-API-KEY\":\"your serper api key\"}",
          "privacy_policy": "",
          "parent_action_id": "b951f27d-040d-49bd-9a2c-575f329fb750"
        }
      }
    ]
  },
  "updateMask": "tools"
}'
  • Updating tools replaces all existing tools, including actions.
  • Tool types:
    • tune: Built-in tools like web search and image generation
    • user_function: Custom functions
    • tune_action: Actions

Deleting All Tools

curl -X PATCH "https://studio.tune.app/v1/assistant/<YOUR-ASSISTANT-ID>" \
-H "accept: application/json" \
-H "content-type: application/json" \
-H "x-tune-key: <YOUR-TUNE-KEY>" \
-H "X-Org-Id: <YOUR-ORG-ID>" \
-d '{
  "assistant": {
    "tools": []
  },
  "updateMask": "tools"
}'
Use an empty list to delete all tools.

Assistant Glossary

This glossary provides definitions for key terms and concepts related to AI assistants.

Assistant

An AI designed to perform specific tasks, leveraging:

  • Open source and deployed models
  • Internal tools (e.g., web search and image generation)
  • Custom tool integrations
  • Ability to execute actions

Threads

A conversation session between an Assistant and a user that:

  • Stores Messages in Threads
  • Handles truncation automatically
  • Ensures content fits the model’s context

Function Model

A model that:

  • Decides whether to call a function
  • Determines which function to call
  • Generates a JSON object of strings adhering to your custom schema when a function is called

Response Model

A model that:

  • Combines responses from multiple tools
  • Appends structured responses returned by functions
  • Summarizes results
  • Sends the final output as a response to the user

Tools

Enhance assistant capabilities by:

  • Enabling more complex tasks
  • Facilitating seamless interaction with your application
  • Offering built-in tools (e.g., web search and image generation)
  • Allowing creation of custom tools using Function Calling

Function Calling

A flexible integration method that:

  • Connects Assistants with external systems, services, or applications
  • Allows defining and registering functions with the Tune Assistants API
  • Intelligently determines when and which functions to invoke
  • Provides corresponding arguments to complete specific tasks

Only some models provide function calling capabilities.

Temperature

A parameter that:

  • Controls randomness in output
  • Increases diversity with higher values

Top-p

A parameter that:

  • Sets the cumulative probability cutoff for token selection
  • Results in sampling from a smaller, more top-weighted nucleus with lower values

Actions

Facilitate interaction with external applications by:

  • Using RESTful API calls outside of Tune
  • Requiring only the JSON schema for the API call
  • Enabling data retrieval (e.g., getting a list of recent orders)
  • Allowing actions in other applications (e.g., sending an email)

Assistant schema

{
  "assistantName": "string",
  "modelName": "string",
  "description": "string",
  "instructions": "string",
  "functionModel": {
    "modelId": "string",
    "temperature": 0,
    "topP": 0
  },
  "responseModel": {
    "modelId": "string",
    "temperature": 0,
    "topP": 0
  },
  "tools": [
    {
      "id": "string",
      "name": "string",
      "type": "string",
      "function": {
        "name": "string",
        "description": "string",
        "parameters": {},
        "required": [
          "string"
        ]
      },
      "openapiSpec": "string",
      "openapiActionData": {}
    }
  ],
  "metadata": {},
  "userFilters": {}
}