add README.md

README.md

@@ -1,2 +1,57 @@
-# task-6a1867fa8a94f887e50d52bd
+# Planning Agent – LangGraph Demo
 
+## What this project does
+This repository contains a minimal, fully‑working example of a **LangGraph** agent that first *plans* a task into discrete steps and then *executes* those steps one by one.  The goal is to satisfy the exam assignment “Экзамен: Планирующий агент” from the BroJS course.
+
+The agent:
+1. Uses an LLM (BroJS GPT‑OSS‑20B) to split a natural‑language task into a numbered list of actions.
+2. Executes each action sequentially – in this demo we simply echo the step, but you can replace it with real tool calls.
+3. Stops when all steps are finished and prints the accumulated results.
+
+The code is intentionally simple yet fully typed, documented and contains three example tasks that run automatically when executing `python main.py`.
+
+## File structure
+```
+├── main.py          – entry point with LangGraph implementation
+├── requirements.txt – Python dependencies
+└── README.md        – this documentation
+```
+
+## Installation
+```bash
+# Create a virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+Make sure you have the **JOURNAL_MCP_PAT** environment variable set – it is required by the BroJS LLM endpoint.
+
+## Running the demo
+```bash
+python main.py
+```
+You will see three tasks processed sequentially, each showing:
+- The original task description
+- A numbered plan generated by the LLM
+- Execution results for every step
+
+Feel free to modify `examples` in `main.py` or replace the execution node with real tool calls.
+
+## How it works (high‑level)
+1. **State** – a TypedDict holding `task`, optional `plan`, `current_step`, and accumulated `results`.
+2. **Planning node** – sends the task to the LLM, expects JSON output `{"plan": ["step 1", "step 2", ...]}`.
+3. **Execution node** – takes the next step from `plan`, records a dummy result.
+4. **Conditional edge** – loops until all steps are processed.
+5. The graph is compiled and run with `agent.stream` to capture intermediate states for pretty printing.
+
+## Extending
+- Replace the execution logic with calls to real tools (e.g., web search, calculator).
+- Add a *verification* node that asks the LLM if the step succeeded before moving on.
+- Persist state using LangGraph checkpoints for long‑running tasks.
+
+---
+
+**Author:** Kirill Kutlahmetov – student of BroJS course (course ID: 698b49da77cb6d4d2e43ce78)