Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Managing conversation context

Written by
Updated at February 18, 2026

When using the Responses API in Yandex Cloud AI Studio, there are three ways to provide context in a multi-step conversation with an agent:

  • Conversations API: This option involves saving the conversation into an object with a unique ID.
  • Chaining responses: This option implements real-time chat by chaning responses together with the previous_response_id parameter.
  • Manual context management: This option allows you to edit the conversation history provided to the agent.

Getting started

To use the examples:

  1. Create a service account and assign the ai.assistants.editor and ai.languageModels.user roles to it.

  2. Get and save the service account's API key with yc.ai.foundationModels.execute for its scope.

    Note

    If you are using Windows, we recommend installing the WSL shell first and using it to proceed.

  3. Install Python 3.10 or higher.

  4. Install Python venv to create isolated virtual environments in Python.

  5. Create a new Python virtual environment and activate it:

    python3 -m venv new-env
source new-env/bin/activate

  6. Install the OpenAI library for Python:

    pip install openai

Managing context with the Conversations API

You can use the Conversations API to create the conversation object, which is provided to subsequent requests to preserve the state and share the context across responses. The conversation is stored as a long-lived object with a unique ID.

  1. Create a file named dialogue.py and add the following code to it:

    import openai

YC_MODEL = "yandexgpt"

def print_conversation(conv_id):
    print(f"\nConversation {conv_id}")
    items = client.conversations.items.list(conversation_id=conv_id)
    print(f"\nFound {len(items.data)} items in conversation:")
    
    for item in items.data:
        print(f"\nItem: {item}")
    print("-" * 80)


client = openai.OpenAI(
    api_key=YC_API_KEY,
    base_url="https://ai.api.cloud.yandex.net/v1",
    project=YC_FOLDER_ID
)

# 1) Creating a conversation.
conv = client.conversations.create()
print("conversation id:", conv.id)
print_conversation(conv.id)

# 2) First message with a system instruction and user input.
r1 = client.responses.create(
    model=f"gpt://{YC_FOLDER_ID}/{YC_MODEL}",
    conversation=conv.id,
    input=[
        {"role": "developer", "content": "You are my assistant."},
        {"role": "user", "content": "Hi! Remember: I live in Serpukhov."}
    ]
)
print("assistant:", r1.output_text)
print_conversation(conv.id)


# 3) Proceeding in the same conversation.
r2 = client.responses.create(
    model=f"gpt://{YC_FOLDER_ID}/{YC_MODEL}",
    conversation=conv.id,
    input="What city do I live in?"
)
print("assistant:", r2.output_text)
print_conversation(conv.id)


# 4) Calling web_search.
r3 = client.responses.create(
    model=f"gpt://{YC_FOLDER_ID}/{YC_MODEL}",
    conversation=conv.id,
    input="What will the weather be like this weekend?",
    tools=[{
        "type": "web_search",
    }]
)
print("assistant:", r3.output_text)
print_conversation(conv.id)

  2. Save authentication data into environment variables:

    export YC_FOLDER_ID=<folder_ID>
export YC_API_KEY=<API_key>

  3. Run the file you created:

    python dialogue.py
    Response fragment
    assistant: The weather forecast for Serpukhov this weekend is as follows:

- **Saturday, January 31**:
  - Night: -9°C, feels like -15°C
  - Morning: -10°C, feels like -17°C
  - Day: -5°C, feels like -10°C
  - Evening: -7°C, feels like -13°C

- **Sunday, February 1**:
  - Night: -21°C, feels like -27°C
  - Morning: -21°C, feels like -27°C
  - Day: -19°C, feels like -25°C
  - Evening: -20°C, feels like -26°C

Note

Currently, you cannot edit elements or reset a conversation. To start a new conversation, create a new conversation object.

Managing context by chaining responses

The previous_response_id parameter allows you to chain responses together and start a conversation from a certain point.

  1. Create a file named dialogue.py and add the following code to it:

    import openai     

YC_MODEL = "yandexgpt"

previous_id = None  # parameter for saving the ID of the assistant's last response

client = openai.OpenAI(
    api_key=YC_API_KEY,
    project=YC_FOLDER_ID,
    base_url="https://ai.api.cloud.yandex.net/v1",
)

print("Chat with agent (to exit, type 'exit')\n")

while True:
    user_input = input("You: ")
    if user_input.lower() in ("exit", "quit"):
        print("Chat session ended.")
        break

    response = client.responses.create(
        model=f"gpt://{YC_FOLDER_ID}/{YC_MODEL}",
        input=user_input,
        instructions="You are a text agent that engages in a conversation with the user and provides meaningful responses to their questions.",
        previous_response_id=previous_id  # providing context, if any
    )

    # saving the ID for the next step
    previous_id = response.id

    # outputting the agent's response
    print("Agent:", response.output_text)

  2. Save authentication data to environment variables:

    export YC_FOLDER_ID=<folder_ID>
export YC_API_KEY=<API_key>

  3. Run the file you created:

    python dialogue.py

    This opens a chat where you can talk to the agent in real time while maintaining context.

    Conversation example
    Chat with agent (to exit, type 'exit')

You: Hi! Remember: my cat's name is Muffin, she’ll be one year old this month.
Agent: Hi! Okay, I've got it: your cat's name is Muffin, and she'll be one year old this month. If you have any other questions or need help, let me know!
You: How old is Muffin?
Agent: Muffin will turn one year old this month.

Manually managing conversation state

For maximum control over the conversation state, you can store the history in the application and explicitly provide the required messages as input with each Responses API request. This is especially useful when you need to flexibly clean up or compress context or edit the history you provide.

  1. Create a file named dialogue.py and add the following code to it:

    import openai     

YC_MODEL = "yandexgpt"

client = openai.OpenAI(
    api_key=YC_API_KEY,
    base_url="https://ai.api.cloud.yandex.net/v1",
    project=YC_FOLDER_ID,
)

response = client.responses.create(
    model=f"gpt://{YC_FOLDER_ID}/{YC_MODEL}",
    input=[
        {"role": "user", "content": "Hi! Help me choose a gift for myself."},
        {"role": "assistant", "content": "Hi! Tell me about yourself"},
        {"role": "user", "content": "My name is George."},
        {"role": "user", "content": "I love to travel."},
        {"role": "user", "content": "I'm into anime and design."},
    ],
)

print(response.output_text)

  2. Save authentication data into environment variables:

    export YC_FOLDER_ID=<folder_ID>
export YC_API_KEY=<API_key>

  3. Run the file you created:

    python dialogue.py
    Response example:
    Here are some gift ideas you might like:

1. **Travel accessories.** For example, a high-quality backpack or carry-on bag, a compact hygiene kit, or a universal adapter for different power outlets.

2. **Books on design.** You can choose both classic design theory texts and contemporary books with examples and advice from leading designers.

3. **Anime figures and merchandise.** If you're a fan of a particular anime, look for figurines, posters, clothing, and various other items featuring symbols from your favorite show.

4. **Graphics tablet.** If you're interested in design and want to develop your skills, a graphics tablet can be a useful tool for drawing and creating digital illustrations.

5. **Camera or accessories for it.** If you enjoy taking photos while traveling, you might consider getting a camera, extra lens, or other helpful photography gear.

6. **Courses.** Whether it's design, photography, animation, or something else entirely, courses are a great way to boost skills and learn something new.

7. **Subscribtion to anime streaming services.** Enjoy your favorite anime shows in high quality and ad-free.

I hope this helps you find a gift you’ll enjoy!
Previous
Creating a voice agent via Realtime API
Next
Creating a text agent with web search