diff --git a/README.md b/README.md
index 83eaacc..49a5889 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,122 @@
-# 8-samopisnyy-poiskovyy-agent-na-osnove-deep-agents
+# 8. Самописный поисковый агент на основе deep agents from scratch
 
-Решение: 8. Самописный поисковый агент на основе deep agents from scratch
\ No newline at end of file
+## Описание проекта
+
+В этом проекте реализован **самописный поисковый агент** с использованием библиотеки LangChain и OpenAI LLM.  
+Агент умеет:
+
+1. Принимать запрос от пользователя через консоль.
+2. Искать нужную информацию в интернете (через встроенные инструменты LangChain).
+3. Создавать виртуальные файлы, заполняя их содержимым найденной информации.
+4. Выводить содержимое файлов в красивом формате с помощью `rich`.
+5. Сохранять созданные файлы на диск.
+
+Проект демонстрирует практическое применение **deep agents** – агентов, которые могут использовать внешние инструменты и сохранять промежуточные результаты в виде файлов.
+
+---
+
+## Предварительные требования
+
+| Пакет | Версия |
+|-------|--------|
+| Python | 3.10+ |
+| langchain | ≥0.1.0 |
+| langchain-openai | ≥0.1.0 |
+| questionary | ≥1.10.0 |
+| rich | ≥13.0.0 |
+
+> **Важно**: Для работы с OpenAI понадобится API‑ключ, который можно получить на [openai.com](https://platform.openai.com/).  
+> Установите переменную окружения `OPENAI_API_KEY` перед запуском.
+
+---
+
+## Установка
+
+```bash
+# 1. Клонируйте репозиторий (или скачайте файлы)
+git clone https://github.com/<ваш-аккаунт>/deep-agent-search.git
+cd deep-agent-search
+
+# 2. Создайте виртуальное окружение (рекомендовано)
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# 3. Установите зависимости
+pip install -r requirements.txt
+```
+
+`requirements.txt` содержит:
+
+```text
+langchain>=0.1.0
+langchain-openai>=0.1.0
+questionary>=1.10.0
+rich>=13.0.0
+```
+
+---
+
+## Запуск
+
+```bash
+# Установите переменную окружения с вашим ключом OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# Запустите скрипт
+python solution.py
+```
+
+После запуска вы увидите интерактивный запрос:
+
+```
+Введите ваш поисковый запрос:
+```
+
+Вводите любой вопрос, например: `Какой самый быстрый млекопитающий?`.  
+Агент выполнит поиск, создаст виртуальный файл с ответом и отобразит его содержимое. Далее будет предложено сохранить файлы на диск.
+
+---
+
+## Пример работы
+
+```text
+$ python solution.py
+Введите ваш поисковый запрос: Какой самый быстрый млекопитающий?
+
+[+] Ищу информацию...
+[+] Создаю виртуальный файл "fastest_mammal.txt"...
+
+Содержимое файла:
+----------------------------------------
+Самым быстрым млекопитающим считается гепард (Acinonyx jubatus). Он способен развивать скорость до 120 км/ч на коротких дистанциях.
+----------------------------------------
+
+Хотите сохранить файлы на диск? [y/N]: y
+Файл сохранён: ./fastest_mammal.txt
+```
+
+---
+
+## Как это работает
+
+- **LangChain** управляет агентом и инструментами поиска (например, `SerpAPI`).
+- **ChatOpenAI** отвечает за генерацию текста и интерпретацию запросов.
+- **questionary** обеспечивает интерактивный ввод/вывод в консоли.
+- **rich** форматирует вывод, делая его более читаемым.
+
+---
+
+## Возможные улучшения
+
+- Добавить поддержку нескольких языков.
+- Интегрировать другие источники данных (Wikipedia API, DuckDuckGo и т.д.).
+- Сохранять файлы в формате Markdown или PDF.
+- Реализовать кэширование результатов для ускорения повторных запросов.
+
+---
+
+## Лицензия
+
+MIT License – см. файл `LICENSE`.
+
+---
\ No newline at end of file