OpenAI Assistants: How to create and use them
Want to create your own AI Assistant where you can feed in your own data, run code on the fly, or made calls to external code? Read this tutorial to learn how.
Dec 15, 2023 • 7 Minute Read
OpenAI recently unleashed a slew of cool new features, with the Assistants API being a standout. Imagine having a personal assistant or a custom ChatGPT, but with an added touch of magic. Not only does it have all the power of the underlying GPT models, but it has some sweet-sweet extras like the integration of your own data, the execution of Python code, and the use of custom functions and external APIs.
In this article, we’ll build an Assistant together. We’ll start in the user-friendly Playground UI (no coding skills required), and then move on to writing one with Python code. Note that the Assistants API is still in beta, so we should expect some changes as we move towards a full-scale launch.
Table of contents
How to create an Assistant using the Playground UI
Create the assistant
To more easily grasp the concept of an Assistant and what it can do, we’ll start in the Playground UI. This does require an account, which is free to create, but know that you will be charged for tokens used. We’re likely talking cents here, not dollars, but see OpenAI pricing for more.
After navigating to the OpenAI Playground, select Assistants from the top dropdown. Then select the down arrow below that, and choose + Create assistant.
Now fill out the details for the assistant. Feel free to choose your own, or follow along with mine, which will be a travel agent.
Name: Terrific Travels
Instructions: You are a travel agent who specializes in world travel, on all seven continents. You'll be provided with data indicating travel background and preferences. Your job is to suggest itineraries for travel, and give me tips about things like best time to travel, what to pack, etc.
Model: gpt-4-1106-preview. You can choose another model, but at the moment, this model is the only one that will let you upload your own data files, which is something we’ll need to do.
Choose your tools
Tools are the sweet-sweet extras I mentioned above. We currently have three options:
Functions: This lets the assistant call custom functions or external APIs. If you’re building a travel assistant, perhaps you could call an API to check airfares.
Code interpreter: This enables the assistant to write and run Python code in a sandboxed environment. Say you wanted it to crunch some numbers and then create a visualization for you on the fly. No problem!
Retrieval: This tool lets you upload files for the assistant to consider when answering questions. This basically fine-tunes the assistant by augmenting its general knowledge with whatever you feed it.
For our Terrific Travel assistant, I’d like to take advantage of the Retrieval tool by uploading a CSV file about travel preferences. This file contains preferred activities, preferred time of year to travel, budget, and a list of countries already visited. Here’s a preview of the CSV:
In the Playground, toggle Retrieval on, and then browse to the file(s) you’d like to upload (for me, this is TravelPreferences.csv).
Save the assistant by clicking Save.
After your assistant successfully saves, it will be assigned an assistant ID. If you plan to use this assistant programmatically in the future, this is a handy place to grab the ID.
Run the assistant
Now that the assistant is set up, it’s time to take it for a run. Enter whatever message you’d like, and then click Run.
And, like a good assistant, we get a tailored travel recommendation based on the data passed in with the CSV file. Nice!
How to create an Assistant using the Python APIs
Let's start with some key concepts
If you built out an assistant using the Playground UI above, then you unknowingly learned some concepts that will be useful as you start writing code. Let’s touch on the core building blocks that make all of this work, namely: Assistant, Thread, Message, Run and Run Step.
First, a visual…
And what it all means…
OBJECT | WHAT IT REPRESENTS |
Assistant | Your personal assistant that uses the OpenAI models and tools like Functions, Code Interpreter and Retrieval. |
Thread | A conversation session between a user and the Assistant. Threads are made up of Messages. |
Message | A message created by the user or the assistant. These can be text, images or other files. Messages are stored as a list on the Thread. |
Run | An invocation of an Assistant on a Thread. A Run pulls together the details of the Assistant, along with a Thread’s Messages, then calls models and tools. During the Run, the Assistant appends Messages to the Thread. |
Run Step | A list of steps the Assistant should undertake as part of a Run, such as creating messages or calling tools. |
To make it more concrete, here’s a look at the concepts from the assistant we created in the Playground UI…
Setting up the Python code
Okay. With the concepts out of the way, let’s dig into the code. I’ll be using VS Code, but you can use another IDE if you’d like.
Create a file called assistant.py. And if you’ll be providing a file to the assistant, add that file in the same location (for me, this is TravelPreferences.csv).
Next, make sure you have the latest version of the SDK by opening a terminal and typing:
pip install --upgrade openai
Below is the code to create and run the assistant, complete with threads, messages and runs. Copy this code to assistants.py and check out the code comments for what each code block is doing.
# Imports
from openai import OpenAI
# Update with your API key
client = OpenAI(api_key="YOUR_API_KEY_HERE")
# Open the CSV file in "read binary" (rb) mode, with the "assistants" purpose
file = client.files.create(
file=open("TravelPreferences.csv", "rb"),
purpose='assistants'
)
# Create and configure the assistant
# Add the CSV file from above (using tool type "retrieval")
assistant = client.beta.assistants.create(
name="Terrific Travels",
instructions="You are a travel agent who specializes in world travel, on all seven continents. You'll be provided with data indicating travel background and preferences. Your job is to suggest itineraries for travel, and give me tips about things like best time to travel, what to pack, etc.",
model="gpt-4-1106-preview",
tools=[{"type": "retrieval"}],
file_ids=[file.id]
)
# Create a thread where the conversation will happen
thread = client.beta.threads.create()
# Create the user message and add it to the thread
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="I'd like help planning a new trip based on criteria for Amber. I'd prefer to visit a country I haven't been to yet. What would you suggest?",
)
# Create the Run, passing in the thread and the assistant
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id=assistant.id
)
# Periodically retrieve the Run to check status and see if it has completed
# Should print "in_progress" several times before completing
while run.status != "completed":
keep_retrieving_run = client.beta.threads.runs.retrieve(
thread_id=thread.id,
run_id=run.id
)
print(f"Run status: {keep_retrieving_run.status}")
if keep_retrieving_run.status == "completed":
print("\n")
break
# Retrieve messages added by the Assistant to the thread
all_messages = client.beta.threads.messages.list(
thread_id=thread.id
)
# Print the messages from the user and the assistant
print("###################################################### \n")
print(f"USER: {message.content[0].text.value}")
print(f"ASSISTANT: {all_messages.data[0].content[0].text.value}")
To run the code from the terminal, type:
python assistants.py
It will likely take a little while to run. While it’s in progress, you’ll see several “in_progress” messages, and then eventually the user and assistant messages will print, giving you some fabulous travel ideas.
Wrapping up
So there you go! Your own AI assistant at your service. This was a simple example, but hopefully you can appreciate how powerful these assistants are. Being able to feed in your own data, run code on-the-fly, and make calls to external code is a game-changer. Have fun incorporating assistants into your sites and apps to take them to the next level!
If you want to dig deeper in this space, you might also enjoy these additional resources:
