In the ever-evolving landscape of artificial intelligence, OpenAI continues to push boundaries with innovations that empower developers to create intelligent assistants. In this blog, we’ll explore the key features, steps to integrate, tools, and the potential of the OpenAI’s Assistants API.
What are OpenAI Assistants API?
The Assistants API by OpenAI allows developers to construct AI assistants within their applications. These assistants can respond to user queries by leveraging models, tools, and knowledge. Currently in beta, the API supports tools such as Code Interpreter, Retrieval, and Function calling.
The Assistants API is a testament to this effort, offering a powerful platform to build AI assistants seamlessly into applications. OpenAI has plans to introduce more tools and the ability for developers to provide their own tools.
Here are the key component you need to know about Assistants API:
1) Assistant
An Assistant is the core entity, configured with instructions, a chosen model, and optional tools. The below code illustrates a math tutor assistant with the Code Interpreter tool enabled.
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"
)2) Thread
A Thread represents a conversation session between the assistant and a user. It stores Messages, providing context for ongoing interactions.
thread = client.beta.threads.create()
3) Message
Messages contain user input and can include files. They form the communication history within a 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?"
)
4) Run
A Run triggers the assistant to respond based on the Thread’s context. It incorporates the assistant’s instructions and can call tools.
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id=assistant.id,
instructions="Please address the user as Jane Doe. The user has a premium account."
)5) Response
After running the assistant, the Messages added to the Thread provide the assistant’s responses.
messages = client.beta.threads.messages.list(
thread_id=thread.id
)How Assistants Work?
Here are the core capabilities of this new tool:
- Model Interaction: Assistants can call OpenAI’s models with specific instructions, allowing customization of personality and capabilities.
- Parallel Tool Access: Multiple tools can be accessed simultaneously, including OpenAI-hosted tools like Code Interpreter and custom tools via Function calling.
- Persistent Threads: Threads store message history, simplifying development by retaining context across interactions.
- File Handling: Assistants can access files in various formats, both for input and output. Tools can create files, and references can be cited in Messages.
Creating Assistants
To create an Assistant, specify the model, instructions, and tools. Additional customization, such as attaching files, enhances the assistant’s capabilities.
file = client.files.create(
file=open("speech.py", "rb"),
purpose='assistants'
)
assistant = client.beta.assistants.create(
name="Data visualizer",
description="You are great at creating beautiful data visualizations...",
model="gpt-4-1106-preview",
tools=[{"type": "code_interpreter"}],
file_ids=[file.id]
)
Managing Threads and Messages
Threads are instrumental in preserving the conversational context. Messages, containing text or files, facilitate user and assistant interactions.
thread = client.beta.threads.create(
messages=[
{
"role": "user",
"content": "Create 3 data visualizations based on the trends in this file.",
"file_ids": [file.id]
}
]
)Runs and Run Steps
Runs trigger the assistant to act on a Thread. The Run’s lifecycle involves queuing, in-progress execution, and completion.
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id=assistant.id
)
Run Steps detail the actions taken during a Run, including Message creation and tool calls.
Data Access and Limitations
Due to API key access, implement proper authorization and restrict key access. Consider creating separate accounts for different applications to isolate data.
While the API is in beta, certain limitations exist, such as the absence of streaming output support, notifications, and certain tool functionalities.
OpenAI Assistants API Tools
From coding to knowledge retrieval to intelligent function calling, your assistant can become a powerhouse. Here are some of the tools to know about the OpenAI Assistants API Tools:
Code Interpreter
Think of it as your assistant’s coding buddy. It can write and run Python code, making it a wizard at solving code and math problems. It can learn from mistakes. If the code fails, it can try a different approach until success.
How to Enable Code Interpreter?
When creating your assistant, just include “code_interpreter” in the tools parameter. Here’s a snippet in Python:
assistant = client.beta.assistants.create(
instructions="You are a personal math tutor. Write and run code to answer math questions.",
model="gpt-4-1106-preview",
tools=[{"type": "code_interpreter"}]
)
Passing Files to Code Interpreter
You can feed Code Interpreter files for analysis. These files can be at the assistant or thread level, allowing your assistant to access them during interactions.
Reading Code Interpreter Outputs
When Code Interpreter generates images or files, you can find the file ID in the assistant’s response. Download it using the file ID to see what magic your assistant has created.
Code Interpreter Logs
Check out the input and output logs using the Run Steps feature.
Knowledge Retrieval
What is Knowledge Retrieval?
Knowledge Retrieval empowers your assistant with external information. It can pull insights from documents, helping it answer user queries effectively.
How to Enable Retrieval?
To activate Retrieval, include “retrieval” in the tools parameter when creating your assistant. Like this:
assistant = client.beta.assistants.create(
instructions="You are a customer support chatbot. Use your knowledge base to respond to queries.",
model="gpt-4-1106-preview",
tools=[{"type": "retrieval"}]
)
Uploading Files for Retrieval
Just like with Code Interpreter, you can pass files to Retrieval. These files can be added at the assistant or thread level, enhancing your assistant’s knowledge.
Deleting Files
To tidy up, you can remove a file from your assistant by detaching it. This action also removes the file from the retrieval index.
File Citations
When your assistant mentions file paths, you can convert them into download links using annotations.
Function Calling
What is Function Calling?
Function Calling lets your assistant understand and execute functions intelligently. It pauses during a run, asks for function outputs, and continues the magic.
Defining Functions
Define functions when creating your assistant. It’s like giving it a playbook. Here’s a simple example:
assistant = client.beta.assistants.create(
instructions="You are a weather bot. Use the provided functions to answer questions.",
model="gpt-4-1106-preview",
tools=[{
"type": "function",
"function": {
"name": "getCurrentWeather",
"description": "Get the weather in location",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"},
"unit": {"type": "string", "enum": ["c", "f"]}
},
"required": ["location"]
}
}
}]
)
Reading Function Calls
When a user message triggers a function, the run enters a “requires_action” state. Retrieve the run to get details on the functions your assistant needs to execute.
Submitting Function Outputs
Complete the run by submitting tool outputs, providing results for each function call. This allows the run to continue its execution.
Learn more about the OpenAI’s function calling feature here.
Conclusion
Hope this guide will be a good introduction for beginners on Assistants API. It opens the door to building intelligent and interactive applications. By understanding the core components, customization options, tools, and data management, developers can create dynamic AI assistants that enhance user experiences. As the API evolves, the potential for more sophisticated and diverse functionalities is on the horizon.
