OpenAI Assistants: How to create and use them

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.

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:

And what it all means…

      # 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}")