Полный гайд по созданию первого AI-агента на LangGraph

ТИЗЕР: Полный гайд по созданию первого AI-агента на LangGraph — это практическое руководство, написанное на основе неудачного опыта демонстрации ИИ-агента перед клиентом. Автор осознал, что провал произошёл из-за неверной архитектуры: запутанные связи, отсутствие чёткой логики и слабое управление состоянием. В результате он пересмотрел подход и объяснил, как правильно строить агента.

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

На примере LangGraph демонстрируется пошаговая сборка агента, анализирующего статьи с Medium: классификация текста, извлечение сущностей и создание краткого резюме. Вся логика реализуется в виде графа из узлов и связей.

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

Спустя 1 месяц разработки моего коммерческого AI-агента всё рухнуло во время клиентской демонстрации.

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

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

Этот провал изменил мой подход и стал основой того, как я теперь объясняю такие системы. Как только вы поймёте базовые принципы, создание эффективных агентов окажется неожиданно простым.

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

AI-агенты — это системы, которые:

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

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

Агенты меняют этот подход. В отличие от традиционных моделей, работающих изолированно, агент управляет различными возможностями, при этом сохраняя общее понимание всей задачи.

Агенты не просто следуют инструкциям — они адаптируются и принимают разумные решения о следующих шагах, исходя из того, что уже узнали, — так же, как это делает человек.

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

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

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

ИИ-агенты опираются на три фундаментальных принципа:

Теперь, когда вы поняли, что такое AI-агенты и почему они важны, давайте создадим одного с помощью LangGraph — фреймворка от LangChain для создания надёжных ИИ-агентов.

Что мне особенно нравится в LangGraph — он позволяет визуализировать мышление и действия агента в виде графа. Каждый узел (node) представляет собой отдельную способность (например, поиск в интернете или написание кода), а связи между узлами (edges) управляют потоком информации.

Когда я только начал разрабатывать агентов, этот подход стал для меня откровением, потому что я буквально смог "увидеть", как думает мой агент.

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

Шаг 1 — Создайте директорию проекта:

mkdir ai_agent_project
cd ai_agent_project

Шаг 2 — Создайте и активируйте виртуальное окружение:

python -m venv agent_env
agent_env\Scripts\activate

На macOS/Linux:

python3 -m venv agent_env
source agent_env/bin/activate

Шаг 3 — Установите необходимые библиотеки:

pip install langgraph langchain langchain-openai python-dotenv

Шаг 4 — Настройка OpenAI API:

Я использую GPT-4o mini в качестве "мозга" агента, но вы можете заменить его на любую другую LLM по своему выбору. Если у вас нет API-ключа:

Шаг 5 — Создайте файл .env:

echo OPENAI_API_KEY=your-api-key-here > .env

На macOS/Linux:

echo "OPENAI_API_KEY=your-api-key-here" > .env

Замените your-api-key-here на ваш фактический API-ключ.

Шаг 6 — Создайте тестовый файл test_setup.py:

import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI

Загрузить переменные окружения load_dotenv()

Инициализировать ChatOpenAI llm = ChatOpenAI(model="gpt-4o-mini")

Проверка работы модели response = llm.invoke("Hello! Are you working?") print(response.content)

Шаг 7 — Запуск теста:

python test_setup.py

Если вы получили ответ — поз��равляем! Ваша среда готова к созданию агента.

Сначала импортируем необходимые библиотеки:

import os
from typing import TypedDict, List
from langgraph.graph import StateGraph, END
from langchain.prompts import PromptTemplate
from langchain_openai import ChatOpenAI
from langchain.schema import HumanMessage

Агенту необходима память, чтобы отслеживать прогресс. Создадим её с помощью TypedDict:

from typing import TypedDict, List

class State(TypedDict): text: str # Исходный ввод текста classification: str # Результат классификации (например, тип контента) entities: List[str] # Извлечённые сущности (имена, организации, места) summary: str # Краткое резюме текста

Теперь, когда у нашего агента есть память, давайте дадим ему возможности мышления!

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

Установка temperature=0 гарантирует, что агент будет последовательно выбирать наиболее вероятный ответ — это критически важно для агентов, которые должны следовать чётким логическим шаблонам. Для напоминания: параметр temperature регулирует степень "творчества" LLM:

Если ваш агент ведёт себя странно — сначала проверьте параметр temperature!

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

1. Узел классификации текста

def classification_node(state: State): """ Классифицирует текст по одной из заданных категорий.

Параметры: state (State): текущий словарь состояния, содержащий текст

Возвращает: dict: словарь с ключом "classification" и результатом классификации

Категории: - News: фактические новости и события - Blog: личные или неформальные публикации - Research: академические или научные материалы - Other: всё, что не попадает в вышеуказанные категории """ prompt = PromptTemplate( input_variables=["text"], template="Classify the following text into one of the categories: News, Blog, Research, or Other.\n\nText: {text}\n\nCategory:" )

message = HumanMessage(content=prompt.format(text=state["text"])) classification = llm.invoke([message]).content.strip() return {"classification": classification}

Что делает функция: Она использует шаблон запроса, чётко формулируя инструкцию для модели. Функция принимает текущее состояние (с текстом) и возвращает результат классификации.

2. Узел извлечения сущностей (Entity Extraction)

def entity_extraction_node(state: State): """ Выделяет именованные сущности из текста: - Люди (Person) - Организации (Organization) - Локации (Location) """

prompt = PromptTemplate( input_variables=["text"], template="Extract all the entities (Person, Organization, Location) from the following text. Provide the result as a comma-separated list.\n\nText: {text}\n\nEntities:" )

message = HumanMessage(content=prompt.format(text=state["text"])) entities = llm.invoke([message]).content.strip().split(", ") return {"entities": entities}

Что делает функция: Обрабатывает документ и возвращает список ключевых сущностей — имена, организации, географические объекты. Всё это форматируется в виде списка и добавляется в память агента.

def summarize_node(state: State):
# Создаём шаблон для запроса на резюмирование
# Модель должна резюмировать текст в одном предложении
summarization_prompt = PromptTemplate.from_template(
"""Summarize the following text in one short sentence.
Text: {text}
Summary:"""
)
# Создаём цепочку: передаём шаблон модели
chain = summarization_prompt | llm
# Запускаем цепочку с текстом из состояния
response = chain.invoke({"text": state["text"]})
# Возвращаем результат в виде словаря
return {"summary": response.content}

Эта функция сжимает документ до краткого, ёмкого резюме его ключевых мыслей.

Теперь мы объединим все возможности в единую координированную схему:

workflow = StateGraph(State)

Добавим узлы workflow.add_node("classification_node", classification_node) workflow.add_node("entity_extraction", entity_extraction_node) workflow.add_node("summarization", summarize_node)

Установим связи между узлами workflow.set_entry_point("classification_node") # Стартовая точка workflow.add_edge("classification_node", "entity_extraction") workflow.add_edge("entity_extraction", "summarization") workflow.add_edge("summarization", END)

Компилируем граф app = workflow.compile()

Поздравляю! Вы создали агента, который проходит через три этапа: классификация → извлечение сущностей → резюмирование, что позволяет ему понимать тип текста, выделять ключевую информацию и формировать лаконичное резюме.

Проверим работу агента на примере текста:

sample_text = """ Anthropic's MCP (Model Context Protocol) is an open-source powerhouse that lets your applications interact effortlessly with APIs across various systems. """

state_input = {"text": sample_text} result = app.invoke(state_input)

print("Classification:", result["classification"]) print("\nEntities:", result["entities"]) print("\nSummary:", result["summary"])

Результат работы агента:

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

Подобный агент можно адаптировать под множество задач:

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

Второе ограничение — контекстуальное понимание. Агент может обрабатывать текст, но не обладает широкими знаниями и культурными нюансами, которые человек улавливает интуитивно. Он работает строго в рамках предоставленного текста, хотя подключение к интернет-поиску может частично компенсировать этот недостаток.

Проблема "чёрного ящика" также сохраняется в агентных системах: мы видим входные и выходные данные, но не понимаем, что происходит внутри. Некоторые модели рассуждения, такие как GPT-o1 или DeepSeek R1, предлагают большую прозрачность, демонстрируя свои рассуждения, но даже с ними невозможно полностью контролировать внутренние процессы.

И, наконец, такие системы не являются полностью автономными — им требуется человеческий контроль, особенно для проверки выводов и качества работы. Как и в других AI-системах, лучшие результаты достигаются в связке "ИИ + человек".

Осознание этих ограничений помогает создавать более устойчивые системы и точно понимать, в каких моментах необходим человек.

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

Приняв, что агенты:

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

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

Каталог архитектурных шаблонов для типовых AI-агентов на базе LangGraph

Каждый агент описан по единой структуре: 📌 Назначение | 🧩 Узлы | 🔁 Логика переходов | 📦 Состояния (State) | 🛠 Возможные инструменты

📌 Назначение: анализировать статьи, отчёты, посты; извлекать ключевые идеи, термины, инсайты.

🧩 Узлы:

🔁 Переходы: classification → entities → summary → insights → END

📦 Состояние:

class State(TypedDict):
text: str
classification: str
entities: List[str]
summary: str
insights: List[str]

🛠 Инструменты: LangChain + GPT-4o, опционально SerpAPI / DocQA

📌 Назначение: автоматическое создание отчётов на основе входных данных (таблиц, метрик, событий)

🧩 Узлы:

🔁 Переходы: parse → analyze → generate_comments → assemble → END

📦 Состояние:

class State(TypedDict):
raw_data: str
trends: Dict
commentary: str
final_report: str

🛠 Инструменты: Pandas, LangChain Expression Language, GPT-4o, визуализация через Plotly/Matplotlib

📌 Назначение: отвечать на обращения клиентов по базе знаний, быстро и точно

🧩 Узлы:

🔁 Переходы: intent → retrieve → answer → ask_feedback → END

📦 Состояние:

class State(TypedDict):
question: str
intent: str
retrieved_docs: List[str]
answer: str
feedback: Optional[str]

🛠 Инструменты: FAISS / Weaviate + LangChain, GPT-3.5/4o

📌 Назначение: сбор и структурирование информации о конкурентах

🧩 Узлы:

🔁 Переходы: search → summarize → swot → insight → END

📦 Состояние:

class State(TypedDict):
query: str
search_results: List[str]
summary: str
swot: Dict
insights: List[str]

🛠 Инструменты: SerpAPI, LangChain, SWOT-паттерн

📌 Назначение: давать доступ к внутренним политикам, инструкциям, процессам

🧩 Узлы:

🔁 Переходы: classify → retrieve → answer → reference → END

📦 Состояние:

class State(TypedDict):
query: str
category: str
documents: List[str]
answer: str
references: List[str]

🛠 Инструменты: PDF loader, ChromaDB, GPT-4, OpenRouter

Мини-гайд по проверке агента перед боевым запуском (v1.0)

Для каждого проекта ввести версирование агента (например, v1.0 → v1.1), и сопровождать его чек-листом валидации на GitHub или в Notion/Wiki.

@abashinpro