Implementation:BerriAI Litellm Assistants API

Property	Value
sources	litellm/assistants/main.py
domains	Assistants, Threads, Messages, Runs, OpenAI, Azure
last_updated	2026-02-15 16:00 GMT

Overview

The Assistants API module provides a unified interface for managing OpenAI-compatible Assistants, including creating assistants, managing threads and messages, and running assistant threads, with support for both OpenAI and Azure providers.

Description

This module implements the OpenAI Assistants API surface through LiteLLM, offering synchronous and asynchronous function pairs for each operation. It supports two LLM providers (OpenAI and Azure) and delegates to provider-specific handler classes (OpenAIAssistantsAPI and AzureAssistantsAPI). Each function resolves API credentials through a priority chain (explicit parameters, LiteLLM globals, environment variables) and includes configurable timeout logic with a default of 600 seconds (10 minutes). Unlike most other LiteLLM API modules, this module does not use the @client decorator pattern, representing an older integration approach.

Usage

Import this module when you need to interact with OpenAI Assistants features (creating assistants, managing threads, posting messages, running threads) through a provider-agnostic interface. It is accessed via the litellm.assistants namespace or through direct imports from litellm.assistants.main.

Code Reference

Source Location

Property	Value
Repository	github.com/BerriAI/litellm
File	litellm/assistants/main.py
Lines	1485
Module	litellm.assistants.main

Signature

Assistants:

def get_assistants(
    custom_llm_provider: Literal["openai", "azure"],
    client: Optional[Any] = None,
    api_key: Optional[str] = None,
    api_base: Optional[str] = None,
    api_version: Optional[str] = None,
    **kwargs,
) -> SyncCursorPage[Assistant]

async def aget_assistants(
    custom_llm_provider: Literal["openai", "azure"],
    client: Optional[AsyncOpenAI] = None,
    **kwargs,
) -> AsyncCursorPage[Assistant]

def create_assistants(
    custom_llm_provider: Literal["openai", "azure"],
    model: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    instructions: Optional[str] = None,
    tools: Optional[List[Dict[str, Any]]] = None,
    tool_resources: Optional[Dict[str, Any]] = None,
    metadata: Optional[Dict[str, str]] = None,
    temperature: Optional[float] = None,
    top_p: Optional[float] = None,
    response_format: Optional[Union[str, Dict[str, str]]] = None,
    client: Optional[Any] = None,
    api_key: Optional[str] = None,
    api_base: Optional[str] = None,
    api_version: Optional[str] = None,
    **kwargs,
) -> Union[Assistant, Coroutine[Any, Any, Assistant]]

def delete_assistant(
    custom_llm_provider: Literal["openai", "azure"],
    assistant_id: str,
    client: Optional[Any] = None,
    api_key: Optional[str] = None,
    api_base: Optional[str] = None,
    api_version: Optional[str] = None,
    **kwargs,
) -> Union[AssistantDeleted, Coroutine[Any, Any, AssistantDeleted]]

Threads:

def create_thread(
    custom_llm_provider: Literal["openai", "azure"],
    messages: Optional[Iterable[OpenAICreateThreadParamsMessage]] = None,
    metadata: Optional[dict] = None,
    tool_resources: Optional[OpenAICreateThreadParamsToolResources] = None,
    client: Optional[OpenAI] = None,
    **kwargs,
) -> Thread

def get_thread(
    custom_llm_provider: Literal["openai", "azure"],
    thread_id: str,
    client=None,
    **kwargs,
) -> Thread

Messages:

def add_message(
    custom_llm_provider: Literal["openai", "azure"],
    thread_id: str,
    role: Literal["user", "assistant"],
    content: str,
    attachments: Optional[List[Attachment]] = None,
    metadata: Optional[dict] = None,
    client=None,
    **kwargs,
) -> OpenAIMessage

def get_messages(
    custom_llm_provider: Literal["openai", "azure"],
    thread_id: str,
    client: Optional[Any] = None,
    **kwargs,
) -> SyncCursorPage[OpenAIMessage]

Runs:

def run_thread(
    custom_llm_provider: Literal["openai", "azure"],
    thread_id: str,
    assistant_id: str,
    additional_instructions: Optional[str] = None,
    instructions: Optional[str] = None,
    metadata: Optional[dict] = None,
    model: Optional[str] = None,
    stream: Optional[bool] = None,
    tools: Optional[Iterable[AssistantToolParam]] = None,
    client: Optional[Any] = None,
    event_handler: Optional[AssistantEventHandler] = None,
    **kwargs,
) -> Run

Import

from litellm.assistants.main import (
    get_assistants, aget_assistants,
    create_assistants, acreate_assistants,
    delete_assistant, adelete_assistant,
    create_thread, acreate_thread,
    get_thread, aget_thread,
    add_message, a_add_message,
    get_messages, aget_messages,
    run_thread, arun_thread,
    run_thread_stream, arun_thread_stream,
)

I/O Contract

Inputs

Parameter	Type	Required	Description
custom_llm_provider	Literal["openai", "azure"]	Yes	The LLM provider to use for the assistants operation
model	str	For create	The model to use for the assistant (e.g., "gpt-4")
assistant_id	str	For delete/run	The ID of the assistant to operate on
thread_id	str	For thread/message/run operations	The ID of the thread to operate on
api_key	Optional[str]	No	API key; falls back to env vars and litellm globals
api_base	Optional[str]	No	API base URL; falls back to env vars and litellm globals
api_version	Optional[str]	No	API version (mainly for Azure)
client	Optional[OpenAI/AsyncOpenAI]	No	Pre-configured OpenAI client instance
**kwargs	dict	No	Additional parameters passed to GenericLiteLLMParams

Outputs

Function	Return Type	Description
get_assistants	SyncCursorPage[Assistant]	Paginated list of assistants
create_assistants	Assistant	The created assistant object
delete_assistant	AssistantDeleted	Deletion confirmation object
create_thread	Thread	The created thread object
get_thread	Thread	The retrieved thread object
add_message	OpenAIMessage	The added message object
get_messages	SyncCursorPage[OpenAIMessage]	Paginated list of messages
run_thread	Run	The run execution result

Usage Examples

from litellm.assistants.main import create_assistants, create_thread, add_message, run_thread

# Create an assistant
assistant = create_assistants(
    custom_llm_provider="openai",
    model="gpt-4",
    name="Math Tutor",
    instructions="You are a helpful math tutor.",
)

# Create a thread
thread = create_thread(custom_llm_provider="openai")

# Add a message to the thread
message = add_message(
    custom_llm_provider="openai",
    thread_id=thread.id,
    role="user",
    content="What is 2 + 2?",
)

# Run the thread
run = run_thread(
    custom_llm_provider="openai",
    thread_id=thread.id,
    assistant_id=assistant.id,
)

# Async example
import asyncio
from litellm.assistants.main import acreate_assistants, acreate_thread, arun_thread

async def main():
    assistant = await acreate_assistants(
        custom_llm_provider="openai",
        model="gpt-4",
        name="Code Helper",
    )
    thread = await acreate_thread(custom_llm_provider="openai")
    run = await arun_thread(
        custom_llm_provider="openai",
        thread_id=thread.id,
        assistant_id=assistant.id,
    )

asyncio.run(main())

Related Pages

• Implementation:BerriAI_Litellm_Responses_API -- The newer Responses API module that provides a similar interface with the @client decorator pattern
• Implementation:BerriAI_Litellm_Passthrough_API -- Passthrough API for direct provider access when the Assistants wrapper is insufficient