Skip to content

assistants

The assistants module offers functionalities to create, retrieve, update, list, and delete Assistants. Assistants are AI models configured to perform specific tasks based on instructions, files, and other parameters.

Classes:

Name Description
Assistants
AssistantsWithRawResponse
AssistantsWithStreamingResponse
AsyncAssistants
AsyncAssistantsWithRawResponse
AsyncAssistantsWithStreamingResponse

Assistants 

Assistants(client: OpenAI)

Methods:

Name Description
create

Create an assistant with a model and instructions.
delete

Delete an assistant.
files
list

Returns a list of assistants.
retrieve

Retrieves an assistant.
update

Modifies an assistant.
with_raw_response
with_streaming_response

create 

create(
    *,
    model: str,
    description: Optional[str] | NotGiven = NOT_GIVEN,
    file_ids: List[str] | NotGiven = NOT_GIVEN,
    instructions: Optional[str] | NotGiven = NOT_GIVEN,
    metadata: Optional[object] | NotGiven = NOT_GIVEN,
    name: Optional[str] | NotGiven = NOT_GIVEN,
    tools: (
        Iterable[AssistantToolParam] | NotGiven
    ) = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> Assistant

Create an assistant with a model and instructions.

Parameters:

Name Type Description Default
model str

ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.

 required
description Optional[str] | NotGiven

The description of the assistant. The maximum length is 512 characters.

 NOT_GIVEN
file_ids List[str] | NotGiven

A list of file IDs attached to this assistant. There can be a maximum of 20 files attached to the assistant. Files are ordered by their creation date in ascending order.

 NOT_GIVEN
instructions Optional[str] | NotGiven

The system instructions that the assistant uses. The maximum length is 32768 characters.

 NOT_GIVEN
metadata Optional[object] | NotGiven

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

 NOT_GIVEN
name Optional[str] | NotGiven

The name of the assistant. The maximum length is 256 characters.

 NOT_GIVEN
tools Iterable[AssistantToolParam] | NotGiven

A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter, retrieval, or function.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

delete 

delete(
    assistant_id: str,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> AssistantDeleted

Delete an assistant.

Parameters:

Name Type Description Default
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

files 

files() -> Files

list 

list(
    *,
    after: str | NotGiven = NOT_GIVEN,
    before: str | NotGiven = NOT_GIVEN,
    limit: int | NotGiven = NOT_GIVEN,
    order: Literal["asc", "desc"] | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> SyncCursorPage[Assistant]

Returns a list of assistants.

Parameters:

Name Type Description Default
after str | NotGiven

A cursor for use in pagination.

 NOT_GIVEN

after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

before: A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

extra_headers: Send extra headers

extra_query: Add additional query parameters to the request

extra_body: Add additional JSON properties to the request

timeout: Override the client-level default timeout for this request, in seconds

retrieve 

retrieve(
    assistant_id: str,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> Assistant

Retrieves an assistant.

Parameters:

Name Type Description Default
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

update 

update(
    assistant_id: str,
    *,
    description: Optional[str] | NotGiven = NOT_GIVEN,
    file_ids: List[str] | NotGiven = NOT_GIVEN,
    instructions: Optional[str] | NotGiven = NOT_GIVEN,
    metadata: Optional[object] | NotGiven = NOT_GIVEN,
    model: str | NotGiven = NOT_GIVEN,
    name: Optional[str] | NotGiven = NOT_GIVEN,
    tools: (
        Iterable[AssistantToolParam] | NotGiven
    ) = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> Assistant

Modifies an assistant.

Parameters:

Name Type Description Default
description Optional[str] | NotGiven

The description of the assistant.

 NOT_GIVEN

The maximum length is 512 characters.

file_ids: A list of File IDs attached to this assistant. There can be a maximum of 20 files attached to the assistant. Files are ordered by their creation date in ascending order. If a file was previously attached to the list but does not show up in the list, it will be deleted from the assistant.

instructions: The system instructions that the assistant uses. The maximum length is 32768 characters.

metadata: Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

model: ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.

name: The name of the assistant. The maximum length is 256 characters.

tools: A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter, retrieval, or function.

extra_headers: Send extra headers

extra_query: Add additional query parameters to the request

extra_body: Add additional JSON properties to the request

timeout: Override the client-level default timeout for this request, in seconds

with_raw_response 

with_raw_response() -> AssistantsWithRawResponse

with_streaming_response 

with_streaming_response() -> (
    AssistantsWithStreamingResponse
)

AssistantsWithRawResponse 

AssistantsWithRawResponse(assistants: Assistants)

Methods:

Name Description
files

Attributes:

Name Type Description
create
delete
list
retrieve
update

create instance-attribute 

create = to_raw_response_wrapper(create)

delete instance-attribute 

delete = to_raw_response_wrapper(delete)

list instance-attribute 

list = to_raw_response_wrapper(list)

retrieve instance-attribute 

retrieve = to_raw_response_wrapper(retrieve)

update instance-attribute 

update = to_raw_response_wrapper(update)

files 

files() -> FilesWithRawResponse

AssistantsWithStreamingResponse 

AssistantsWithStreamingResponse(assistants: Assistants)

Methods:

Name Description
files

Attributes:

Name Type Description
create
delete
list
retrieve
update

create instance-attribute 

create = to_streamed_response_wrapper(create)

delete instance-attribute 

delete = to_streamed_response_wrapper(delete)

list instance-attribute 

list = to_streamed_response_wrapper(list)

retrieve instance-attribute 

retrieve = to_streamed_response_wrapper(retrieve)

update instance-attribute 

update = to_streamed_response_wrapper(update)

files 

files() -> FilesWithStreamingResponse

AsyncAssistants 

AsyncAssistants(client: AsyncOpenAI)

Methods:

Name Description
create

Create an assistant with a model and instructions.
delete

Delete an assistant.
files
list

Returns a list of assistants.
retrieve

Retrieves an assistant.
update

Modifies an assistant.
with_raw_response
with_streaming_response

create async 

create(
    *,
    model: str,
    description: Optional[str] | NotGiven = NOT_GIVEN,
    file_ids: List[str] | NotGiven = NOT_GIVEN,
    instructions: Optional[str] | NotGiven = NOT_GIVEN,
    metadata: Optional[object] | NotGiven = NOT_GIVEN,
    name: Optional[str] | NotGiven = NOT_GIVEN,
    tools: (
        Iterable[AssistantToolParam] | NotGiven
    ) = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> Assistant

Create an assistant with a model and instructions.

Parameters:

Name Type Description Default
model str

ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.

 required
description Optional[str] | NotGiven

The description of the assistant. The maximum length is 512 characters.

 NOT_GIVEN
file_ids List[str] | NotGiven

A list of file IDs attached to this assistant. There can be a maximum of 20 files attached to the assistant. Files are ordered by their creation date in ascending order.

 NOT_GIVEN
instructions Optional[str] | NotGiven

The system instructions that the assistant uses. The maximum length is 32768 characters.

 NOT_GIVEN
metadata Optional[object] | NotGiven

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

 NOT_GIVEN
name Optional[str] | NotGiven

The name of the assistant. The maximum length is 256 characters.

 NOT_GIVEN
tools Iterable[AssistantToolParam] | NotGiven

A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter, retrieval, or function.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

delete async 

delete(
    assistant_id: str,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> AssistantDeleted

Delete an assistant.

Parameters:

Name Type Description Default
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

files 

files() -> AsyncFiles

list 

list(
    *,
    after: str | NotGiven = NOT_GIVEN,
    before: str | NotGiven = NOT_GIVEN,
    limit: int | NotGiven = NOT_GIVEN,
    order: Literal["asc", "desc"] | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> AsyncPaginator[Assistant, AsyncCursorPage[Assistant]]

Returns a list of assistants.

Parameters:

Name Type Description Default
after str | NotGiven

A cursor for use in pagination.

 NOT_GIVEN

after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

before: A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

order: Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

extra_headers: Send extra headers

extra_query: Add additional query parameters to the request

extra_body: Add additional JSON properties to the request

timeout: Override the client-level default timeout for this request, in seconds

retrieve async 

retrieve(
    assistant_id: str,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> Assistant

Retrieves an assistant.

Parameters:

Name Type Description Default
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

update async 

update(
    assistant_id: str,
    *,
    description: Optional[str] | NotGiven = NOT_GIVEN,
    file_ids: List[str] | NotGiven = NOT_GIVEN,
    instructions: Optional[str] | NotGiven = NOT_GIVEN,
    metadata: Optional[object] | NotGiven = NOT_GIVEN,
    model: str | NotGiven = NOT_GIVEN,
    name: Optional[str] | NotGiven = NOT_GIVEN,
    tools: (
        Iterable[AssistantToolParam] | NotGiven
    ) = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> Assistant

Modifies an assistant.

Parameters:

Name Type Description Default
description Optional[str] | NotGiven

The description of the assistant.

 NOT_GIVEN

The maximum length is 512 characters.

file_ids: A list of File IDs attached to this assistant. There can be a maximum of 20 files attached to the assistant. Files are ordered by their creation date in ascending order. If a file was previously attached to the list but does not show up in the list, it will be deleted from the assistant.

instructions: The system instructions that the assistant uses. The maximum length is 32768 characters.

metadata: Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

model: ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.

name: The name of the assistant. The maximum length is 256 characters.

tools: A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter, retrieval, or function.

extra_headers: Send extra headers

extra_query: Add additional query parameters to the request

extra_body: Add additional JSON properties to the request

timeout: Override the client-level default timeout for this request, in seconds

with_raw_response 

with_raw_response() -> AsyncAssistantsWithRawResponse

with_streaming_response 

with_streaming_response() -> (
    AsyncAssistantsWithStreamingResponse
)

AsyncAssistantsWithRawResponse 

AsyncAssistantsWithRawResponse(assistants: AsyncAssistants)

Methods:

Name Description
files

Attributes:

Name Type Description
create
delete
list
retrieve
update

create instance-attribute 

create = async_to_raw_response_wrapper(create)

delete instance-attribute 

delete = async_to_raw_response_wrapper(delete)

list instance-attribute 

list = async_to_raw_response_wrapper(list)

retrieve instance-attribute 

retrieve = async_to_raw_response_wrapper(retrieve)

update instance-attribute 

update = async_to_raw_response_wrapper(update)

files 

files() -> AsyncFilesWithRawResponse

AsyncAssistantsWithStreamingResponse 

AsyncAssistantsWithStreamingResponse(
    assistants: AsyncAssistants,
)

Methods:

Name Description
files

Attributes:

Name Type Description
create
delete
list
retrieve
update

create instance-attribute 

create = async_to_streamed_response_wrapper(create)

delete instance-attribute 

delete = async_to_streamed_response_wrapper(delete)

list instance-attribute 

list = async_to_streamed_response_wrapper(list)

retrieve instance-attribute 

retrieve = async_to_streamed_response_wrapper(retrieve)

update instance-attribute 

update = async_to_streamed_response_wrapper(update)

files 

files() -> AsyncFilesWithStreamingResponse