Как создать планировщик путешествий с ИИ-агентом на CopilotKit, LangGraph и Google Maps API

Кто сказал, что разработка ИИ‑агента — это сложно, долго и только для крупных корпораций? Сегодня мы убедимся, что добавить в своё приложение умного ассистента может каждый. Встречайте: ИИ‑агент, который помогает пользователю находить оптимальные варианты и обновляет данные в реальном времени.

Используя CopilotKit, LangGraph и Google Maps API, мы создадим приложение, которое не только действует по сценариям, но и предлагает решения. Мы изучим, как реализовать human‑in‑the‑loop, чтобы пользователь мог одобрять или отклонять действия агента.

Приятного прочтения (‑:

Что такое CopilotKit?

CopilotKit — это фреймворк, который превращает создание ИИ‑ассистентов из сложного инженерного процесса в увлекательную и понятную задачу. Вам больше не нужно вручную продумывать каждую деталь интеграции ИИ в приложение — CopilotKit сделает это за вас. Хотите встраивать умных ассистентов прямо в свои приложения? Легко. Настроить чат‑бота, который понимает контекст и выполняет задачи? Несколько строк кода — и готово.

CopilotKit предлагает полный набор инструментов для создания умных ИИ‑ассистентов. Вы можете подключать готовые компоненты чат‑ботов или создавать свои с нуля, при этом поддерживается «безголовый» UI для полного контроля над дизайном. Ассистенты не только отвечают на запросы, но и выполняют действия внутри приложения — например, записывают данные, ищут информацию или запускают процессы. Платформа позволяет создавать динамические React‑компоненты прямо внутри чата, делая взаимодействие не только функциональным, но и визуально привлекательным. Ассистенты понимают контекст и текущее состояние приложения, благодаря чему они адаптируют ответы и действия к конкретной ситуации.

Всё это поддерживается интеграцией с ведущими ИИ‑платформами: OpenAI, Anthropic, Azure, Google Generative AI и другими. CopilotKit — это билет в мир умных ИИ‑ассистентов, которые меняют привычные приложения и делают их удобнее и функциональнее.

Подготавливаем файлы проекта

В этом гайде мы начнём с приложения, в котором ещё нет ИИ, затем шаг за шагом добавим функции, которые предоставляет CopilotKit. Исходный код доступен здесь.

Начальная настройка

Мы будем работать с веткой coagents-travel-tutorial-start, в ней уже содержится стартовый код для нашего приложения. Клонируем её на свой компьютер:

git clone -b coagents-travel-tutorial-start https://github.com/CopilotKit/CopilotKit.git
cd CopilotKit

Пример кода для туториала находится в директории examples/coagents-travel, которая разделена на два каталога: ui — содержит приложение на Next.js, куда мы будем интегрировать агента LangGraph, и agent — включает Python‑реализацию самого агента LangGraph. Сначала перейдём в директорию examples/coagents-travel, чтобы начать настройку:

cd examples/coagents-travel

Установка зависимостей

Начнём с настройки приложения на Next.js. Убедитесь, что у вас установлен менеджер пакетов pnpm. Заскочим в папку ui и установим все необходимые зависимости проекта:

npm install -g pnpm@latest-10
cd ui
pnpm install

Установка API-ключей

Для работы с CopilotKit вам понадобятся API‑ключи. Создадим файл .env в директории ui и добавим в него переменные окружения:

# ui/.env

OPENAI_API_KEY=<ваш ключ доступа к API OpenAI>
NEXT_PUBLIC_CPK_PUBLIC_API_KEY=<ваш ключ доступа к API CopilotKit>

Ключ API для CopilotKit можно получить на официальном сайте платформы. Когда все зависимости установлены, запустим сервер разработки:

pnpm run dev

Если всё настроено правильно, откройте в браузере http://localhost:3000 — здесь вы увидите работающее приложение‑планировщик. Оно ещё не обладает искусственным интеллектом, но это лишь вопрос времени.

Давайте теперь глубже разберёмся, как работает агент LangGraph.

Агент LangGraph

Перед тем как интегрировать агента LangGraph, давайте уделим немного времени тому, чтобы понять, как он работает. Для этого урока мы не будем создавать LangGraph‑агента с нуля — вместо этого мы воспользуемся готовой версией, расположенной в директории agent.

Как устроен агент LangGraph?

LangGraph — это, по сути, графовая структура, где каждый узел выполняет конкретную задачу: один может обрабатывать запросы, другой — сохранять данные, третий — обновлять состояние приложения. Такая архитектура позволяет агенту принимать сложные решения и обрабатывать задачи последовательно или параллельно.

Установка LangGraph Studio

LangGraph Studio — это отличный инструмент для визуализации и отладки рабочих процессов LangGraph. Настоятельно рекомендуется использовать LangGraph Studio совместно с CopilotKit, чтобы лучше понимать, как LangGraph функционирует. Установка LangGraph Studio подробно описана здесь.

Ещё одна установка API-ключей

Создадим файл .env в директории agent и внесём в него следующие переменные окружения:

# agent/.env

OPENAI_API_KEY=<ваш ключ доступа к API OpenAI>
GOOGLE_MAPS_API_KEY=<ваш ключ доступа к API Google Maps>

Если вам нужен API‑ключ для Google Maps, можно обратиться к официальному руководству от Google для его получения.

Визуализация агента LangGraph

Когда LangGraph Studio установлена, давайте откроем в ней директорию examples/coagents-travel/agent, чтобы загрузить нужного агента LangGraph и увидеть его работу в визуальном формате. Настройка может занять пару минут. Результат будет выглядеть как интерактивная схема, которая показывает взаимодействия между узлами — логику работы агента.

Тестирование агента LangGraph

Как проверить, что агент работает? Всё просто: добавьте сообщение в переменную состояния messages (это, по сути, запрос пользователя) и нажмите Submit. После чего агент обработает ваш ввод, ответит в чате и выполнит связанные задачи. Например:

• Агент активирует узел search_node, чтобы выполнить поиск.

• Получив ответ, задействует узел trips_node, чтобы обновить состояние приложения, добавив новую поездку.

Круто, правда? Всё это можно наблюдать на графе. Агент не только решает задачи, но и показывает, как именно он это делает.

Точки останова: контроль за действиями агента

Что если ИИ в какой‑то момент понадобится подсказка человека? Здесь на помощь приходит концепция human‑in‑the‑loop — пользовательский контроль над ключевыми решениями агента. Пример из жизни: представьте, что агент хочет добавить поездку в ваш список, но вы хотите проверить детали перед подтверждением. Именно для таких случаев LangGraph поддерживает точки останова.

Чтобы добавить точку останова, мы нажмём на узел trips_node и включим параметр interrupt_after. Ну а теперь пробуем создать новую поездку — агент остановится на полпути, запросит одобрения и только потом продолжит выполнение.

Оставляем LangGraph Studio запущенной

Вашему агенту нужно постоянное рабочее пространство, и пока таким местом будет LangGraph Studio. Оставьте студию запущенной локально. В нижнем левом углу интерфейса вы увидите URL‑адрес, он пригодится позже для подключения к агенту.

Теперь интегрируем LangGraph в наше приложение, чтобы превратить его в настоящего ассистента-агента.

Настройка CopilotKit

Сделаем наш проект по‑настоящему умным и свяжем всё воедино. У нас уже есть приложение и агент, а сейчас мы добавим CopilotKit, чтобы интеграция стала реальностью. Для этой задачи мы установим следующие зависимости:

• @copilotkit/react-core: основная библиотека, содержащая провайдер CopilotKit и полезные хуки для управления функциональностью.

• @copilotkit/react-ui: библиотека пользовательского интерфейса CopilotKit. Здесь находятся готовые компоненты, такие как боковая панель, всплывающее окно чата, текстовые поля и многое другое.

Сначала откроем директорию ui и установим пакеты CopilotKit:

cd ../ui
pnpm add @copilotkit/react-core @copilotkit/react-ui

Эти два пакета — всё, что нужно для интеграции CopilotKit в React‑приложение. Первый пакет отвечает за функциональность, а второй — за визуальные компоненты.

Добавление CopilotKit

Здесь у нас есть два варианта, как мы можем настроить CopilotKit: Copilot Cloud — быстрый и удобная управляемая платформа, где уже настроено всё необходимое, и самостоятельный хостинг, который подходит тем, кто хочет большего контроля.

Мы выберем облачный вариант — это проще, быстрее и не требует сложных конфигураций. Если вы захотите настроить сервер вторым способом, обязательно загляните в руководство по самостоятельному хостингу.

Настройка Copilot Cloud

Подключение к Copilot Cloud начинается с создания аккаунта на платформе. Регистрация занимает всего минуту, после чего откроется доступ к системе.

Следующий шаг — получение API‑ключа Copilot Cloud. Для этого нужно войти в систему, ввести API‑ключ OpenAI, нажать галочку — и ваш публичный ключ будет сгенерирован автоматически.

И наконец, откроем файл .env в директории ui и добавим полученный API‑ключ Copilot Cloud:

# ui/.env

# ...Здесь другие переменные окружения...
NEXT_PUBLIC_CPK_PUBLIC_API_KEY=<ваш ключ доступа к API CopilotKit>

Интеграция CopilotKit

Настроив ключи, пришло время интегрировать CopilotKit в приложение. Начнём с обёртки: откроем файл ui/app/page.tsx и «обмотаем» приложение компонентом CopilotKit.

Далее займёмся пользовательскими компонентами. Платформа предоставляет готовые элементы вроде <CopilotPopup /> и <CopilotSidebar />, которые легко интегрируются и дополняют ваш интерфейс. Хотите больше кастомизации? Включите «безголовый режим» через хук useCopilotChat — это позволит создать интерфейс, адаптированный под ваш дизайн.

Для добавления боковой панели чата используем компонент <CopilotSidebar /> — обновим файл ui/app/page.tsx, добавив этот элемент. Убедимся, что импортированы необходимые стили — так панель будет выглядеть великолепно сразу после внедрения:

// ui/app/page.tsx

"use client";

// ...Здесь другие импорты...
import { TasksList } from "@/components/TasksList";
import { TasksProvider } from "@/lib/hooks/use-tasks";
import { CopilotKit } from "@copilotkit/react-core";
import { CopilotSidebar } from "@copilotkit/react-ui";
import "@copilotkit/react-ui/styles.css";

//...

export default function Home() {
  return (
    <CopilotKit
      publicApiKey={process.env.NEXT_PUBLIC_CPK_PUBLIC_API_KEY}
    >
      <CopilotSidebar
        defaultOpen={true}
        clickOutsideToClose={false}
        labels={{
          title: "Планировщик поездок",
          initial: "Привет!