Everything You Need to Know About Assistants in 5 Minutes

Introduction to Building AI Assistants

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.

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.

Getting Started

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

Use the Assistants API: Integrate Assistant capabilities directly into your applications.
Explore the Tune Assistants Playground: Alternatively, you can explore the Assistants capabilities in the interactive Tune Assistants Playground.

Interaction Methods

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

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

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": {}
}

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

Replace YOUR_AUTH_TOKEN with your actual authentication token or API key. Use “x-tune-key” in the header.

Include your organization ID as x-org-id to specify your organization. If not provided, the default organization is used.

-H "x-org-id: <YOUR-ORG-ID>"

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": "rohan/tune-gpt-4o"
  },
  "responseModel": {
    "modelId": "rohan/tune-gpt-4o"
  }
}'

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.
Top P: 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": "rohan/tune-gpt-4o",
    "temperature": 0.5,
    "topP": 0.9
  },
  "responseModel": {
    "modelId": "rohan/tune-gpt-4o",
    "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": "rohan/tune-gpt-4o"
  },
  "responseModel": {
    "modelId": "rohan/tune-gpt-4o"
  }
}'

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": "rohan/tune-gpt-4o"
   },
   "responseModel": {
     "modelId": "rohan/tune-gpt-4o"
   },
   "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": "rohan/tune-gpt-4o"
   },
   "responseModel": {
     "modelId": "rohan/tune-gpt-4o"
   },
   "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": "rohan/tune-gpt-4o"
   },
   "responseModel": {
     "modelId": "rohan/tune-gpt-4o"
   },
   "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.
openapiActionData: Specifies additional data required for the action, such as API keys.

OpenAPI Specification

The openapiSpec field contains the OpenAPI specification for the action. This specification defines the API endpoint, request and response bodies, and other details.

Action Data

The openapiActionData field contains 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": "rohan/tune-gpt-4o"
  },
  "responseModel": {
    "modelId": "rohan/tune-gpt-4o"
  },
  "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:

An assistant object with the fields you want to update.
An updateMask specifying which fields to update.

Note: 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

Examples

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"
}'

Note: 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": "rohan/llama3-slora-16july",
      "temperature": 0.5,
      "topP": 0.5
    }
  },
  "updateMask": "functionModel"
}'

Note: 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": "rohan/llama3-slora-16july",
      "temperature": 0.5,
      "topP": 0.5
    }
  },
  "updateMask": "responseModel"
}'

Note: 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"
}'

Notes:

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"
}'

Note: Use an empty list to delete all tools.

Was this page helpful?

Notion Recipe Generator Edge cases

On this page

Introduction to Building AI Assistants
Comparison with Traditional Models
Getting Started
Interaction Methods
Assistant Glossary
Assistant
Threads
Function Model
Response Model
Tools
Function Calling
Temperature
Top-p
Actions
Assistant schema
API Basics
Tool Usage During Inference
Creating a Basic Assistant
Required Fields
Example Request
Customizing Function and Response Models
Example Request with Customization
Best Practices for Temperature Settings
Adding Description and Instructions
Example Request with Metadata
Creating an Assistant with Tune Tools
Web Search Tool
Image Generation Tool
Creating an Assistant with Custom Tools
Creating an Assistant with Actions
Required Fields for Creating an Action
OpenAPI Specification
Action Data
Example: Creating an Assistant with a Search Action
Get an assistant
Delete an assistant
List an assistant
Modifying an Assistant
Request Headers
Request Body
Modifiable Fields
Examples
Modifying Assistant Name
Modifying Model Name
Modifying Description
Modifying Instructions
Modifying Function Model
Modifying Response Model
Replacing Tools
Deleting All Tools

Cookbook

​Introduction to Building AI Assistants

​Comparison with Traditional Models

​Getting Started

​Interaction Methods

​Assistant Glossary

​Assistant

​Threads

​Function Model

​Response Model

​Tools

​Function Calling

​Temperature

​Top-p

​Actions

​Assistant schema

​API Basics

​Tool Usage During Inference

​Creating a Basic Assistant

​Required Fields

​Example Request

​Customizing Function and Response Models

​Example Request with Customization

​Best Practices for Temperature Settings

​Adding Description and Instructions

​Example Request with Metadata

​Creating an Assistant with Tune Tools

​Web Search Tool

​Image Generation Tool

​Creating an Assistant with Custom Tools

​Creating an Assistant with Actions

​Required Fields for Creating an Action

​OpenAPI Specification

​Action Data

​Example: Creating an Assistant with a Search Action

​Get an assistant

​Delete an assistant

​List an assistant

​Modifying an Assistant

​Request Headers

​Request Body

​Modifiable Fields

​Examples

​Modifying Assistant Name

​Modifying Model Name

​Modifying Description

​Modifying Instructions

​Modifying Function Model

​Modifying Response Model

​Replacing Tools

​Deleting All Tools