Экзамен: Самокорректирующийся агент: README.md

README.md

@@ -1,89 +1,93 @@
 # Самокорректирующийся агент
 
 ## Описание проекта
-В этом проекте реализован **LangGraph**‑агент, который:
-1. Выполняет задачу через заданный инструмент.
-2. Проверяет результат с помощью LLM (LLM‑as‑judge).
-3. При неудаче повторяет попытку до тех пор, пока результат не будет признан успешным
-   или пока не исчерпается лимит `max_attempts`.
+Проект реализует **LangGraph**‑агента, который:
+1. Выполняет задачу через инструмент (или набор инструментов).
+2. Проверяет результат с помощью LLM‑судьи (`LLM-as-judge`).
+3. При неудаче повторяет попытку до тех пор, пока не получит `success`
+   или не исчерпает заданный лимит `max_attempts`.
 
-Это демонстрация автоматической самопроверки и ретрая без участия человека.
+Это демонстрация автоматической самопроверки и ретрая в стиле HITL (Human‑in‑the‑Loop) без участия человека.
 
 ## Стек технологий
-
 - Python 3.10+
 - `langgraph` – библиотека для построения графов агентов.
-- `langchain-openai` (или `langchain-ollama`) – подключение к LLM.
-
-```bash
-pip install langgraph langchain-openai
-```
-
-## Структура проекта
-
-```
-├── main.py          # точка входа, содержит всю логику агента
-└── README.md        # это файл
-```
-
-### Файл `main.py`
-
-- **AgentState** – тип состояния графа.
-- **execute_task** – узел, который вызывает инструмент (в примере используется `unreliable_tool`).
-- **verify_result** – LLM‑ас‑джюри, оценивает результат как `success` или `failed`.
-- **handle_error** – увеличивает счётчик попыток и готовит повторную попытку.
-- Цикл: `START → execute_task → verify_result → (success|failed) → handle_error?`.
+- `langchain-openai` или `langchain-ollama` – LLM‑интеграция (OpenAI API либо локальный Ollama).
 
 ## Установка зависимостей
 
 ```bash
-# Создайте виртуальное окружение (рекомендовано)
+# Создайте виртуальное окружение (рекомендуется)
 python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\Scripts\activate
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
 
 # Установите зависимости
-pip install langgraph langchain-openai
+pip install langgraph langchain-openai  # или langchain-ollama
 ```
 
+> **Важно**  
+> Если вы используете `langchain-openai`, убедитесь, что переменная окружения `OPENAI_API_KEY` установлена:
+> ```bash
+> export OPENAI_API_KEY="sk-..."
+> ```
+
 ## Запуск проекта
 
+### 1. Основной скрипт `main.py`
+Скрипт запускает агент с заданной задачей и выводит результат.
+
 ```bash
 python main.py
 ```
 
-При запуске агент выполнит задачу, проверит результат и при необходимости повторит попытку. В консоли будет выводить статус каждой итерации.
+Внутри `main.py` задаётся:
+- `task`: исходная задача (строка).
+- `max_attempts`: максимальное число попыток.
+- `unreliable_tool`: пример инструмента, который иногда генерирует ошибку.
 
-### Пример вывода
+### 2. Пример использования в интерактивном режиме
 
-```
-Attempt 1: Task executed successfully.
-Verification result: failed
-Retrying... (attempt 2)
+```python
+from main import run_agent
 
-Attempt 2: Tool raised an error.
-Error: Simulated tool failure.
-Retrying... (attempt 3)
-
-Attempt 3: Task executed successfully.
-Verification result: success
-Agent finished with status: success
+result = run_agent(
+    task="Напиши короткую историю о путешествии робота",
+    max_attempts=5,
+)
+print(result)   # {"status": "success", "attempts": 3, ...}
 ```
 
-## Как использовать
+> `run_agent` – публичная функция из `main.py`, которую можно импортировать в другие скрипты.
 
-1. **Измените задачу** – в `main.py` найдите строку  
-   ```python
-   task = "Напиши короткую историю о путешествии робота."
-   ```
-   и замените её на свою.
-2. **Настройте LLM** – при необходимости поменяйте провайдера (OpenAI, Ollama и т.д.) в `ChatOpenAI(...)`.
-3. **Установите лимит попыток** – задайте нужное значение `max_attempts` в состоянии графа.
+## Пример вывода
 
-## Тестовый инструмент
+```text
+Attempt 1: Выполнение задачи...
+Result: "Робот отправился в космос..."
+Проверка результата... Неудача. Ошибка: Недостаточно деталей.
+Повторяем попытку...
 
-В примере используется `unreliable_tool`, который случайно генерирует ошибку 30 % времени, чтобы продемонстрировать работу ретрая. Вы можете заменить его на любой реальный инструмент из LangChain.
+Attempt 2: Выполнение задачи...
+Result: "Робот отправился в космос, но забыл зарядку..."
+Проверка результата... Успех!
+```
+
+## Как это работает
+
+1. **execute_task** – вызывает `unreliable_tool` (или любой другой инструмент) и сохраняет результат.
+2. **verify_result** – LLM оценивает строку результата как `success` или `failed`.
+3. Если `failed` и попыток осталось, **handle_error** увеличивает счётчик и переходит к `execute_task` снова.
+4. После достижения `max_attempts` агент завершается со статусом `max_attempts`.
+
+## Расширение проекта
+
+- Добавьте свои инструменты в список `tools`.
+- Настройте более сложные правила проверки результата, используя собственный шаблон LLM‑судьи.
+- Интегрируйте с другими LLM (Claude, Gemini) через `langchain-openai`/`langchain-google-genai`.
+
+## Лицензия
+MIT License – свободно используйте и модифицируйте этот код для своих проектов.
 
 --- 
 
-**Автор:** [Ваше имя]  
-**Дата:** 2026‑05‑28
+**Ссылка на репозиторий:** https://github.com/your-username/self-correcting-agent (замените на актуальную)