Creating a text agent with search based on pre-created chunks

Written by

Updated at December 23, 2025

Getting started
Fragment the information
Upload the file to Vector Store
Create a Vector Store search index
Create an AI agent with index search

With Vector Store, you can upload into the search index not only whole files but also pre-created data chunks in JSONL format. This gives you full control over the data structure and improves the search and generative response accuracy by avoiding potential loss of meaning due to automatic fragmentation of documents.

Getting started

To use an example:

Python

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 as the specified scope.

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
```
Install the OpenAI library for Python:
```
pip install openai
```

Fragment the information

Split the information you want to upload into the search index into fragments. Save the resulting fragments in JSON Lines format as "body":"<fragment_content>" pairs. Here is an example:

{ "body": "How to recover a password? Go to the password recovery page and enter your email." }
{ "body": "Can I work offline? Yes, the application supports offline mode." }

Save the resulting text fragments to a file named chunks.jsonl.

Upload the file to Vector Store

Before you create a search index, upload the resulting file in JSON Lines format to Vector Store:

Python

Create a file named upload.py and paste the following code into it:

import pathlib
import openai
from openai import OpenAI

YANDEX_API_KEY = "<API_key>"
YANDEX_FOLDER_ID = "<folder_ID>"
filename = "chunks.jsonl"


# Local file for indexing
def local_path(path: str) -> pathlib.Path:
    return pathlib.Path(__file__).parent / path


def main():
    client = OpenAI(
        api_key=YANDEX_API_KEY,
        base_url="https://rest-assistant.api.cloud.yandex.net/v1",
        project=YANDEX_FOLDER_ID,
    )

    print("Uploading the file...")

    with open(local_path(filename), "rb") as file:
        f = client.files.create(
            file=(filename, file, "application/jsonlines"),
            purpose="assistants",
            expires_after=openai.types.file_create_params.ExpiresAfter(
                anchor="created_at", seconds=3600
            ),
            extra_body={"format": "chunks"},
        )

    print(f"{filename} uploaded:", f.id)


if __name__ == "__main__":
    main()

Where:

YANDEX_API_KEY: Service account API key you got before you started.
YANDEX_FOLDER_ID: ID of the folder for operations with the Vector Store API.

Run the file you created:
```
python3 upload.py
```
Result:
```
Uploading the file...
File chunks.jsonl uploaded: fvtnmsqdn2pq********
```
Save the uploaded file's ID. You will need it later to create a search index.

Create a Vector Store search index

Create a search index from the file uploaded in the previous step:

Python

Create a file named index.py and paste the following code into it:

import time
from openai import OpenAI

YANDEX_API_KEY = "<API_key>"
YANDEX_FOLDER_ID = "<folder_ID>"
input_file_ids = ["<file_ID>"]


def main():
    client = OpenAI(
        api_key=YANDEX_API_KEY,
        base_url="https://rest-assistant.api.cloud.yandex.net/v1",
        project=YANDEX_FOLDER_ID,
    )

    # Creating a search index with several files
    print("Creating a search index...")
    vector_store = client.vector_stores.create(
        # Descriptive index name
        name="Support knowledge base",
        # Your file labels
        metadata={"key": "value"},
        # Index lifetime
        # last_active_at: since last active
        expires_after={"anchor": "last_active_at", "days": 1},
        # or created_at: since created
        # expires_after={"anchor": "created_at", "days": 1},
        file_ids=input_file_ids,  # <- list of files
    )
    vector_store_id = vector_store.id
    print("Vector store created:", vector_store_id)

    # Waiting for the search index to get ready
    while True:
        vector_store = client.vector_stores.retrieve(vector_store_id)
        print("Vector store status:", vector_store.status)
        if vector_store.status == "completed":
            break
        time.sleep(2)

    print("Vector store is ready for use.")


if __name__ == "__main__":
    main()

Where input_file_ids is a list of IDs of uploaded source files. In our example, a single source file ID you got in the previous step will be added to the array.

Run the file you created:

python3 index.py

Result:

Creating a search index...
Vector store created: fvtol0geat8g********
Vector store status: in_progress
Vector store status: in_progress
Vector store status: in_progress
Vector store status: in_progress
Vector store status: in_progress
Vector store status: completed
Vector store is ready for use.

Save the index ID. You will need it later to execute a search query.

Create an AI agent with index search

For the agent to be able to use the index you created, provide index ID in the client.responses.create() method's tools parameter:

Python

Create a file named query.py and paste the following code into it:

import openai
import json

YANDEX_API_KEY = "<API_key>"
YANDEX_FOLDER_ID = "<folder_ID>"
VECTOR_STORE_ID = "<search_index_ID>"
QUERY_TEXT = "How to recover a password?"
YANDEX_CLOUD_MODEL = "yandexgpt"


client = openai.OpenAI(
    api_key=YANDEX_API_KEY,
    base_url="https://rest-assistant.api.cloud.yandex.net/v1",
    project=YANDEX_FOLDER_ID,
)

response = client.responses.create(
    model=f"gpt://{YANDEX_FOLDER_ID}/{YANDEX_CLOUD_MODEL}",
    instructions="You are a smart assistant. If asked about how to use the app, search in the connected index",
    tools=[{"type": "file_search", "vector_store_ids": [VECTOR_STORE_ID]}],
    input=QUERY_TEXT,
)

# Response for the user
print("Response text:")
print(response.output_text)
print("\n" + "=" * 50 + "\n")

# Full response
print("Full response (JSON):")
print(json.dumps(response.model_dump(), indent=2, ensure_ascii=False))

Where VECTOR_STORE_ID is the Vector Store search index ID you got in the previous step.

Run the file you created:

python3 query.py

Result:

Response text:
Go to the password recovery page and enter your email.

Example of a full response

Full response (JSON):
{
  "id": "d70f114f-77c3-427b-b3cd-b70c********",
  "created_at": 1764746460.0,
  "error": null,
  "incomplete_details": null,
  "instructions": "You are a smart assistant. If asked about how to use the app, search in the connected index",
  "metadata": null,
  "model": "gpt://b1gt6g8ht345********/yandexgpt",
  "object": "response",
  "output": [
    {
      "id": "f170da63-5f61-4f9b-a4ba-49d4********",
      "queries": [
        "How to recover a password?"
      ],
      "status": "completed",
      "type": "file_search_call",
      "results": [
        {
          "attributes": {},
          "file_id": "fvtq3f79gjc7********",
          "filename": "chunks.jsonl",
          "score": 0.9034204,
          "text": "How to recover a password? Go to the password recovery page and enter your email.",
          "valid": true
        },
        {
          "attributes": {},
          "file_id": "fvtq3f79gjc7********",
          "filename": "chunks.jsonl",
          "score": 0.29538444,
          "text": "Can I work offline? Yes, the application supports offline mode.",
          "valid": true
        }
      ],
      "valid": true
    },
    {
      "id": "40d3b1e3-ffe6-4c8f-b332-ed71********",
      "content": [
        {
          "annotations": [
            {
              "file_id": "fvtq3f79gjc7********",
              "filename": "chunks.jsonl",
              "index": 0,
              "type": "file_citation",
              "valid": true
            },
            {
              "file_id": "fvtq3f79gjc7********",
              "filename": "chunks.jsonl",
              "index": 0,
              "type": "file_citation",
              "valid": true
            }
          ],
          "text": "Go to the password recovery page and enter your email.",
          "type": "output_text",
          "logprobs": null,
          "valid": true
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message",
      "valid": true
    }
  ],
  "parallel_tool_calls": true,
  "temperature": null,
  "tool_choice": "auto",
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": [
        "fvtneupef1s8********"
      ],
      "filters": null,
      "max_num_results": null,
      "ranking_options": null,
      "valid": true
    }
  ],
  "top_p": null,
  "background": false,
  "conversation": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "previous_response_id": null,
  "prompt": null,
  "prompt_cache_key": null,
  "prompt_cache_retention": null,
  "reasoning": null,
  "safety_identifier": null,
  "service_tier": null,
  "status": "completed",
  "text": null,
  "top_logprobs": null,
  "truncation": null,
  "usage": {
    "input_tokens": 232,
    "input_tokens_details": {
      "cached_tokens": 0,
      "valid": true
    },
    "output_tokens": 8,
    "output_tokens_details": {
      "reasoning_tokens": 0,
      "valid": true
    },
    "total_tokens": 240,
    "valid": true
  },
  "user": "",
  "valid": true
}

Creating a text agent with search based on pre-created chunks

Getting started

Fragment the information

Upload the file to Vector Store

Create a Vector Store search index

Create an AI agent with index search

See also

Was the article helpful?

Creating a text agent with search based on pre-created chunks

Getting startedGetting started

Fragment the informationFragment the information

Upload the file to Vector StoreUpload the file to Vector Store

Create a Vector Store search indexCreate a Vector Store search index

Create an AI agent with index searchCreate an AI agent with index search

See alsoSee also

Was the article helpful?

Getting started

Fragment the information

Upload the file to Vector Store

Create a Vector Store search index

Create an AI agent with index search

See also