Полное руководство (с кодом) AI агента с использованием LangGraph

Всем привет!
Меня зовут Александр, я COO в SaaS-платформе для аналитики данных. Последний год активно изучаю AI-решения, с фокусом на реальные внедрения в процессах.
В своих переводах делюсь материалами, которые помогают:

• Продуктовым менеджерам — интегрировать AI без перегрузки команд;

• Разработчикам — выбирать инструменты под конкретные бизнес-задачи;

• Специалистам по данным — избегать ошибок в production-развертывании.

Сегодняшний перевод — Your First AI Agent: Simpler Than You Think
Статья демонстрирует пошаговый процесс создания AI агента для анализа текста с использованием LangGraph. Автор показывает, как координировать различные возможности AI, поддерживая целостное понимание задачи через управление состоянием, принятие решений и эффективное использование инструментов.

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

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

Начнем с небольшого введения

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

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

ИИ-агенты

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

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

Чем отличается ИИ-агент?

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

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

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

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

Архитектура интеллекта

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

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

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

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

Понимание LangGraph, фреймворка для рабочих процессов ИИ-агентов

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

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

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

Создание нашего первого агента: система анализа текста

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

Вы можете найти весь код в моем GitHub репозитории (6K), вместе с 42 другими руководствами по созданию различных ИИ-агентов, классифицированных по уровню сложности и типу варианта использования:

ССЫЛКА НА РЕПОЗИТОРИЙ

Настройка нашего окружения

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

1. Создание виртуального окружения. Сначала откройте терминал и создайте новую директорию для этого проекта:

bash

mkdir ai_agent_project 
cd ai_agent_project

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

bash

# Windows 
python -m venv agent_env 
agent_envScriptsactivate 
# macOS/Linux
python3 -m venv agent_env 
source agent_env/bin/activate

2. Установка необходимых пакетов. С активированным виртуальным окружением установите необходимые пакеты:

bash

pip install langgraph langchain langchain-openai python-dotenv

3. Настройка API-ключа OpenAI. Вам понадобится API-ключ OpenAI для использования их моделей. Вот как его получить:

• Перейдите на https://platform.openai.com/signup

• Создайте аккаунт или войдите

• Перейдите в раздел API Keys

• Нажмите “Create new secret key”

• Скопируйте ваш API-ключ

Теперь создайте файл .env в директории вашего проекта:

bash

# Windows
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-ключом OpenAI.

4. Создание тестового файла. Давайте убедимся, что всё работает. Создайте файл с названием test_setup.py:

python

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
# Load environment variables
load_dotenv() 
# Initialize the ChatOpenAI instance 
llm = ChatOpenAI(model="gpt-4o-mini") 
# Test the setup 
response = llm.invoke("Hello! Are you working?") 
print(response.content)

Запустите его, чтобы проверить вашу настройку:

bash

python test_setup.py

Если вы видите ответ, поздравляю! Ваше окружение готово к работе.

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

python

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

Каждый из этих импортов играет важную роль в функциональности нашего агента. Класс StateGraph предоставит основу для структуры нашего агента, в то время как PromptTemplate и ChatOpenAI дают нам инструменты для эффективного взаимодействия с ИИ-моделями.

Проектирование памяти нашего агента

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

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

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

python

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

Затем мы инициализируем llm, который хотим использовать (в данном случае “gpt-4o-mini”, но вы можете использовать любой llm, который захотите. Если вы работаете с Openai API, вам нужно будет создать приватный токен на их сайте, который позволит вам его использовать) с temperature = 0. Temperature = 0 в LLMs означает, что модель всегда будет выбирать наиболее вероятный/правдоподобный токен на каждом шаге, делая выходные данные детерминированными и последовательными. Это приводит к более сфокусированным и точным ответам, но потенциально менее креативным по сравнению с настройками более высокой температуры, которые вводят больше случайности в выбор токенов.

Создание основных возможностей нашего агента

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

Сначала давайте создадим нашу возможность классификации:

python

def classification_node(state: State):
    ''' Classify the text into one of the categories: News, Blog, Research, or Other '''
    prompt = PromptTemplate(
        input_variables=["text"],
        template="Classify the following text into one of the categories: News, Blog, Research, or Other.nnText:{text}nnCategory:"
    )
    message = HumanMessage(content=prompt.format(text=state["text"]))
    classification = llm.invoke([message]).content.strip()
    return {"classification": classification}

Эта функция действует как опытный библиотекарь, который может быстро определить, с каким типом документа они имеют дело. Обратите внимание, как мы используем шаблон запроса, чтобы дать четкие, последовательные инструкции нашей ИИ-модели. Функция принимает наше текущее состояние (которое включает текст, который мы анализируем) и возвращает его классификацию.

Затем мы создаем нашу возможность извлечения сущностей:

python

def entity_extraction_node(state: State):
    ''' Extract all the entities (Person, Organization, Location) from the text      '''
    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.nnText:{text}nnEntities:"
    )
    message = HumanMessage(content=prompt.format(text=state["text"]))
    entities = llm.invoke([message]).content.strip().split(", ")
    return {"entities": entities}

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

Наконец, мы реализуем нашу возможность обобщения:

def summarization_node(state: State):
    ''' Summarize the text in one short sentence '''
    prompt = PromptTemplate(
        input_variables=["text"],
        template="Summarize the following text in one short sentence.nnText:{text}nnSummary:"
    )
    message = HumanMessage(content=prompt.format(text=state["text"]))
    summary = llm.invoke([message]).content.strip()
    return {"summary": summary}

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

Объединение всего

Теперь наступает самая увлекательная часть – соединение этих возможностей в координированную систему:

python

workflow = StateGraph(State)

# Add nodes to the graph
workflow.add_node("classification_node", classification_node)
workflow.add_node("entity_extraction", entity_extraction_node)
workflow.add_node("summarization", summarization_node)

# Add edges to the graph
workflow.set_entry_point("classification_node") # Set the entry point of the graph
workflow.add_edge("classification_node", "entity_extraction")
workflow.add_edge("entity_extraction", "summarization")
workflow.add_edge("summarization", END)

# Compile the graph
app = workflow.compile()

Поздравляем, мы только что создали агента!

Напоминание о том, как он выглядит:

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

Структура, которую мы создали, говорит нашему агенту:

1. Начать с понимания, с каким типом текста он имеет дело

2. Затем определить важные сущности в этом тексте

3. Наконец, создать резюме, которое отражает основные моменты

4. Завершить процесс, как только резюме будет готово

Наблюдение за работой нашего агента

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

python

sample_text = """
OpenAI has announced the GPT-4 model, which is a large multimodal model that exhibits human-level performance on various professional benchmarks. It is developed to improve the alignment and safety of AI systems.
additionally, the model is designed to be more efficient and scalable than its predecessor, GPT-3. The GPT-4 model is expected to be released in the coming months and will be available to the public for research and development purposes.
"""

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

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

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

Classification: News

Entities: ['OpenAI', 'GPT-4', 'GPT-3']

Summary: OpenAI's upcoming GPT-4 model is a multimodal AI that aims for human-level performance, improved safety, and greater efficiency compared to GPT-3.

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

Во-первых, наш узел классификации правильно определил это как новостную статью. Это имеет смысл, учитывая формат объявления и фокус на текущих разработках. Агент распознал особенности новостного стиля – своевременную информацию, фактическое представление и фокус на конкретном развитии.

Затем возможность извлечения сущностей определила ключевых игроков в этой истории: OpenAI как организацию, и GPT-4 и GPT-3 как ключевые технические сущности, о которых идет речь. Заметьте, как она сосредоточилась на наиболее релевантных сущностях, отфильтровав менее важные детали, чтобы дать нам четкую картину того, о ком и о чем говорится в этом тексте.

Наконец, возможность обобщения объединила все это понимание для создания краткого, но всеобъемлющего резюме. Резюме отражает основные моменты – объявление о GPT-4, его ключевые улучшения по сравнению с GPT-3 и его значимость. Это не просто случайный набор предложений; это интеллектуальная дистилляция наиболее важной информации.

Понимание силы координированной обработки

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

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

Практические применения и инсайты

Пример, который мы создали, демонстрирует фундаментальный шаблон, который может быть применен к многим сценариям. В то время как мы использовали его для анализа новостной статьи об ИИ, та же структура может быть адаптирована для анализа:

Медицинских исследовательских статей, где понимание типа исследования, ключевых медицинских терминов и основных выводов имеет решающее значение

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

Финансовых отчетов, где понимание типа отчета, ключевых метрик и основных выводов определяет принятие решений

Понимание ограничений нашего агента

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

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

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

Агент также сталкивается с общей проблемой систем ИИ – проблемой “черного ящика”. В то время как мы можем наблюдать конечные выходные данные из каждого узла, у нас нет полной видимости того, как агент приходит к своим выводам. Это затрудняет отладку проблем или понимание, почему агент может иногда производить неожиданные результаты. (исключением здесь является использование моделей рассуждения, таких как GPT-o1 или DeepSeek R1, которые показывают вам, как они думают, но вы все равно не можете этим управлять)

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

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