Assistants API Migration Reference

Warning

Feature Not Implemented!

This functionality is currently under development and is not available in AvalAI. Do not treat the examples on this page as runnable until AvalAI announces Assistants compatibility.

OpenAI has deprecated the Assistants API as of August 26, 2025, with a sunset date of August 26, 2026. For new AvalAI agentic applications, use the Responses API, function calling, tools, and conversation state instead.

This page is retained as a future compatibility map for existing Assistants-style integrations. In that model, an Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries.

Migration Map to Responses

For runnable AvalAI agent workflows today, map Assistants concepts to Responses primitives instead of waiting on /v1/assistants:

Assistants concept	Responses/AvalAI replacement
Assistant instructions	Top-level instructions on /v1/responses, plus app-side agent configuration when you need reusable personas.
Thread	previous_response_id, manual response.output replay, or a route-supported conversation object when available.
Message	input item with role: "user" or role: "assistant"; preserve typed output items for reasoning/tool flows.
Run	A /v1/responses request, optionally with background: true when the route supports background processing.
Function tool	Responses function tool with a strict schema; return results as function_call_output using the matching call_id.
File search / vector store	Route-supported file_search if available; otherwise build RAG with /v1/embeddings, your own store, and /v1/responses.
Code interpreter / hosted tools	Route-, model-, and account-dependent; use your own sandbox or worker when hosted tools are not exposed.

OpenAI Migration Notes for AvalAI

OpenAI's current migration guide maps Assistants to versioned Prompts, Threads to Conversations, Runs to Responses, and run steps to typed response items. In AvalAI docs, treat hosted prompt and conversation objects as compatibility concepts unless AvalAI announces matching endpoints. The portable migration is:

1. Version the agent profile in your app: keep model, instructions, tool schemas, output schema, and safety policy in source control or your own configuration store.
2. Store conversation state yourself: persist user messages, assistant messages, tool calls, and tool outputs in your database.
3. Call /v1/responses: send the current turn plus relevant compacted history, or use previous_response_id only when the selected route supports stored state.
4. Preserve typed items: do not flatten tool calls, reasoning summaries, file references, or citations into plain text before your application has processed them.
5. Migrate new traffic first: route new conversations to Responses, then backfill old Assistants-style thread data only when the product needs continuity.

This keeps the migration runnable on AvalAI today while leaving room for future hosted Prompt, Conversation, or Assistants compatibility.

Runnable Replacement: Responses Math Tutor

Use this pattern for new AvalAI agent-style apps instead of the planned Assistants endpoint. Keep the reusable persona in instructions, send the current turn in input, and add custom function tools only when your application can execute and authorize them safely.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    instructions=(
        "You are a patient math tutor. Explain the reasoning, "
        "show the final answer, and ask one follow-up practice question."
    ),
    input="A rectangle has area 84 and width 7. What is its length?",
    store=False,
)

print(response.output_text)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.5",
  instructions:
    "You are a patient math tutor. Explain the reasoning, show the final answer, and ask one follow-up practice question.",
  input: "A rectangle has area 84 and width 7. What is its length?",
  store: false,
});

console.log(response.output_text);

Bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are a patient math tutor. Explain the reasoning, show the final answer, and ask one follow-up practice question.",
    "input": "A rectangle has area 84 and width 7. What is its length?",
    "store": false
  }'

If your Assistants design depended on Code Interpreter, run code in your own sandbox or worker and expose only a narrow function tool until the selected AvalAI route explicitly supports hosted code execution.

Endpoint (Not Available Yet)

POST https://api.avalai.ir/v1/assistants

Create an Assistant

Request Body

Parameter	Type	Required	Description
model	string	Yes	ID of the model to use. See Models for available options.
name	string	No	The name of the assistant. The maximum length is 256 characters.
description	string	No	The description of the assistant. The maximum length is 512 characters.
instructions	string	No	The system instructions that the assistant uses. The maximum length is 32768 characters.
tools	array	No	A list of tools enabled on the assistant. There can be a maximum of 128 tools per assistant.
tool_resources	object	No	A set of resources that the assistant has access to when using tools.
metadata	object	No	Set of 16 key-value pairs that can be attached to an object.

Tools Object

Parameter	Type	Required	Description
type	string	Yes	The tool type. OpenAI Assistants v2 commonly uses "code_interpreter", "file_search", or "function"; AvalAI support has not been announced.
function	object	Conditional	Required when type is "function".

Examples

Warning

The following examples document the planned compatibility shape only. For runnable agent workflows today, use /v1/responses with custom function tools or route-supported hosted tools.

Creating an Assistant

Bash

curl https://api.avalai.ir/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
  "model": "gpt-5.5",
  "name": "Math Tutor",
  "instructions": "You are a personal math tutor. Write and run code to answer math questions.",
  "tools": [{"type": "code_interpreter"}]
}'

Python

from openai import OpenAI

client = OpenAI(
    api_key="your-avalai-api-key",  # Replace with your actual API key
    base_url="https://api.avalai.ir/v1",  # AvalAI API endpoint
)

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-5.5",
)

print(assistant.id)

JavaScript

import { OpenAI } from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const assistant = await 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-5.5",
});

console.log(assistant.id);

Go

// Go Example: Creating an Assistant via AvalAI
package main

import (
	"context"
	"fmt"
	"os"

	openai "github.com/openai/openai-go"
)

func main() {
	apiKey := os.Getenv("AVALAI_API_KEY") // Or replace with your key
	if apiKey == "" {
		fmt.Println("Error: AVALAI_API_KEY environment variable not set.")
		return
	}
	baseURL := "https://api.avalai.ir/v1" // Use AvalAI base URL

	config := openai.DefaultConfig(apiKey)
	config.BaseURL = baseURL
	client := openai.NewClientWithConfig(config)

	req := openai.AssistantRequest{
		Model:        "gpt-5.5",
		Name:         openai.NewString("Math Tutor"),
		Instructions: openai.NewString("You are a personal math tutor. Write and run code to answer math questions."),
		Tools: []openai.AssistantTool{
			{Type: openai.AssistantToolTypeCodeInterpreter},
		},
		// Description: openai.NewString("Optional description"),
		// Metadata: map[string]interface{}{"user_id": "123"}, // Optional
	}

	resp, err := client.CreateAssistant(context.Background(), req)
	if err != nil {
		fmt.Printf("Assistant creation error: %v\n", err)
		return
	}

	fmt.Printf("Assistant created with ID: %s\n", resp.ID)
}

PHP

<?php
// PHP Example: Creating an Assistant via AvalAI

$apiKey = getenv('AVALAI_API_KEY'); // Or replace with your key directly
$apiUrl = 'https://api.avalai.ir/v1/assistants'; // Use AvalAI base URL

$data = [
'model' => 'gpt-5.5',
'name' => 'Math Tutor',
'instructions' => 'You are a personal math tutor. Write and run code to answer math questions.',
'tools' => [['type' => 'code_interpreter']],
// 'description' => 'Optional description', // Optional
// 'metadata' => ['user_id' => '123'] // Optional
];

$jsonData = json_encode($data);

$ch = curl_init($apiUrl);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey,
'OpenAI-Beta: assistants=v2', // Required header for Assistants API v2
'Content-Length: ' . strlen($jsonData)
]);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$err = curl_error($ch);

curl_close($ch);

if ($err) {
  echo "cURL Error #:" . $err;
} elseif ($httpcode >= 400) {
  echo "HTTP Error: " . $httpcode . "\n";
  echo "Response: " . $response;
} else {
  echo "Assistant creation response:\n";
  echo $response;
  // $responseData = json_decode($response, true);
  // if (isset($responseData['id'])) {
    // echo "Assistant created with ID: " . $responseData['id'] . "\n";
    // } else {
      // print_r($responseData);
      // }
    }
    ?>

Response Format

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-5.5",
  "instructions": "You are a personal math tutor. Write and run code to answer math questions.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "file_ids": [],
  "metadata": {}
}

Response Parameters

Parameter	Type	Description
id	string	The identifier for the assistant.
object	string	The object type, which is always "assistant".
created_at	integer	The Unix timestamp (in seconds) of when the assistant was created.
name	string or null	The name of the assistant.
description	string or null	The description of the assistant.
model	string	The model that the assistant uses.
instructions	string	The system instructions that the assistant uses.
tools	array	A list of tools enabled on the assistant.
file_ids	array	A list of file IDs attached to this assistant.
metadata	object	Set of key-value pairs attached to the assistant.

Threads

Threads represent conversations between users and assistants.

Create a Thread

POST https://api.avalai.ir/v1/threads

Request Body

Parameter	Type	Required	Description
messages	array	No	A list of messages to start the thread with.
metadata	object	No	Set of key-value pairs that can be attached to the thread.

Add a Message to a Thread

POST https://api.avalai.ir/v1/threads/{thread_id}/messages

Request Body

Parameter	Type	Required	Description
role	string	Yes	The role of the entity that is creating the message. Currently only "user" is supported.
content	string	Yes	The content of the message.
file_ids	array	No	A list of File IDs that the message should use.
metadata	object	No	Set of key-value pairs that can be attached to the message.

Run an Assistant on a Thread

POST https://api.avalai.ir/v1/threads/{thread_id}/runs

Request Body

Parameter	Type	Required	Description
assistant_id	string	Yes	The ID of the assistant to use for this run.
instructions	string	No	Override the assistant's instructions for this run.
tools	array	No	Override the assistant's tools for this run.
metadata	object	No	Set of key-value pairs that can be attached to the run.

Error Handling

The API may return various error codes:

Status Code	Description
400	Bad Request - Your request is invalid.
401	Unauthorized - Your API key is wrong.
403	Forbidden - You don't have permission to access this resource.
404	Not Found - The specified resource could not be found.
429	Too Many Requests - You have exceeded your rate limit.
500	Internal Server Error - We had a problem with our server.

For more information on handling errors, see the Error Handling guide.

Related Resources

• Models - Learn about available models
• Authentication - Learn about authentication methods
• Rate Limits - Learn about API rate limits