Human‑in‑the‑Loop через middleware: README.md

2026-05-26 09:35:41 +00:00
parent 9a647a8d8d
commit 0d80914a27
1 changed files with 161 additions and 0 deletions
@@ -0,0 +1,161 @@
 # Human‑in‑the‑Loop через Middleware  
 ## Описание  
 В этом проекте реализован агент на базе **LangChain** с встроенным middleware `HumanInTheLoopMiddleware`.  
 При каждом вызове инструмента агент останавливается и выводит в терминал сообщение вида:
 ```
 > Инструмент: get_weather
 > Запрос: Какая погода сегодня в Москве?
 > Выберите действие: [approve / reject]
 ```
 Пользователь вводит `approve` или `reject`. После этого выполнение агента возобновляется, а результат инструмента (или отказ) возвращается в цепочку.  
 Мiddleware автоматически формирует запрос на подтверждение и обрабатывает ответ через `Command(resume={"decisions": [...]})`.
 > **Важно**: для корректной работы паузы нужен чекпоинтер (`MemorySaver`). Без него агент не сможет сохранить состояние между остановками.
 ---
 ## Структура проекта  
 ```
 ├── agent.py          # Создание агента с HumanInTheLoopMiddleware
 ├── run_agent.py      # Запуск интерактивного диалога с пользователем
 └── requirements.txt # Зависимости
 ```
 ---
 ## Установка зависимостей
 ```bash
 # 1. Клонируйте репозиторий (или скопируйте файлы)
 git clone https://github.com/your-username/human-in-loop-middleware.git
 cd human-in-loop-middleware
 # 2. Создайте виртуальное окружение (рекомендовано)
 python -m venv .venv
 source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
 # 3. Установите зависимости
 pip install -r requirements.txt
 ```
 `requirements.txt` содержит:
 ```text
 langchain==0.*          # актуальная версия LangChain
 langgraph==0.*          # для MemorySaver и middleware
 openai==1.*             # если используете OpenAI LLM
 python-dotenv==1.*      # для загрузки переменных окружения (API‑ключи)
 ```
 > **Примечание**: Если вы хотите использовать другой LLM, замените `langchain` на нужный пакет и настройте `llm` в `agent.py`.
 ---
 ## Запуск
 ### 1. Создание агента (`agent.py`)
 ```bash
 python agent.py
 ```
 Файл создаёт объект `agent`, но не запускает диалог. Он нужен для импорта при запуске основного скрипта.
 ### 2. Интерактивный запуск (`run_agent.py`)
 ```bash
 python run_agent.py
 ```
 После запуска вы увидите приглашение:
 ```
 > Какой вопрос у вас есть? (напишите 'exit' чтобы выйти)
 ```
 Пример взаимодействия:
 ```
 > Какую погоду сегодня в Москве?
 > Инструмент: get_weather
 > Запрос: Какая погода сегодня в Москве?
 > Выберите действие: [approve / reject] > approve
 > Погода в Москве сегодня 22°C, ясно.
 ```
 Если пользователь вводит `reject`, агент сообщает об отказе и предлагает задать другой вопрос.
 ---
 ## Пример использования
 ```python
 from langchain.agents import create_agent
 from langchain.agents.middleware import HumanInTheLoopMiddleware
 from langgraph.checkpoint.memory import MemorySaver
 import os
 from dotenv import load_dotenv
 from langchain_openai import ChatOpenAI
 load_dotenv()  # загружает переменные из .env (OPENAI_API_KEY)
 # Инициализация LLM
 llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)
 # Пример инструмента
 def get_weather(location: str) -> str:
    """Возвращает погоду в указанном месте."""
    # В реальном проекте здесь будет запрос к API погоды
    return f"Погода в {location} сегодня 22°C, ясно."
 get_weather_tool = {
    "name": "get_weather",
    "description": "Получить текущую погоду по местоположению.",
    "func": get_weather,
 }
 memory = MemorySaver()
 agent = create_agent(
    model=llm,
    tools=[get_weather_tool],
    system_prompt="Ты полезный ассистент, который может получать погоду.",
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={"get_weather": True},
            description_prefix="Подтвердите вызов инструмента",
        ),
    ],
    checkpointer=memory,
 )
 # Запуск диалога
 while True:
    user_input = input("> Какой вопрос у вас есть? (exit) ")
    if user_input.lower() == "exit":
        break
    response = agent.invoke({"input": user_input})
    print(response["output"])
 ```
 ---
 ## Что дальше?
 - **Добавить больше инструментов** – просто расширьте список `tools` и настройте `interrupt_on`.
 - **Настроить разрешённые решения** – в `HumanInTheLoopMiddleware` можно указать `allowed_decisions=["approve", "reject"]`, чтобы убрать вариант редактирования.
 - **Сохранить историю** – используйте более продвинутый чекпоинтер (`SQLiteSaver`) для долгосрочного хранения сессий.
 ---
 ## Ссылки
 - [Документация LangChain: Human‑in‑the‑Loop](https://docs.langchain.com/oss/python/langchain/human-in-the-loop)
 - [GitHub репозиторий LangChain](https://github.com/langchain-ai/langchain)
 ---