Creating an assistant with the WebSearch tool

Written by

Updated at November 26, 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.

The WebSearch tool enables AI assistants to retrieve information from internet sources.

Getting started

To use the examples:

cURL

Get API authentication credentials as described in Authentication with the Yandex AI Studio API.

To use the examples, install the cURL and jq utilities.

Create an assistant

cURL

This example shows how to create an assistant that relies on information from the internet for responses. In this example, we will use the basic algorithm for working with AI Assistant API via the REST API interface: creating an assistant and a thread and submitting a request to the assistant.

As the external information sources, we will use the Central Bank of Russia official website and the Currency rates portal by Yandex. For internet-wide search, leave the options field in WebSearch empty.

Create an AI assistant:

Create a file named assistant.json with the body of the request to create an assistant:

assistant.json
```
{
  "folderId": "<folder_ID>",
  "modelUri": "gpt://<folder_ID>/yandexgpt-lite/latest",
  "instruction": "You are a smart assistant designed for a finance company. Answer politely. Use search to answer the questions. Do not make up your answer.",
  "tools": [
    {
      "genSearch": {
        "options": {
          "site": {
            "site": [
              "https://cbr.ru/",
              "https://yandex.ru/finance/currencies"
            ]
          },
          "enableNrfmDocs": true
        },
        "description": "Tool to get information about official currency exchange rates."
      }
    }
  ]
}
```
Where:
- folderId: ID of the folder for which your account has the roles ai.assistants.editor and ai.languageModels.user or higher.
- modelUri: URI of the text generation model.
- instruction: Basic instruction that the AI assistant will use to run user queries.
- tools: Settings for the tool the assistant will use:
  - site: Array of websites the assistant will access to search for information.
  - enableNrfmDocs: Parameter that determines whether search results will include documents which are not directly accessible from the websites’ home pages.
  - description: Tool description the assistant will use to decide whether to use this tool when generating a response to a specific query.
  To learn more about internet search settings available in WebSearch, see WebSearch.

Send a request to create an AI assistant by specifying the path to the new assistant.json request body file:

export IAM_TOKEN=<IAM_token>
curl \
  --request POST \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --silent \
  --data "@<path_to_request_body>" \
  "https://rest-assistant.api.cloud.yandex.net/assistants/v1/assistants" | \
  jq

Where:

<IAM_token>: IAM token you got before you started.
<path_to_request_body>: Path to the previously created request body file (assistant.json).

Result

{
  "id": "fvthd7m0d6up********",
  "folder_id": "b1gt6g8ht345********",
  "name": "",
  "description": "",
  "created_by": "ajeol2afu1js********",
  "created_at": "2025-08-27T11:07:37.532517Z",
  "updated_by": "ajeol2afu1js********",
  "updated_at": "2025-08-27T11:07:37.532517Z",
  "expiration_config": {
    "expiration_policy": "SINCE_LAST_ACTIVE",
    "ttl_days": "7"
  },
  "expires_at": "2025-09-03T11:07:37.532517Z",
  "labels": {},
  "model_uri": "gpt://b1gt6g8ht345********/yandexgpt-lite/latest",
  "instruction": "You are a smart assistant designed for a finance company. Answer politely. Use search to answer the questions. Do not make up your answer.",
  "prompt_truncation_options": {
    "max_prompt_tokens": null,
    "auto_strategy": {}
  },
  "completion_options": {
    "max_tokens": null,
    "temperature": null
  },
  "tools": [
    {
      "gen_search": {
        "options": {
          "site": {
            "site": [
              "https://cbr.ru/",
              "https://yandex.ru/finance/currencies"
            ]
          },
          "enable_nrfm_docs": true,
          "search_filters": []
        },
        "description": "Tool to get information about official currency exchange rates."
      }
    }
  ],
  "response_format": null
}

In response, AI Assistant API will return your new AI assistant's ID. Save the obtained id. You will need it when accessing the assistant.

Create a thread:

Create a file named thread.json with the body of the request to create a thread and specify the folder ID:

thread.json
```
{
  "folderId": "<folder_ID>"
}
```

Send a request to create a thread by specifying the path to the new thread.json request body file:

curl \
  --request POST \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --silent \
  --data "@<path_to_request_body>" \
  "https://rest-assistant.api.cloud.yandex.net/assistants/v1/threads" | \
  jq

Result

{
  "id": "fvtfq63a134i********",
  "folder_id": "b1gt6g8ht345********",
  "name": "",
  "description": "",
  "default_message_author_id": "fvtsnf3tqbhg********",
  "created_by": "ajeol2afu1js********",
  "created_at": "2025-08-27T11:22:28.999319Z",
  "updated_by": "ajeol2afu1js********",
  "updated_at": "2025-08-27T11:22:28.999319Z",
  "expiration_config": {
    "expiration_policy": "SINCE_LAST_ACTIVE",
    "ttl_days": "7"
  },
  "expires_at": "2025-09-03T11:22:28.999319Z",
  "labels": {},
  "tools": []
}

Save the obtained thread ID (id field value). You will need it later.

Create a message in your thread:

Create a file named message.json with the body of the request to create a message and specify the previously obtained thread ID and request text:

message.json

{
  "threadId": "<thread_ID>",
  "content": {
    "content": [
      {
        "text": {
          "content": "What is today’s official USD rate?"
        }
      }
    ]
  }
}

Send a request to create a message by specifying the path to the new message.json request body file:

curl \
  --request POST \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --silent \
  --data "@<path_to_request_body>" \
  "https://rest-assistant.api.cloud.yandex.net/assistants/v1/messages" | \
  jq

Result:

{
  "id": "fvt6bpm6mbp5********",
  "thread_id": "fvtfq63a134i********",
  "created_by": "ajeol2afu1js********",
  "created_at": "2025-08-27T11:24:46.312977Z",
  "author": {
    "id": "fvtsnf3tqbhg********",
    "role": "USER"
  },
  "labels": {},
  "content": {
    "content": [
      {
        "text": {
          "content": "What is today’s official USD rate?"
        }
      }
    ]
  },
  "status": "COMPLETED",
  "citations": []
}

Run the assistant with the message you created earlier:

Create a file named run.json with the body of the request to run the assistant by specifying the assistant and thread IDs you got earlier:

run.json
```
{
  "assistantId": "<assistant_ID>",
  "threadId": "<thread_ID>"
}
```

Send a request to run the assistant by specifying the path to the new run.json request body file:

curl \
  --request POST \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --silent \
  --data "@<path_to_request_body>" \
  "https://rest-assistant.api.cloud.yandex.net/assistants/v1/runs" | \
  jq

Result:

{
  "id": "fvtar74rehg7********",
  "assistant_id": "fvthd7m0d6up********",
  "thread_id": "fvtfq63a134i********",
  "created_by": "ajeol2afu1js********",
  "created_at": "2025-08-27T11:31:06.486275281Z",
  "labels": {},
  "state": {
    "status": "PENDING"
  },
  "usage": null,
  "custom_prompt_truncation_options": null,
  "custom_completion_options": null,
  "tools": [],
  "custom_response_format": null
}

AI Assistant API has returned the run information: the launch is in PENDING status. Save the run ID (id field value). You will need it in the next step.

Get the result of the run with the assistant's response. To do this, make a request by specifying the run ID you got earlier:

curl \
  --request GET \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --silent \
  "https://rest-assistant.api.cloud.yandex.net/assistants/v1/runs/<execution_ID>" | \
  jq

Result

{
  "id": "fvtar74rehg7********",
  "assistant_id": "fvthd7m0d6up********",
  "thread_id": "fvtfq63a134i********",
  "created_by": "ajeol2afu1js********",
  "created_at": "2025-08-27T11:31:06.486275281Z",
  "labels": {},
  "state": {
    "status": "COMPLETED",
    "completed_message": {
      "id": "fvt24upe31hh********",
      "thread_id": "fvtfq63a134i********",
      "created_by": "ajeol2afu1js********",
      "created_at": "2025-08-27T11:31:08.781561740Z",
      "author": {
        "id": "fvthd7m0d6up********",
        "role": "ASSISTANT"
      },
      "labels": {},
      "content": {
        "content": [
          {
            "text": {
              "content": "Today's official USD to RUB exchange rate is 80.5268 RUB per USD."
            }
          }
        ]
      },
      "status": "COMPLETED",
      "citations": []
    }
  },
  "usage": {
    "prompt_tokens": "390",
    "completion_tokens": "44",
    "total_tokens": "434"
  },
  "custom_prompt_truncation_options": null,
  "custom_completion_options": null,
  "tools": [],
  "custom_response_format": null
}

In the content field, the AI assistant returned the model-generated response based on the data from websites specified in the assistant settings.

Creating an assistant with the WebSearch tool

Getting started

Create an assistant

See also

Was the article helpful?

Creating an assistant with the WebSearch tool

Getting startedGetting started

Create an assistantCreate an assistant

See alsoSee also

Was the article helpful?

Getting started

Create an assistant

See also