The Assistants API is in beta. This API is deprecated and may be removed in future versions. Consider using the Responses API for new applications. Overview The Assistants API allows you to build AI assistants with custom instructions, tools (Code Interpreter, File Search, Function calling), and knowledge bases. Assistants can maintain context across multiple conversations.
All assistant endpoints require the OpenAI-Beta: assistants=v2 header, which is automatically added by the SDK.
Create assistant Creates an assistant with a model and instructions.
assistant = client. beta . assistants . create ( model: "gpt-4o" , name: "Math Tutor" , instructions: "You are a helpful math tutor. Answer questions clearly and show your work." , tools: [ { type: "code_interpreter" }, { type: "file_search" } ] )
Parameters ID of the model to use. See the model list for available options. Name of the assistant (max 256 characters)
Description of the assistant (max 512 characters)
System instructions for the assistant (max 256,000 characters)
Tools available to the assistant (max 128). Options: { type: "code_interpreter" }
Allows the assistant to write and run Python code Enables searching through uploaded files { type: "function" , function: { name: "get_weather" , description: "Get current weather" , parameters: { type: "object" , properties: { location: { type: "string" } }, required: [ "location" ] } } }
Custom function the assistant can call Resources for tools: tool_resources: { code_interpreter: { file_ids: [ "file-abc123" ] } }
tool_resources: { file_search: { vector_store_ids: [ "vs-abc123" ] } }
Optional metadata (up to 16 key-value pairs)
Sampling temperature (0-2, default: 1)
Nucleus sampling parameter (0-1)
Response format specification:
auto (default){ type: "text" }{ type: "json_object" }{ type: "json_schema", json_schema: {...} } Response Unique assistant identifier
Unix timestamp of creation
Retrieve assistant Retrieves an assistant by ID.
assistant = client. beta . assistants . retrieve ( "asst_abc123" ) puts assistant. name
Parameters ID of the assistant to retrieve
Update assistant Modifies an assistant.
assistant = client. beta . assistants . update ( "asst_abc123" , instructions: "Updated instructions for the assistant" , name: "Updated Math Tutor" )
Parameters ID of the assistant to modify
All creation parameters are available as optional update parameters.
List assistants Returns a list of assistants.
assistants = client. beta . assistants . list ( limit: 20 , order: :desc ) assistants. data . each do | assistant | puts " #{ assistant. name } ( #{ assistant. model } )" end
Parameters Number to return (1-100, default: 20)
Sort order: asc or desc (default)
Cursor for reverse pagination
Delete assistant Deletes an assistant.
client. beta . assistants . delete ( "asst_abc123" )
Parameters ID of the assistant to delete
Examples Math tutor with Code Interpreter # Create assistant assistant = client. beta . assistants . create ( name: "Math Tutor" , instructions: "You are a helpful math tutor. Solve problems step by step." , model: "gpt-4o" , tools: [{ type: "code_interpreter" }] ) # Create thread thread = client. beta . threads . create # Add message client. beta . threads . messages . create ( thread. id , role: "user" , content: "Solve: x^2 + 5x + 6 = 0" ) # Run assistant run = client. beta . threads . runs . create ( thread. id , assistant_id: assistant. id ) # Wait for completion loop do run = client. beta . threads . runs . retrieve (thread. id , run. id ) break if run. status == "completed" sleep 1 end # Get response messages = client. beta . threads . messages . list (thread. id ) puts messages. data . first . content . first . text . value
RAG assistant with File Search # Create vector store with files vector_store = client. vector_stores . create ( name: "Product Docs" , file_ids: [file1. id , file2. id ] ) # Create assistant with file search assistant = client. beta . assistants . create ( name: "Documentation Assistant" , instructions: "Answer questions using the uploaded documentation." , model: "gpt-4o" , tools: [{ type: "file_search" }], tool_resources: { file_search: { vector_store_ids: [vector_store. id ] } } )
Function calling assistant assistant = client. beta . assistants . create ( name: "Weather Assistant" , instructions: "Help users check the weather." , model: "gpt-4o" , tools: [ { type: "function" , function: { name: "get_current_weather" , description: "Get the current weather for a location" , parameters: { type: "object" , properties: { location: { type: "string" , description: "City and state, e.g. San Francisco, CA" }, unit: { type: "string" , enum: [ "celsius" , "fahrenheit" ] } }, required: [ "location" ] } } } ] )