docs: comprehensive README

README.md

@@ -1,53 +1,70 @@
-# Deep Agent with Web Search and Virtual File Creation
+# Deep Agent — поисковый агент с виртуальной ФС
 
-## Overview
-This repository contains a minimal implementation of a **Deep Agent** built from scratch using the `deepagents` framework. The agent can:
+Реализация **Deep Agent** на основе фреймворка `deepagents` (deep agents from scratch).
 
-1. **Search the web** for information using DuckDuckGo.
-2. **Create virtual files** during its execution.
-3. **Export** those virtual files to the real filesystem after the agent finishes.
+## Что умеет агент
 
-The implementation follows the guidelines from the *Deep Agents from Scratch* course and uses the BroJS LLM endpoint.
+| Возможность | Инструмент |
+|-------------|------------|
+| Поиск в интернете | `web_search` (DuckDuckGo, без API-ключа) |
+| Создание файлов в виртуальной ФС | `write_file` |
+| Чтение и редактирование файлов | `read_file`, `edit_file` |
+| Выгрузка виртуальных файлов в реальную ФС | `export_virtual_files` |
 
-## Prerequisites
-- Python 3.10 or newer
-- A valid BroJS API key set in the environment variable `JOURNAL_MCP_PAT`.
-- (Optional) A virtual environment to isolate dependencies.
+## Архитектура
+
+```
+main.py
+├── LLM: ChatOpenAI → BroJS (openai/gpt-oss-20b:free)
+├── Backend: CompositeBackend
+│   ├── LocalShellBackend  (virtual_mode=True, root=./workspace/)
+│   └── FilesystemBackend  (virtual_mode=True, route=/fs/)
+└── Tools: web_search, export_virtual_files
+```
+
+Агент работает в **виртуальной ФС** (`./workspace/`). По завершении инструмент `export_virtual_files` копирует все созданные файлы в реальную папку `./output/`.
+
+## Установка
 
-## Installation
 ```bash
-# Clone the repository
-git clone https://git.brojs.ru/KirillKutlakhmetov/task-69de7223f309a98be0007e09.git
-cd task-69de7223f309a98be0007e09
-
-# Create and activate a virtual environment (recommended)
-python -m venv .venv
-source .venv/bin/activate  # On Windows use .venv\Scripts\activate
-
-# Install dependencies
 pip install -r requirements.txt
 ```
 
-## Usage
-```bash
-# Ensure the environment variable is set
-export JOURNAL_MCP_PAT=your_brojs_api_key
+## Переменные окружения
 
-# Run the agent
-python main.py
+| Переменная | Описание |
+|------------|----------|
+| `JOURNAL_MCP_PAT` | Токен доступа к BroJS LLM |
+
+Создай файл `.env`:
+```
+JOURNAL_MCP_PAT=jrnl_...
 ```
 
-The agent will perform a sample query (`"Python async programming"`). After completion, the virtual files created during the run will be exported to the `./exported_files` directory.
+## Запуск
 
-## Project Structure
-- `main.py` – Entry point and agent definition.
-- `requirements.txt` – Python dependencies.
-- `README.md` – Project documentation.
+```bash
+# Запрос по умолчанию (исследование LangGraph)
+python main.py
 
-## Customization
-- To change the query, modify the `user_query` variable in `main.py`.
-- To add more tools, define additional functions decorated with `@tool` and include them in the `tools` list when creating the agent.
-- The agent can be extended to accept user input at runtime by replacing the hard‑coded query.
+# Свой запрос
+python main.py "расскажи про LangChain агентов и сохрани в файл"
+```
 
-## License
-MIT License.
+## Пример работы
+
+```
+Запрос: Найди информацию о LangGraph...
+
+=== Ответ агента ===
+Файл langgraph_research.md сохранён и выгружен в ./output/
+
+=== Файлы в output/ ===
+  langgraph_research.md (2847 байт)
+```
+
+## Источники
+
+- [deep-agents-from-scratch](https://github.com/langchain-ai/deep-agents-from-scratch)
+- [deepagents PyPI](https://pypi.org/project/deepagents/)
+- [LangChain docs](https://python.langchain.com/)