🤖 Агент решения домашних заданий

Берёт задания из журнала через MCP, решает их с помощью LLM, заливает на git.brojs.ru и отправляет ссылку преподавателю. Общаться с агентом можно через чат на localhost:8123 — так же, как у преподавателя.

Структура проекта

homework_agent/
├── agent.py          # Граф агента + CLI (точка входа для langgraph dev)
├── llm.py            # Фабрика LLM: openai (пары) ↔ gigachat (дома)
├── mcp_clients.py    # Загрузка MCP-инструментов (journal + gitea)
├── gitea_rest.py     # REST fallback для Gitea (если uvx недоступен)
├── langgraph.json    # Конфиг для langgraph dev
├── requirements.txt
├── .env.example
└── .env              # ← создай сам, не коммить!

Установка

# 1. Виртуальное окружение
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Mac/Linux

# 2. Зависимости
pip install -r requirements.txt

# 3. uv (нужен для Gitea MCP, если будешь использовать)
pip install uv

Настройка .env

cp .env.example .env
# открой .env и заполни значения

Токен журнала — JOURNAL_MCP_PAT (самое важное!)

Без него агент не видит задания. Спроси у преподавателя или найди сам:

1. Зайди на https://platform.brojs.ru (авторизуйся)
2. Открой DevTools (F12) → вкладка Network
3. Обнови страницу, кликни на любой запрос к /jrnl-bh/api/...
4. В заголовках найди Authorization: Bearer <токен> — это и есть JOURNAL_MCP_PAT

Токен Gitea — GITEA_TOKEN

1. Зайди на https://git.brojs.ru (авторизуйся)
2. Аватарка → Settings → Applications → Generate New Token
3. Поставь права: repository: read & write
4. Скопируй в .env как GITEA_TOKEN
5. Туда же GITEA_USERNAME — твой логин на git.brojs.ru

Переключение LLM

На парах (gpt-oss-20b):

LLM_PROVIDER=openai
OPENAI_BASE_URL=https://89fe241d-b6f4-4e49-b3d5-9ed3c91dbe2f.tunnel4.com/v1
OPENAI_MODEL=openi/gpt-oss-20b
OPENAI_API_KEY=fake

⚠️ URL туннеля меняется каждый день — спрашивай актуальный у преподавателя

Дома (GigaChat, бесплатно):

LLM_PROVIDER=gigachat
GIGACHAT_CREDENTIALS=твои_credentials
GIGACHAT_SCOPE=GIGACHAT_API_B2B

Получить credentials: https://developers.sber.ru/studio/workspaces/my-space/get-token/gigachat

🚀 Запуск чата (localhost:8123)

langgraph dev

Открой в браузере http://localhost:8123 — появится чат. Можно писать:

• «покажи мои задания»
• «реши задание с id=abc123»
• «какие задания есть в курсе xyz?»

Запуск из консоли (без чата)

# Показать список заданий
python agent.py --list

# Решить конкретное задание
python agent.py --task-id <id>

# Решить задания курса
python agent.py --course-id <id>

# Посмотреть решение без отправки
python agent.py --task-id <id> --dry-run

Как это работает

Ты пишешь в чат
  ↓
agent_graph (LangGraph ReAct)
  ↓ читает задания
  mcp__journal-mcp__tasks_list / task_get
  ↓ пишет код (LLM)
  gpt-oss-20b / GigaChat
  ↓ заливает на Gitea
  upload_solution → git.brojs.ru/username/dz
  ↓ отправляет ссылку
  mcp__journal-mcp__submission_teacher_set_status

Частые проблемы

Ошибка	Решение
JOURNAL_MCP_PAT не задан	Добавь токен в .env
FileNotFoundError: uvx	pip install uv или работает REST fallback
LLM не отвечает	Проверь OPENAI_BASE_URL — URL туннеля мог смениться
langgraph: command not found	pip install langgraph-cli[inmem]