Как научить нейросеть работать руками: создание полноценного ИИ-агента с MCP и LangGraph за час

Друзья, приветствую! Надеюсь, успели соскучиться.

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

На повестке дня — LangGraph и MCP: инструменты, с помощью которых можно создавать действительно полезных ИИ-агентов.

Если раньше мы спорили о том, какая нейросеть лучше отвечает на русском языке, то сегодня поле битвы сместилось в сторону более прикладных задач: кто лучше справляется с ролью ИИ-агента? Какие фреймворки действительно упрощают разработку? И как интегрировать всё это добро в реальный проект?

Но прежде чем нырнуть в практику и код, давайте разберёмся с базовыми понятиями. Особенно с двумя ключевыми: ИИ-агенты и MCP. Без них разговор про LangGraph будет неполным.

ИИ-агенты простыми словами

ИИ-агенты — это не просто «прокачанные» чат-боты. Они представляют собой более сложные, автономные сущности, которые обладают двумя важнейшими особенностями:

1. Умение взаимодействовать и координироваться.
   Современные агенты способны делить задачи на подзадачи, вызывать других агентов, запрашивать внешние данные, работать в команде. Это уже не одиночный ассистент, а распределённая система, где каждый компонент может вносить свой вклад.

2. Доступ к внешним ресурсам.
   ИИ-агент больше не ограничен рамками диалога. Он может обращаться к базам данных, выполнять вызовы к API, взаимодействовать с локальными файлами, векторными хранилищами знаний и даже запускать команды в терминале. Всё это стало возможным благодаря появлению MCP — нового уровня интеграции между моделью и средой.

Что такое MCP (Model Context Protocol)

Если говорить просто: MCP — это мост между нейросетью и её окружением. Он позволяет модели «понимать» контекст задачи, получать доступ к данным, выполнять вызовы и формировать обоснованные действия, а не просто выдавать текстовые ответы.

Представим аналогию:

• У вас есть нейросеть — она умеет рассуждать и генерировать тексты.

• Есть данные и инструменты — документы, API, базы знаний, терминал, код.

• И есть MCP — это интерфейс, который позволяет модели взаимодействовать с этими внешними источниками так, как если бы они были частью её внутреннего мира.

Без MCP:

Модель — это изолированный диалоговый движок. Вы подаёте ей текст — она отвечает. И всё.

С MCP:

Модель становится полноценным исполнителем задач:

• получает доступ к структурам данных и API;

• вызывает внешние функции;

• ориентируется в текущем состоянии проекта или приложения;

• может запоминать, отслеживать и изменять контекст по мере диалога;

• использует расширения, такие как инструменты поиска, код-раннеры, базу векторных эмбеддингов и пр.

В техническом смысле MCP — это протокол взаимодействия между LLM и её окружением, где контекст подаётся в виде структурированных объектов (вместо «сырого» текста), а вызовы оформляются как интерактивные операции (например, function calling, tool usage или agent actions). Именно это и превращает обычную модель в настоящего ИИ-агента, способного делать больше, чем просто «поговорить».

А теперь — к делу!

Теперь, когда мы разобрались с базовыми понятиями, логично задаться вопросом: «Как всё это реализовать на практике в Python?»

Вот здесь и вступает в игру LangGraph — мощный фреймворк для построения графов состояний, поведения агентов и цепочек мышления. Он позволяет «прошивать» логику взаимодействия между агентами, инструментами и пользователем, создавая живую архитектуру ИИ, адаптирующуюся к задачам.

В следующих разделах мы посмотрим, как:

• строится агент с нуля;

• создаются состояния, переходы и события;

• интегрируются функции и инструменты;

• и как вся эта экосистема работает в реальном проекте.

Немного теории: что такое LangGraph

Прежде чем приступить к практике, нужно сказать пару слов о самом фреймворке.

LangGraph — это проект от команды LangChain, тех самых, кто первыми предложили концепцию «цепочек» (chains) взаимодействия с LLM. Если раньше основной упор делался на линейные или условно-ветвящиеся пайплайны (langchain.chains), то теперь разработчики делают ставку на графовую модель, и именно LangGraph они рекомендуют как новое «ядро» для построения сложных ИИ-сценариев.

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

Как это работает: графы и узлы

Концептуально, LangGraph строится на следующих идеях:

• Граф — это структура, которая описывает возможные пути выполнения логики. Можно думать о нём как о карте: из одной точки можно перейти в другую в зависимости от условий или результата выполнения.

• Узлы (ноды) — это конкретные шаги внутри графа. Каждый узел выполняет какую-то функцию: вызывает модель, вызывает внешний API, проверяет условие или просто обновляет внутреннее состояние.

• Переходы между узлами — это логика маршрутизации: если результат предыдущего шага такой-то, то идём туда-то.

• Состояние (state) — передаётся между узлами и накапливает всё, что нужно: историю, промежуточные выводы, пользовательский ввод, результат работы инструментов и т.д.

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

Почему это удобно?

LangGraph позволяет строить прозрачную, воспроизводимую и расширяемую логику:

• легко отлаживать;

• легко визуализировать;

• легко масштабировать под новые задачи;

• легко интегрировать внешние инструменты и MCP-протоколы.

По сути, LangGraph — это «мозг» агента, где каждый шаг задокументирован, контролируем и может быть изменён без хаоса и «магии».

Ну а теперь — хватит теории!

Можно ещё долго рассказывать о графах, состояний, композиции логики и преимуществах LangGraph над классическими пайплайнами. Но, как показывает практика, лучше один раз увидеть в коде.

Пора перейти к практике. Дальше — пример на Python: создадим простого, но полезного ИИ-агента на базе LangGraph, который будет использовать внешние инструменты, память и принимать решения сам.

Подготовка: облачные и локальные нейросети

Для того чтобы приступить к созданию ИИ-агентов, нам в первую очередь нужен мозг — языковая модель. Здесь есть два подхода:

• использовать облачные решения, где всё готово «из коробки»;

• или поднять модель локально — для полной автономии и конфиденциальности.

Рассмотрим оба варианта.

Облачные сервисы: быстро и удобно

Самый простой путь — воспользоваться мощностями крупных провайдеров: OpenAI, Anthropic, DeepSeek, Groq, Mistral и других. Вам достаточно приобрести API-ключ и начать использовать модели через стандартные HTTP-запросы.

Где взять ключи и токены:

• OpenAI — ChatGPT и другие продукты;

• Anthropic — Claude;

• OpenRouter.ai — десятки моделей (один токен — множество моделей через OpenAI-совместимый API);

• Amvera Cloud — возможность подключить LLaMA с оплатой рублями и встроенным проксированием до OpenAI и Anthropic.

Этот путь удобен, особенно если вы:

• не хотите настраивать инфраструктуру;

• разрабатываете с упором на скорость;

• работаете с ограниченными ресурсами.

Локальные модели: полный контроль

Если вам важна приватность, работа без интернета или вы хотите строить полностью автономные агенты, то имеет смысл развернуть нейросеть локально.

Основные преимущества:

• Конфиденциальность — данные остаются у вас;

• Работа без интернета — полезно в изолированных сетях;

• Отсутствие подписок и токенов — бесплатно после настройки.

Недостатки очевидны:

• Требования к ресурсам (особенно к видеопамяти);

• Настройка может занять время;

• Некоторые модели сложно развернуть без опыта.

Тем не менее, есть инструменты, которые делают локальный запуск проще. Один из лучших на сегодня — это Ollama.

Развёртывание локальной LLM через Ollama + Docker

Мы подготовим локальный запуск модели Qwen 2.5 (qwen2.5:32b) с использованием Docker-контейнера и системы Ollama. Это позволит интегрировать нейросеть с MCP и использовать её в собственных агентах на базе LangGraph.

Если вычислительных ресурсов вашего компьютера или сервера окажется недостаточно для работы с данной версией модели, вы всегда можете выбрать менее «прожорливую» нейросеть — процесс установки и запуска останется аналогичным.

📦 Быстрая установка (сводка шагов)

1. Установите Docker + Docker Compose

2. Создайте структуру проекта:

   mkdir qwen-local && cd qwen-local

3. Создайте docker-compose.yml
   (универсальный вариант, GPU определяется автоматически)

   services:   ollama:     image: ollama/ollama:latest     container_name: ollama_qwen     ports:       - '11434:11434'     volumes:       - ./ollama_data:/root/.ollama       - /tmp:/tmp     environment:       - OLLAMA_HOST=0.0.0.0       - OLLAMA_ORIGINS=*     restart: unless-stopped 

4. Запустите контейнер:

   docker compose up -d

5. Загрузите модель:

   docker exec -it ollama_qwen ollama pull qwen2.5:32b

6. Проверьте работу через API:

   curl http://localhost:11434/api/generate \   -H "Content-Type: application/json" \   -d '{"model": "qwen2.5:32b", "prompt": "Привет!", "stream": false}' 

7. Интеграция с Python:

   import requests  def query(prompt):     res = requests.post("http://localhost:11434/api/generate", json={         "model": "qwen2.5:32b",         "prompt": prompt,         "stream": False     })     return res.json()['response']  print(query("Объясни квантовую запутанность")) 

Теперь у вас полноценная локальная LLM, готовая к работе с MCP и LangGraph.

Что дальше?

У нас есть выбор между облачными и локальными моделями, и мы научились подключать обе. Самое интересное впереди — создание ИИ-агентов на LangGraph, которые используют выбранную модель, память, инструменты и собственную логику.

Переходим к самому вкусному — коду и практике!

Подготовка к написанию кода

Перед тем как перейти к практике, важно подготовить рабочее окружение. Я предполагаю, что вы уже знакомы с основами Python, знаете, что такое библиотеки и зависимости, и понимаете, зачем использовать виртуальное окружение.

Если всё это вам в новинку — рекомендую сначала пройти короткий курс или гайд по Python-базе, а затем возвращаться к статье.

Шаг 1: Создание виртуального окружения

Создайте новое виртуальное окружение в папке проекта:

python -m venv venv source venv/bin/activate  # для Linux/macOS venv\Scripts\activate     # для Windows 

Шаг 2: Установка зависимостей

Создайте файл requirements.txt и добавьте в него следующие строки:

langchain==0.3.26 langchain-core==0.3.69 langchain-deepseek==0.1.3 langchain-mcp-adapters==0.1.9 langchain-ollama==0.3.5 langchain-openai==0.3.28 langgraph==0.5.3 langgraph-checkpoint==2.1.1 langgraph-prebuilt==0.5.2 langgraph-sdk==0.1.73 langsmith==0.4.8 mcp==1.12.0 ollama==0.5.1 openai==1.97.0

⚠️ Актуальные версии указаны на 21 июля 2025 года. С момента публикации они могли измениться — проверяйте актуальность перед установкой.

Затем установите зависимости:

pip install -r requirements.txt

Шаг 3: Конфигурация переменных окружения

Создайте в корне проекта файл .env и добавьте в него нужные API-ключи:

OPENAI_API_KEY=sk-proj-1234 DEEPSEEK_API_KEY=sk-123 OPENROUTER_API_KEY=sk-or-v1-123 BRAVE_API_KEY=BSAj123KlbvBGpH1344tLwc

Назначение переменных:

• OPENAI_API_KEY — ключ для доступа к GPT-моделям от OpenAI;

• DEEPSEEK_API_KEY — ключ для использования моделей Deepseek;

• OPENROUTER_API_KEY — единый ключ для доступа к множеству моделей через OpenRouter (можно получить бесплатно);

• BRAVE_API_KEY — API-ключ для MCP-модуля web-поиска через Brave Search (можно получить бесплатно).

Некоторые MCP-инструменты (например, brave-web-search) требуют ключ для работы. Без него они просто не активируются.

А если у вас нет API-ключей?

Не проблема. Вы можете начать разработку с локальной моделью (например, через Ollama), не подключая ни одного внешнего сервиса. В этом случае файл .env можно не создавать вовсе.

Готово! Теперь у нас есть всё необходимое для начала — изолированное окружение, зависимости, и, при необходимости, доступ к облачным нейросетям и MCP-интеграциям.

Далее — запустим нашего LLM-агента разными способами.

Простой запуск LLM-агентов через LangGraph: базовая интеграция

Начнём с самого простого: как «подключить мозг» к будущему агенту. Мы разберём базовые способы запуска языковых моделей (LLM) с помощью LangChain, чтобы в следующем шаге перейти к интеграции с LangGraph и построению полноценного ИИ-агента.

Импорты

import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_ollama import ChatOllama from langchain_deepseek import ChatDeepSeek 

• os и load_dotenv() — для загрузки переменных из .env-файла.

• ChatOpenAI, ChatOllama, ChatDeepSeek — обёртки для подключения языковых моделей через LangChain.

💡 Если вы используете альтернативные подходы к работе с конфигурациями (например, Pydantic Settings), можете заменить load_dotenv() на свой привычный способ.

Загрузка переменных окружения

load_dotenv()

Это подгрузит все переменные из .env, включая ключи для доступа к API OpenAI, DeepSeek, OpenRouter и другим.

Простые функции для получения LLM

OpenAI

def get_openai_llm():     return ChatOpenAI(model="gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")) 

Если переменная OPENAI_API_KEY корректно задана, LangChain подставит её автоматически — явное указание api_key=... здесь опционально.

DeepSeek

def get_deepseek_llm():     return ChatDeepSeek(model="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY")) 

Аналогично, но используем обёртку ChatDeepSeek.

OpenRouter (и другие совместимые API)

def get_openrouter_llm(model="moonshotai/kimi-k2:free"):     return ChatOpenAI(         model=model,         api_key=os.getenv("OPENROUTER_API_KEY"),         base_url="https://openrouter.ai/api/v1",         temperature=0     ) 

Особенности:

• ChatOpenAI используется, несмотря на то что модель не от OpenAI — потому что OpenRouter использует тот же протокол.

• base_url обязателен: он указывает на OpenRouter API.

• Модель moonshotai/kimi-k2:free выбрана как один из наиболее сбалансированных вариантов по качеству и скорости на момент написания статьи.

• API-ключ OpenRouter нужно передавать явно — автоматическая подстановка здесь не работает.

Мини-тест: проверка работы модели

if __name__ == "__main__":     llm = get_openrouter_llm(model="moonshotai/kimi-k2:free")     response = llm.invoke("Кто ты?")     print(response.content) 

Если всё настроено правильно, вы получите осмысленный ответ от модели. Поздравляю — первый шаг сделан!

Но это ещё не агент

На текущем этапе мы подключили LLM и сделали простой вызов. Это больше похоже на консольного чат-бота, чем на ИИ-агента.

Почему?

• Мы пишем синхронный, линейный код без логики состояния или целей.

• Агент не принимает решений, не запоминает контекст и не использует инструменты.

• MCP и LangGraph пока не задействованы.

Что дальше?

Далее мы реализуем полноценного ИИ-агента с использованием LangGraph — сначала без MCP, чтобы сфокусироваться на архитектуре, состояниях и логике самого агента.

Погружаемся в настоящую агентную механику. Поехали!

Агент классификации вакансий: от теории к практике

Создадим реального ИИ-агента, который будет решать конкретную бизнес-задачу — автоматическую классификацию описаний вакансий и услуг. Этот пример покажет, как применить концепции LangGraph на практике и создать полезный инструмент для HR-платформ и бирж фриланса.

Задача агента

Наш агент принимает на вход текстовое описание вакансии или услуги и выполняет трёхуровневую классификацию:

1. Тип работы: проектная работа или постоянная вакансия

2. Категория профессии: из 45+ предопределённых специальностей

3. Тип поиска: ищет ли человек работу или ищет исполнителя

Результат возвращается в структурированном JSON-формате с оценкой уверенности для каждой классификации.

🏗️ Архитектура агента на LangGraph

Следуя принципам LangGraph, создаём граф состояний из четырёх узлов:

📝 Входное описание       ↓ 🔍 Узел классификации типа работы       ↓ 📂 Узел классификации категории       ↓ 🎯 Узел определения типа поиска       ↓ 📊 Узел расчёта уверенности       ↓ ✅ JSON-результат 

Каждый узел — это специализированная функция, которая:

• Получает текущее состояние агента

• Выполняет свою часть анализа

• Обновляет состояние и передаёт его дальше

Управление состоянием

Определяем структуру памяти агента через TypedDict:

class State(TypedDict):     """Состояние агента для хранения информации о процессе классификации"""     description: str     job_type: str     category: str     search_type: str     confidence_scores: Dict[str, float]     processed: bool 

Это рабочая память агента — всё, что он помнит и накапливает в процессе анализа. Подобно тому, как человек-эксперт держит в уме контекст задачи при анализе документа.

Давайте рассмотрим полный код, а после сконцентрируемся на основных моментах.

import asyncio import json from typing import TypedDict, Dict, Any from enum import Enum from langgraph.graph import StateGraph, END from langchain.prompts import PromptTemplate from langchain_openai import ChatOpenAI from langchain.schema import HumanMessage   # Категории профессий CATEGORIES = [     "2D-аниматор", "3D-аниматор", "3D-моделлер",      "Бизнес-аналитик", "Блокчейн-разработчик", ... ]   class JobType(Enum):     PROJECT = "проектная работа"     PERMANENT = "постоянная работа"   class SearchType(Enum):     LOOKING_FOR_WORK = "поиск работы"     LOOKING_FOR_PERFORMER = "поиск исполнителя"   class State(TypedDict):     """Состояние агента для хранения информации о процессе классификации"""     description: str     job_type: str     category: str     search_type: str     confidence_scores: Dict[str, float]     processed: bool   class VacancyClassificationAgent:     """Асинхронный агент для классификации вакансий и услуг"""      def __init__(self, model_name: str = "gpt-4o-mini", temperature: float = 0.1):         """Инициализация агента"""         self.llm = ChatOpenAI(model=model_name, temperature=temperature)         self.workflow = self._create_workflow()      def _create_workflow(self) -> StateGraph:         """Создает рабочий процесс агента на основе LangGraph"""         workflow = StateGraph(State)          # Добавляем узлы в граф         workflow.add_node("job_type_classification", self._classify_job_type)         workflow.add_node("category_classification", self._classify_category)         workflow.add_node("search_type_classification", self._classify_search_type)         workflow.add_node("confidence_calculation", self._calculate_confidence)          # Определяем последовательность выполнения узлов         workflow.set_entry_point("job_type_classification")         workflow.add_edge("job_type_classification", "category_classification")         workflow.add_edge("category_classification", "search_type_classification")         workflow.add_edge("search_type_classification", "confidence_calculation")         workflow.add_edge("confidence_calculation", END)          return workflow.compile()      async def _classify_job_type(self, state: State) -> Dict[str, Any]:         """Узел для определения типа работы: проектная или постоянная"""         prompt = PromptTemplate(             input_variables=["description"],             template="""             Проанализируй следующее описание и определи тип работы.              Описание: {description}              Ответь только одним из двух вариантов:             - "проектная работа" - если это временная задача, проект, фриланс, разовая работа             - "постоянная работа" - если это постоянная должность, штатная позиция, долгосрочное трудоустройство              Тип работы:             """         )          message = HumanMessage(content=prompt.format(description=state["description"]))         response = await self.llm.ainvoke([message])         job_type = response.content.strip().lower()          # Нормализуем ответ         if "проектная" in job_type or "проект" in job_type or "фриланс" in job_type:             job_type = JobType.PROJECT.value         else:             job_type = JobType.PERMANENT.value          return {"job_type": job_type}      async def _classify_category(self, state: State) -> Dict[str, Any]:         """Узел для определения категории профессии"""         categories_str = "\n".join([f"- {cat}" for cat in CATEGORIES])          prompt = PromptTemplate(             input_variables=["description", "categories"],             template="""             Проанализируй описание вакансии/услуги и определи наиболее подходящую категорию из списка.              Описание: {description}              Доступные категории:             {categories}              Выбери ТОЧНО одну категорию из списка выше, которая лучше всего соответствует описанию.             Ответь только названием категории без дополнительных пояснений.              Категория:             """         )          message = HumanMessage(content=prompt.format(             description=state["description"],             categories=categories_str         ))         response = await self.llm.ainvoke([message])         category = response.content.strip()          # Проверяем, есть ли категория в списке доступных         if category not in CATEGORIES:             # Ищем наиболее похожую категорию             category = self._find_closest_category(category)          return {"category": category}      async def _classify_search_type(self, state: State) -> Dict[str, Any]:         """Узел для определения типа поиска"""         prompt = PromptTemplate(             input_variables=["description"],             template="""             Проанализируй описание и определи, кто и что ищет.              Описание: {description}              Ответь только одним из двух вариантов:             - "поиск работы" - если соискатель ищет работу/заказы             - "поиск исполнителя" - если работодатель/заказчик ищет исполнителя              Обрати внимание на ключевые слова:             - "ищу работу", "резюме", "хочу работать" = поиск работы             - "требуется", "ищем", "вакансия", "нужен специалист" = поиск исполнителя              Тип поиска:             """         )          message = HumanMessage(content=prompt.format(description=state["description"]))         response = await self.llm.ainvoke([message])         search_type = response.content.strip().lower()          # Нормализуем ответ         if "поиск работы" in search_type or "ищу работу" in search_type:             search_type = SearchType.LOOKING_FOR_WORK.value         else:             search_type = SearchType.LOOKING_FOR_PERFORMER.value          return {"search_type": search_type}      async def _calculate_confidence(self, state: State) -> Dict[str, Any]:         """Узел для расчета уровня уверенности в классификации"""         prompt = PromptTemplate(             input_variables=["description", "job_type", "category", "search_type"],             template="""             Оцени уверенность классификации по шкале от 0.0 до 1.0 для каждого параметра:              Описание: {description}             Тип работы: {job_type}             Категория: {category}             Тип поиска: {search_type}              Ответь в формате JSON:             {{                 "job_type_confidence": 0.0-1.0,                 "category_confidence": 0.0-1.0,                 "search_type_confidence": 0.0-1.0             }}             """         )          message = HumanMessage(content=prompt.format(             description=state["description"],             job_type=state["job_type"],             category=state["category"],             search_type=state["search_type"]         ))         response = await self.llm.ainvoke([message])          try:             confidence_scores = json.loads(response.content.strip())         except:             # Fallback значения если парсинг не удался             confidence_scores = {                 "job_type_confidence": 0.7,                 "category_confidence": 0.7,                 "search_type_confidence": 0.7             }          return {             "confidence_scores": confidence_scores,             "processed": True         }      def _find_closest_category(self, predicted_category: str) -> str:         """Находит наиболее похожую категорию из списка доступных"""         # Простая эвристика поиска по вхождению ключевых слов         predicted_lower = predicted_category.lower()          for category in CATEGORIES:             category_lower = category.lower()             if predicted_lower in category_lower or category_lower in predicted_lower:                 return category          # Если ничего не найдено, возвращаем первую категорию как fallback         return CATEGORIES[0]      async def classify(self, description: str) -> Dict[str, Any]:         """Основной метод для классификации вакансии/услуги"""         initial_state = {             "description": description,             "job_type": "",             "category": "",             "search_type": "",             "confidence_scores": {},             "processed": False         }          # Запускаем рабочий процесс         result = await self.workflow.ainvoke(initial_state)          # Формируем итоговый ответ в формате JSON         classification_result = {             "job_type": result["job_type"],             "category": result["category"],             "search_type": result["search_type"],             "confidence_scores": result["confidence_scores"],             "success": result["processed"]         }          return classification_result   async def main():     """Демонстрация работы агента"""     agent = VacancyClassificationAgent()      # Тестовые примеры     test_cases = [         "Требуется Python разработчик для создания веб-приложения на Django. Постоянная работа, полный рабочий день.",         "Ищу заказы на создание логотипов и фирменного стиля. Работаю в Adobe Illustrator.",         "Нужен 3D-аниматор для краткосрочного проекта создания рекламного ролика.",         "Резюме: опытный маркетолог, ищу удаленную работу в сфере digital-маркетинга",         "Ищем фронтенд-разработчика React в нашу команду на постоянную основе"     ]      test_cases = []     print("🤖 Демонстрация работы агента классификации вакансий\n")      for i, description in enumerate(test_cases, 1):         print(f"📋 Тест {i}:")         print(f"Описание: {description}")          try:             result = await agent.classify(description)             print("Результат классификации:")             print(json.dumps(result, ensure_ascii=False, indent=2))          except Exception as e:             print(f"❌ Ошибка: {e}")          print("-" * 80)   if __name__ == "__main__":     asyncio.run(main()) 

Асинхронная архитектура

В отличие от простых примеров, наш агент работает полностью асинхронно:

async def _classify_job_type(self, state: State) -> Dict[str, Any]:     """Узел для определения типа работы: проектная или постоянная"""     response = await self.llm.ainvoke([message])     # Обработка ответа...     return {"job_type": job_type} 

Это позволяет:

• Обрабатывать множественные запросы параллельно

• Интегрироваться с асинхронными веб-фреймворками

• Эффективно использовать ресурсы при масштабировании

Специализированные промпты для каждого узла

Каждый узел использует целевой промпт, оптимизированный под свою задачу:

For job type classification:

template=""" Проанализируй следующее описание и определи тип работы.  Описание: {description}  Ответь только одним из двух вариантов: - "проектная работа" - если это временная задача, проект, фриланс - "постоянная работа" - если это постоянная должность, штатная позиция  Тип работы: """ 

Такой подход обеспечивает высокую точность каждого этапа классификации, так как модель получает чёткие, специфичные инструкции.

Обработка ошибок и fallback-механизмы

Агент включает умную обработку неожиданных ситуаций:

def _find_closest_category(self, predicted_category: str) -> str:     """Находит наиболее похожую категорию из списка доступных"""     predicted_lower = predicted_category.lower()      for category in CATEGORIES:         category_lower = category.lower()         if predicted_lower in category_lower or category_lower in predicted_lower:             return category      # Fallback: возвращаем первую категорию     return CATEGORIES[0] 

Это делает агента устойчивым к ошибкам — даже если модель вернёт неточный результат, система найдёт наиболее подходящий вариант из допустимых.

Оценка уверенности

Финальный узел рассчитывает метрики качества классификации:

async def _calculate_confidence(self, state: State) -> Dict[str, Any]:     """Узел для расчета уровня уверенности в классификации"""     # Запрос к LLM для оценки уверенности по шкале 0.0-1.0     # Возврат структурированного JSON с метриками 

Это позволяет:

• Отслеживать качество работы агента

• Выделять случаи, требующие ручной проверки

• Оптимизировать промпты на основе статистики

Практическое применение

async def main():     agent = VacancyClassificationAgent()      description = "Требуется Python разработчик для создания веб-приложения"     result = await agent.classify(description)      print(json.dumps(result, ensure_ascii=False, indent=2)) 

Результат:

{   "job_type": "постоянная работа",   "category": "Бэкенд-разработчик (Node.js, Python, PHP, Ruby)",   "search_type": "поиск исполнителя",   "confidence_scores": {     "job_type_confidence": 0.95,     "category_confidence": 0.88,     "search_type_confidence": 0.92   },   "success": true } 

Ключевые преимущества архитектуры

1. Модульность — каждый узел решает одну задачу, легко тестировать и улучшать отдельно

2. Расширяемость — можно добавлять новые узлы анализа без изменения существующих

3. Прозрачность — весь процесс принятия решений документирован и отслеживаем

4. Производительность — асинхронная обработка множественных запросов

5. Надёжность — fallback-механизмы и обработка ошибок

Реальная польза

Такой агент может использоваться в:

• HR-платформах для автоматической категоризации резюме и вакансий

• Биржах фриланса для улучшения поиска и рекомендаций

• Внутренних системах компаний для обработки заявок и проектов

• Аналитических решениях для исследования рынка труда

MCP в действии: создаём агента с файловой системой и веб-поиском

После того как мы разобрались с базовыми принципами LangGraph и создали простого классификатора, пора перейти к настоящей магии — интеграции агента с внешним миром через MCP (Model Context Protocol).

Сейчас мы создадим полноценного ИИ-помощника, который сможет:

• Работать с файловой системой (читать, создавать, изменять файлы)

• Искать актуальную информацию в интернете

• Запоминать контекст диалога

• Обрабатывать ошибки и восстанавливаться после сбоев

От теории к реальным инструментам

Помните, как в начале статьи мы говорили о том, что MCP — это мост между нейросетью и её окружением? Сейчас вы увидите это на практике. Наш агент получит доступ к реальным инструментам:

# Инструменты файловой системы - read_file — чтение файлов - write_file — запись и создание файлов - list_directory — просмотр содержимого папок - create_directory — создание папок  # Инструменты веб-поиска - brave_web_search — поиск в интернете - get_web_content — получение содержимого страниц 

Это уже не «игрушечный» агент — это рабочий инструмент, который может решать реальные задачи.

Кода и текста уже накопилось достаточно много, поэтому далее я приведу лишь общее описание принципов и концепции разработки подобных ИИ-агентов с интеграцией MCP. Полный пример кода интеграции с MCP — как для одного сервера, так и для нескольких — вы найдете в моём бесплатном телеграм-канале «Лёгкий путь в Python». Сообщество уже насчитывает около 4000 участников, присоединяйтесь.

🏗️ Архитектура: от простого к сложному

1. Конфигурация как основа стабильности

@dataclass class AgentConfig:     """Упрощенная конфигурация AI-агента"""     filesystem_path: str = "/path/to/work/directory"     model_provider: ModelProvider = ModelProvider.OLLAMA     use_memory: bool = True     enable_web_search: bool = True      def validate(self) -> None:         """Валидация конфигурации"""         if not os.path.exists(self.filesystem_path):             raise ValueError(f"Путь не существует: {self.filesystem_path}") 

Почему это важно? В отличие от примера с классификацией, здесь агент взаимодействует с внешними системами. Одна ошибка в пути к файлам или отсутствующий API-ключ — и весь агент перестаёт работать. Валидация на старте экономит часы отладки.

2. Фабрика моделей: гибкость выбора

class ModelFactory:     """Упрощенная фабрика моделей"""      @staticmethod     def create_model(config: AgentConfig):         """Создает модель согласно конфигурации"""         provider = config.model_provider.value          if provider == "ollama":             return ChatOllama(model="qwen2.5:32b", base_url="http://localhost:11434")         elif provider == "openai":             return ChatOpenAI(model="gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))         # ... другие провайдеры 

Один код — множество моделей. Хотите бесплатную локальную модель? Используйте Ollama. Нужна максимальная точность? Переключитесь на GPT-4. Важна скорость? Попробуйте DeepSeek. Код остаётся тем же.

3. MCP-интеграция: подключение к реальному миру

async def _init_mcp_client(self):     """Инициализация MCP клиента"""     mcp_config = {         "filesystem": {             "command": "npx",             "args": ["-y", "@modelcontextprotocol/server-filesystem", self.filesystem_path],             "transport": "stdio"         },         "brave-search": {             "command": "npx",             "args": ["-y", "@modelcontextprotocol/server-brave-search@latest"],             "transport": "stdio",             "env": {"BRAVE_API_KEY": os.getenv("BRAVE_API_KEY")}         }     }      self.mcp_client = MultiServerMCPClient(mcp_config)     self.tools = await self.mcp_client.get_tools() 

Здесь происходит ключевая работа MCP: мы подключаем к агенту внешние MCP-серверы, которые предоставляют набор инструментов и функций. Агент при этом получает не просто отдельные функции, а полноценное контекстное понимание того, как работать с файловой системой и интернетом.

Для корректной работы указанных MCP-серверов потребуется установить Node.js и npm последней версии. После этого глобально установите необходимые MCP-серверы с помощью команд:

npm install -g @modelcontextprotocol/server-filesystem npm install -g @modelcontextprotocol/server-brave-search@latest

Если вы планируете использовать сервер server-brave-search, обязательно получите бесплатный API-ключ на сайте Brave и установите его в переменную окружения BRAVE_API_KEY.

Таким образом, MCP-сервера предоставляют вашему ИИ-агенту расширенные возможности через стандартизированный протокол, позволяющий интегрировать разные внешние сервисы и инструменты для работы с реальным миром.

Устойчивость к ошибкам

В реальном мире всё ломается: сеть недоступна, файлы заблокированы, API-ключи просрочены. Наш агент готов к этому:

@retry_on_failure(max_retries=2, delay=1.0) async def process_message(self, user_input: str, thread_id: str = "default") -> str:     """Обработка сообщения пользователя с повторными попытками"""     try:         config = {"configurable": {"thread_id": thread_id}}         message_input = {"messages": [HumanMessage(content=user_input)]}          response = await self.agent.ainvoke(message_input, config)         return response["messages"][-1].content      except Exception as e:         error_msg = f"❌ Ошибка обработки: {e}"         logger.error(error_msg)         return error_msg 

Декоратор @retry_on_failure автоматически повторяет операции при временных сбоях. Пользователь даже не заметит, что что-то пошло не так.

Контекстная память

if self.config.use_memory:     self.checkpointer = InMemorySaver()     logger.info("Память агента включена") 

Агент помнит всю историю разговора. Вы можете сказать «создай файл config.py«, затем «добавь в него настройки базы данных», и агент поймёт, что речь идёт о том же файле. Это кардинально меняет пользовательский опыт.

Умный системный промпт

def _get_system_prompt(self) -> str:     base_prompt = (         "Ты — умный AI-ассистент, который помогает пользователю работать с файлами "         "и искать информацию в интернете. Всегда внимательно анализируй запрос "         "и выбирай наиболее подходящий инструмент."     )      if self.config.enable_web_search:         base_prompt += (             " Если требуется найти актуальные данные (погоду, новости, цены), "             "обязательно используй веб-поиск и предоставляй самую свежую информацию."         )      return base_prompt 

Промпт адаптируется к возможностям агента. Если веб-поиск отключён, агент не будет предлагать найти что-то в интернете. Если включён — будет активно использовать эту возможность.

🚀 Практические сценарии использования

Работа с кодом:

> Создай структуру проекта Flask с папками templates, static и models ✅ Создание папок... 📁 Создал директорию /project/templates 📁 Создал директорию /project/static 📁 Создал директорию /project/models 📄 Создал базовый app.py с настройками Flask 

Актуальная информация:

> Какая сейчас погода в Москве? 🔍 Ищу актуальную информацию о погоде... 🌤️ В Москве сейчас +25°C, переменная облачность, ветер 3 м/с 

Анализ и обработка файлов:

> Прочитай все .py файлы в папке и создай документацию 📖 Читаю Python файлы... 📄 Найдено 5 файлов: app.py, models.py, views.py, utils.py, config.py 📝 Создаю документацию на основе анализа кода... ✅ Документация сохранена в README.md 

Ключевые отличия от простого чат-бота

1. Реальные действия — агент не просто говорит, что делать, а делает сам

2. Контекстная память — помнит всю историю и может ссылаться на предыдущие действия

3. Актуальные данные — может получать свежую информацию из интернета

4. Обработка ошибок — graceful degradation при проблемах с инструментами

5. Адаптивность — поведение зависит от доступных инструментов

От примера к продакшену

Этот код демонстрирует архитектурные паттерны для создания продакшн-готовых агентов:

• Модульная конфигурация — легко менять поведение без изменения кода

• Абстракция провайдеров — поддержка множества LLM из коробки

• Graceful error handling — система не падает при проблемах

• Расширяемость — новые инструменты добавляются декларативно

• Наблюдаемость — подробное логирование для отладки

Итоги: от теории к практике ИИ-агентов

Сегодня мы прошли путь от базовых концепций до создания работающих ИИ-агентов. Давайте подведём итоги того, что мы изучили и чего достигли.

Что мы освоили

1. Фундаментальные концепции

• Разобрались с различием между чат-ботами и настоящими ИИ-агентами

• Поняли роль MCP (Model Context Protocol) как моста между моделью и внешним миром

• Изучили архитектуру LangGraph для построения сложной логики агентов

2. Практические навыки

• Настроили рабочее окружение с поддержкой облачных и локальных моделей

• Создали агента-классификатора с асинхронной архитектурой и управлением состояниями

• Построили MCP-агента с доступом к файловой системе и веб-поиску

3. Архитектурные паттерны

• Научились проектировать графы состояний для сложной логики

• Освоили модульную конфигурацию и фабрики моделей

• Внедрили обработку ошибок и retry-механизмы для продакшн-готовых решений

Ключевые преимущества подхода

LangGraph + MCP дают нам:

• Прозрачность — каждый шаг агента документирован и отслеживаем

• Расширяемость — новые возможности добавляются декларативно

• Надёжность — встроенная обработка ошибок и восстановление

• Гибкость — поддержка множества моделей и провайдеров из коробки

Практическая ценность

Созданные примеры — это не просто демонстрация технологий. Это готовые решения для реальных задач:

• Агент-классификатор можно внедрить в HR-платформы и биржи фриланса

• MCP-агент подходит для автоматизации рабочих процессов и анализа данных

• Архитектурные паттерны масштабируются на проекты любой сложности

Уровень подготовки

Сегодня я намеренно не усложнял материал глубокими техническими деталями и сложной терминологией. Цель была простая — преодолеть базовый порог входа в тему интеграции ИИ-агентов с собственными проектами.

Этой информации достаточно, чтобы:

• Понять принципы работы современных ИИ-агентов

• Начать экспериментировать с собственными решениями

• Оценить потенциал технологий для ваших задач

• Сделать осознанный выбор инструментов для проекта

Что дальше?

Мы затронули лишь верхушку айсберга. LangGraph и MCP предлагают гораздо более широкие возможности:

• Мультиагентные системы — координация команд специализированных агентов

• Продвинутые MCP-серверы — интеграция с базами данных, CRM, API сервисов

• Сложные графы состояний — циклы, условные переходы, параллельное выполнение

• Production deployment — масштабирование, мониторинг, A/B тестирование

Где найти больше материалов

Полный исходный код всех примеров, а также эксклюзивные материалы, которые я не публикую на Хабре, вы найдёте в моём телеграм-канале «Легкий путь в Python».

Обратная связь важна

Если вам интересны более глубокие темы:

• LLM и ИИ-агенты в интеграции с собственными проектами

• MCP-серверы и создание кастомных инструментов

• Детальное рассмотрение LangGraph — продвинутые паттерны и оптимизации

Дайте знать своим:

• 👍 Лайком этой статьи

• 📱 Подпиской на телеграм-канал

• 💬 Комментарием с вопросами и предложениями тем

Ваша активность показывает, что тема востребована, и мотивирует создавать ещё больше качественного контента.

Заключение

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

Главное — начать. Возьмите код из примеров, адаптируйте под свои задачи, экспериментируйте. Каждый проект — это новый опыт и шаг к мастерству в области ИИ-разработки.

Удачи в ваших проектах!

---

Amvera Cloud – облако для простого запуска проектов со встроенным CI/CD (деплой идёт через Git или загрузку файлов в интерфейсе), встроенным проксированием до ведущих LLM и собственным инференсом LLaMA. Вам не нужно думать о настройке NGINX, виртуальных машин и другой инфраструктуры. Зарегистрируйтесь и получите 111 рублей на тест.