Creating a simple assistant

Written by

Updated at November 27, 2025

Getting started
Create an assistant

Note

We do not recommend using AI Assistant API in new projects. To create AI agents, use the Responses API.

AI Assistant API is a AI Studio tool for creating AI assistants. It can be used to create personalized assistants, implement a retrieval augmented generation (RAG) scenario based on information from external sources, and save the context of requests to the model.

Getting started

To use the examples:

SDK

Create a service account and assign the ai.assistants.editor and ai.languageModels.user roles to it.
Get and save the service account's API key with yc.ai.foundationModels.execute for its scope.

The following examples use API key authentication. Yandex Cloud ML SDK also supports IAM token and OAuth token authentication. For more information, see Authentication in Yandex Cloud ML SDK.

Note

If you are using Windows, we recommend installing the WSL shell first and using it to proceed.
Install Python 3.10 or higher.
Install Python venv to create isolated virtual environments in Python.
Create a new Python virtual environment and activate it:
```
python3 -m venv new-env
source new-env/bin/activate
```
Use the pip package manager to install the ML SDK library:
```
pip install yandex-cloud-ml-sdk
```

Create an assistant

This example shows how to create an assistant to store your conversations with YandexGPT Pro RC.

SDK

Create a file named simple-assistant.py and paste the following code into it:

#!/usr/bin/env python3

from __future__ import annotations
from yandex_cloud_ml_sdk import YCloudML


def main():
    sdk = YCloudML(
        folder_id="<folder_ID>",
        auth="<API_key>",
    )

    # Creating a thread to store the conversation
    # The thread will be stored for five days
    thread = sdk.threads.create(
        name="SimpleAssistant", ttl_days=5, expiration_policy="static"
    )
    print(f"new {thread=}")

    # Specifying YandexGPT Pro RC for model and setting its maximum context length
    model = sdk.models.completions("yandexgpt", model_version="rc")

    # Creating an assistant for the model
    # The assistant will be deleted four days after its last activity
    assistant = sdk.assistants.create(
        model, ttl_days=4, expiration_policy="since_last_active", max_tokens=500
    )

    # Here you should make provision for reading user messages
    # For now, let's just write something to the thread

    input_text = ""

    while input_text != "exit":
        input_text = input("Enter your question to the assistant: ")
        if input_text != "exit":
            thread.write(input_text)

            # This way you can give the whole thread contents to the model
            run = assistant.run(thread)
            print(f"{run=}")

            # To get the result, wait until the run is complete
            result = run.wait()

            # You can view all the result fields
            print(f"run {result=}")

            # The `text` field stores a string which is convenient for later use
            print("Answer:", result.text)

    # You can view all the messages stored in the thread

    print("Outputting the whole message history when exiting the chat:")

    for message in thread:
        print(f"    {message=}")
        print(f"    {message.text=}\n")

    # Deleting everything you no longer need
    thread.delete()
    assistant.delete()


if __name__ == "__main__":
    main()

Where:

<folder_ID>: ID of the folder in which the service account was created.
<API_key>: Service account API key you got earlier required for authentication in the API.

The following examples use API key authentication. Yandex Cloud ML SDK also supports IAM token and OAuth token authentication. For more information, see Authentication in Yandex Cloud ML SDK.

Run the file you created:

python3 simple-assistant.py

The example implements the simplest chat possible: enter your requests to the assistant from your keyboard and get answers. To end the dialog, enter exit.

Approximate result

new thread=Thread(id='fvt67i1ettn5********', expiration_config=ExpirationConfig(ttl_days=5, expiration_policy=<ExpirationPolicy.STATIC: 1>), name='SimpleAssistant', description=None, created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 5, 33, 8133), updated_by='ajegtlf2q28a********', updated_at=datetime.datetime(2024, 12, 15, 21, 5, 33, 8133), expires_at=datetime.datetime(2024, 12, 20, 21, 5, 33, 8133), labels=None)
Enter your question to the assistant: Hi!
run=Run(id='fvtm4n1o2hla********', assistant_id='fvthtngdnlkq********', thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 5, 53, 312504), labels=None, custom_temperature=None, custom_max_tokens=None, custom_max_prompt_tokens=None)
run result=RunResult(status=<RunStatus.COMPLETED: 4>, error=None, _message=Message(id='fvtburadn35c********', parts=('Hello! What can I do for you?',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 5, 53, 728330), labels=None, author=Author(id='fvthtngdnlkq********', role='ASSISTANT')), usage=Usage(input_text_tokens=12, completion_tokens=6, total_tokens=18))
Answer: Hi there! What can I do for you?
Enter your question to the assistant: How much is 2 + 2?
run=Run(id='fvt2eajhkqnb********', assistant_id='fvthtngdnlkq********', thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 7, 36, 751185), labels=None, custom_temperature=None, custom_max_tokens=None, custom_max_prompt_tokens=None)
run result=RunResult(status=<RunStatus.COMPLETED: 4>, error=None, _message=Message(id='fvtnmfeavsm1********', parts=('2 + 2 = 4.',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 7, 37, 294861), labels=None, author=Author(id='fvthtngdnlkq********', role='ASSISTANT')), usage=Usage(input_text_tokens=36, completion_tokens=9, total_tokens=45))
Answer: 2 + 2 = 4.
Enter your question to the assistant: How about 15,234 - 265?
run=Run(id='fvt55e1qr4d0********', assistant_id='fvthtngdnlkq********', thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 7, 59, 483141), labels=None, custom_temperature=None, custom_max_tokens=None, custom_max_prompt_tokens=None)
run result=RunResult(status=<RunStatus.COMPLETED: 4>, error=None, _message=Message(id='fvtujctocrak********', parts=('15234 − 265 = 14969.',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 8, 0, 244274), labels=None, author=Author(id='fvthtngdnlkq********', role='ASSISTANT')), usage=Usage(input_text_tokens=68, completion_tokens=19, total_tokens=87))
Answer: 15,234 − 265 = 14,969.
Enter your question to the assistant: exit
Outputting the whole message history when exiting the chat:
    message=Message(id='fvtujctocrak********', parts=('15234 − 265 = 14969.',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 8, 0, 244274), labels=None, author=Author(id='fvthtngdnlkq********', role='ASSISTANT'))
    message.text='15234 − 265 = 14969.'

    message=Message(id='fvthbaqg1rep********', parts=('And 15234 - 265?',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 7, 59, 375702), labels=None, author=Author(id='fvt82v4kgb7i********', role='USER'))
    message.text='How about 15,234 - 265?'

    message=Message(id='fvtnmfeavsm1********', parts=('2 + 2 = 4.',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 7, 37, 294862), labels=None, author=Author(id='fvthtngdnlkq********', role='ASSISTANT'))
    message.text='2 + 2 = 4.'

    message=Message(id='fvtdd4fbb4n8********', parts=('How much is 2 + 2?',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 7, 36, 625764), labels=None, author=Author(id='fvt82v4kgb7i********', role='USER'))
    message.text='How much is 2 + 2?'

    message=Message(id='fvtburadn35c********', parts=('Hello! What can I do for you?',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 5, 53, 728331), labels=None, author=Author(id='fvthtngdnlkq********', role='ASSISTANT'))
    message.text='Hello! What can I do for you?'

    message=Message(id='fvt9apvs2au9********', parts=('Hi!',), thread_id='fvt67i1ettn5********', created_by='ajegtlf2q28a********', created_at=datetime.datetime(2024, 12, 15, 21, 5, 53, 136965), labels=None, author=Author(id='fvt82v4kgb7i********', role='USER'))
    message.text='Hi!'

Note

When making requests to the assistant, you can get intermediate generation results before the model completes generating the final response.

Creating a simple assistant

Getting started

Create an assistant

See also

Was the article helpful?

Creating a simple assistant

Getting startedGetting started

Create an assistantCreate an assistant

See alsoSee also

Was the article helpful?

Getting started

Create an assistant

See also