Локальная разработка

Обновлено 10 декабря 2025

Локальная разработка позволяет отладить поведение агента, до его публикации на стенды GigaLab.

Для работы в среде исполнения сервиса, агент должен запускаться с помощью команды langgraph dev, которая запускает агента локально.

Подробнее о требованиях к агенту — в разделе Требования и рекомендации.

В этом разделе, на примере образца агента «Рик и Морти» вы узнаете:

• как запустить локальный сервер с агентом с помощью LangGraph CLI;
• как протестировать запуск через Docker на базе образа среды исполнения GigaLab.

Перед началом работы

Для успешного выполнения инструкций вам понадобятся:

• Python версии 3.12.3 или выше;

• Docker — для тестирования работы Docker-образа;

• Браузер для доступа к LangGraph Studio;

• Ключ авторизации GigaChat API для региона Advanced. Ключ передается в переменной окружения GIGACHAT_CREDENTIALS.

  О том как получить ключ авторизации — в документации GigaChat API.

• Ключ для авторизации запросов в Search Plugin (необязательно). Ключ передается в переменной окружения SEARCH_PLUGIN_KEY.

Запуск агента с помощью LangGraph CLI

Используйте этот способ для разрработки и отладки агента, а также проверки команды langgraph dev.

Этот способ подходит для разработки и отладки агента.

Шаг 1: Подготовка окружения

# Создаем виртуальное окружение Python
python3 -m venv .venv
source .venv/bin/activate

# Устанавливаем LangGraph CLI
pip install "langgraph-cli[inmem]"

# Устанавливаем зависимости агента
pip install -r agents/sample/requirements.txt

Шаг 2: Настройка конфигурации

# Создаем файл конфигурации из шаблона
cp .env.example .env

Отредактируйте файл .env и укажите ваши ключи:

# Основные настройки GigaChat
USE_GIGACHAT_ADVANCED=True
GIGACHAT_CREDENTIALS=YOUR_GIGACHAT_TOKEN_HERE
GIGACHAT_BASE_URL=https://gigachat.sberdevices.ru/v1/
GIGACHAT_SCOPE=GIGACHAT_API_CORP
GIGACHAT_MODEL=GigaChat-2-Max

# Search Plugin (опционально)
SEARCH_PLUGIN_URL=https://search-plugin-p-nasearch.apps.advosp.sberdevices.ru/retrieval
SEARCH_PLUGIN_KEY=YOUR_SEARCH_PLUGIN_KEY_HERE

# Отладка (0 - отключена, 1 - включена)
ADDITIONAL_KWARGS_TO_MESSAGES=0

Шаг 3: Запуск агента

# Запускаем LangGraph development server
langgraph dev --config agents/langgraph.json

После запуска вы увидите примерно следующий вывод:

INFO:langgraph_api.cli:

        Welcome to

╦  ┌─┐┌┐┌┌─┐╔═╗┬─┐┌─┐┌─┐┬ ┬
║  ├─┤││││ ┬║ ╦├┬┘├─┤├─┘├─┤
╩═╝┴ ┴┘└┘└─┘╚═╝┴└─┴ ┴┴  ┴ ┴

- 🚀 API: http://127.0.0.1:2024
- 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
- 📚 API Docs: http://127.0.0.1:2024/docs

Шаг 4: Тестирование агента

Через LangGraph Studio (рекомендуется)

1. Откройте браузер
2. Перейдите по ссылке: LangGraph Studio
3. Выберите режим "Chat" для общения с агентом
4. Отправьте тестовое сообщение, например: "Привет, кто ты?"

Через API (для разработчиков)

# Тестовый запрос к API агента
curl -X POST http://127.0.0.1:2024/runs/stream \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "sample",
    "thread_id": "0199976b-622b-7788-87ef-a34dd6d5f6ed",
    "if_not_exists": "create",
    "input": {"messages": [{"role": "user", "content": "Привет!"}]}
  }'

Отладка и логи

При запуске через langgraph dev все логи выводятся в консоль. Вы можете:

• Видеть вызовы инструментов (калькулятор, поиск, Wikipedia)
• Отслеживать ошибки в реальном времени
• Изменять код агента на лету (перезагрузка происходит автоматически)

Запуск на базе Docker-образа среды исполнения GigaLab

Этот способ максимально приближен к production-окружению.

Шаг 1: Подготовка окружения

# Создаем файл конфигурации
cp .env.example .env
# Отредактируйте .env как описано в Способе 1

Шаг 2: Сборка Docker образа

# Авторизуемся в SberDevices registry для доступа к базовому образу
docker login registry.sberdevices.ru

# Собираем образ с тегом local
docker build -t giga-labs-agent:local .

Процесс сборки включает:

• Использование базового образа agent-toolkit:latest
• Установку зависимостей из requirements.txt
• Копирование кода агента в контейнер

Шаг 3: Запуск контейнера

# Запускаем контейнер с проброской портов и переменных окружения
docker run --rm \
  --name giga-labs-agent \
  --env-file .env \
  -p 8080:8080 \
  giga-labs-agent:local

Альтерна тивный запуск с отдельными переменными:

docker run --rm \
  --name giga-labs-agent \
  -p 8080:8080 \
  -e USE_GIGACHAT_ADVANCED=True \
  -e GIGACHAT_CREDENTIALS=YOUR_TOKEN \
  -e GIGACHAT_MODEL=GigaChat-2-Max \
  -e SEARCH_PLUGIN_KEY=YOUR_KEY \
  giga-labs-agent:local

Шаг 4: Тестирование Docker-версии

После запуска контейнера, можно отправить тестовый запрос агенту

curl -X POST http://127.0.0.1:8080/runs/stream \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "sample",
    "thread_id": "0199976b-622b-7788-87ef-a34dd6d5f6ed",
    "if_not_exists": "create",
    "input": {"messages": [{"role": "user", "content": "Привет!"}]}
  }'

Полезные Docker команды

# Просмотр логов контейнера
docker logs giga-labs-agent

# Подключение к запущенному контейнеру для отладки
docker exec -it giga-labs-agent /bin/bash

# Остановка контейнера
docker stop giga-labs-agent

# Удаление образа
docker rmi giga-labs-agent:local