Let's Try Running the Assistants API from VS Code!

Note: Assistants API is in beta at the time of writing (November 2023). Specifications may change in the future.

OpenAI had its developer conference recently (11/7).
One of the highlights announced there was the Assistants API!
The Assistants API is an incredibly powerful feature that allows you to handle things like RAG (AI that answers by referencing documents) and Agents (like an enhanced version of ChatGPT) all in one place!!

If you haven't checked out the video yet, please do! It's easy to follow with English subtitles.

https://www.youtube.com/watch?v=U9mJuUkhUzk

What is Assistants API?

Before diving into the code, let's quickly look at four important concepts for understanding the Assistants API!

• Assistant
• Thread
• Run
• Message

Assistant

An Assistant is a configuration for responding to messages from users. Specifically, it can be customized with the following elements!

Instructions: Defines how the Assistant or model behaves or responds.
Model: You can specify GPT-3.5 or GPT-4 models, as well as fine-tuned models.
Tools: API-supported tools provided by OpenAI, such as code-interpreter and RAG, are available. You can also define your own.

Thread

A Thread represents a conversation. You can add user-specific contexts, text, and files to a Thread as messages.

Run

By executing a Run, the Assistant reads the Thread and decides whether to call tools or use only the model to find the best answer for the user's input. Once the Run is complete, the assistant adds a message to the Thread as "role='assistant'".

Message

It's exactly what it sounds like: a Message.

The general idea is that you get a response from the Assistant by turning Messages into a Thread and executing a Run!

Execution Code

The following code is based on the introduction below, modified to be executable in VS Code.
https://platform.openai.com/docs/assistants/overview
In this example, the Assistant is set up as a math tutor to solve a math problem using the code-interpreter.

from openai import OpenAI
import time

client = OpenAI()

# Create a new assistant
assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="You are a personal math tutor. Write and run code to answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview"
)

# To retrieve a specific assistant
# assistant = client.beta.assistants.retrieve("Assistant_ID")

# Create a new thread
thread = client.beta.threads.create()

# Create a message in the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Create a Run to execute the assistant and respond to the user's question
run = client.beta.threads.runs.create(
  thread_id=thread.id,
  assistant_id=assistant.id,
)

# Repeatedly check until the Run status becomes "completed"
while not run.status == "completed":
  run = client.beta.threads.runs.retrieve(
    thread_id=thread.id,
    run_id=run.id
  )
  time.sleep(0.1)  # Wait for 0.1 seconds
  print(run.status)  # Display current status

# Retrieve all messages added to the thread
messages = client.beta.threads.messages.list(
  thread_id=thread.id
)

role_value = []

# Retrieve role and content from each message
for thread_message in messages.data:
    role = thread_message.role
    for content in thread_message.content:
        content = content.text.value
        role_value.append((role, content))

# Reverse the list order using the reverse method
role_value.reverse()

# Display the content of the messages
for role, value in role_value:
    print(f"{role} : {value}")

An OpenAI API key is required to run this!
If you haven't obtained one yet, please refer to other articles to get and set your API key.

Let me explain the important parts!

Assistant

assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="You are a personal math tutor. Write and run code to answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview"
)

Here, the Assistant settings are being configured. In this example, it is set up as a math tutor named "Math Tutor". This assistant is instructed to write and run code to answer math questions. The tools used are the "code_interpreter" and the "gpt-4-1106-preview" model.

Thread

thread = client.beta.threads.create()

A new Thread is being created. It is also possible to retrieve an existing Thread.

message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

Here, a user message is being added to the Thread created earlier. It asks for help to solve the equation "3x + 11 = 14".

Run

run = client.beta.threads.runs.create(
  thread_id=thread.id,
  assistant_id=assistant.id,
)

By executing a Run, the Assistant reads the Thread and prepares a response to the user's inquiry.

while not run.status == "completed":
  run = client.beta.threads.runs.retrieve(
    thread_id=thread.id,
    run_id=run.id
  )
  time.sleep(0.1)  # Wait for 0.1 seconds
  print(run.status)  # Display current status

In this loop, the status is monitored until the Run status becomes "completed". Using the Code Interpreter may take longer than standard language models. Once finished, the Run status will be displayed as "completed".

If you proceed to the next step before the Run is finished, you will not be able to receive the response from the Assistant.

Message

messages = client.beta.threads.messages.list(
  thread_id=thread.id
)

This retrieves all messages within the thread.

If you want to learn more about the API details, please refer to the official documentation below!
https://platform.openai.com/docs/api-reference/assistants

Finally

How did you like it? Through this article, I've introduced the basic concepts and actual usage of the Assistants API. I hope you've understood the overall flow, from creating an Assistant and initializing a Thread to adding user messages, executing a Run, and finally retrieving the messages.

This API is a powerful tool that doesn't just answer questions, but can also perform more complex tasks and deepen interaction with users. It can be applied in various ways, from using Code Interpreter to implementing custom functions. Additionally, by customizing the Assistant's responses, you can provide personalized experiences tailored to each user.

This is just the beginning of the infinite possibilities offered by the Assistants API. Please look forward to the evolution of this technology and the new use cases it will bring. Let's create valuable experiences for users by utilizing the Assistants API. I hope this article helps you on your development journey. Happy coding!