Skip to content

Contact sales

By filling out this form and clicking submit, you acknowledge our privacy policy.

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

Please set an alt value for this image...
  • Software Development
  • AI & Data

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:

Amber Israelsen

Amber I.

Amber has been a software developer and technical trainer since the early 2000s. In recent years, she has focused on teaching AI, machine learning, AWS and Power Apps, teaching students around the world. She also works to bridge the gap between developers, designers and businesspeople with her expertise in visual communication, user experience and business/professional skills. She holds certifications in machine learning, AWS, a variety of Microsoft technologies, and is a former Microsoft Certified Trainer.

More about this author