Собираем AI-агента нового поколения: Python, RAG и внешние инструменты через MCP (Model Context Protocol)

Введение: от простых цепочек к агентам, которые действуют

Ещё пару лет назад типичное LLM-приложение выглядело как последовательная цепочка вызовов: взяли промпт, добавили контекст из векторной базы, отправили в модель, получили ответ. LangChain популяризировал эту парадигму — chains, retrievers, memory — и это работало для простых сценариев вроде «ответь на вопрос по документации».
Но бизнес-задачи редко укладываются в линейный пайплайн. Пользователь хочет не просто получить ответ, а чтобы система совершила действие: создала тикет в Jira, отправила письмо, запросила данные из CRM, проверила погоду и только потом сформулировала ответ. Именно здесь на сцену выходят AI-агенты — системы, которые не просто генерируют текст, а автономно принимают решение, какой инструмент вызвать, в каком порядке, и интерпретируют результат. Проблема в том, что до недавнего времени подключение каждого нового инструмента требовало написания «клея» — кастомных функций, обёрнутых в @tool декоратор LangChain, с ручным управлением аутентификацией, обработкой ошибок и сериализацией данных. Для продакшена это быстро превращалось в зоопарк нестандартных интеграций, который сложно поддерживать и масштабировать.
Model Context Protocol (MCP) от Anthropic решает эту проблему, предлагая единый стандарт для подключения инструментов и источников данных к LLM-приложениям. Вместо того чтобы для каждого API писать свой адаптер, мы просто запускаем MCP-сервер, который предоставляет инструменты по стандартизированному протоколу. Агент подключается к этому серверу через MCP-клиент и получает доступ ко всем инструментам без лишнего кода.
В этой статье мы соберём полноценного агента, который:
1. Умеет работать с внешним миром через MCP (узнавать погоду и создавать GitHub Issues);
2. Имеет доступ к внутренней базе знаний через RAG;
3. Принимает решения по ReAct-подходу с использованием LangGraph.

Теоретический минимум: что нужно знать перед погружением в код

AI-агент и ReAct-подход

В контексте LLM агент — это система, которая работает в цикле: Мысль → Действие → Наблюдение. Этот паттерн называется ReAct (Reasoning + Acting).
1. Агент получает задачу от пользователя.
2. Модель анализирует («думает»), какой инструмент нужно вызвать и с какими параметрами.
3. Агент вызывает инструмент и получает результат («наблюдение»).
4. Цикл повторяется, пока модель не решит, что информации достаточно для финального ответа.

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

RAG (Retrieval-Augmented Generation)

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

Model Context Protocol (MCP)

MCP — это открытый протокол, построенный поверх JSON-RPC, который стандартизирует взаимодействие между AI-приложениями и внешними источниками данных и инструментами. Архитектура включает три ключевых компонента:
1. MCP Host — AI-приложение (например, Claude Desktop или наш Python-агент).
2. MCP Client — компонент внутри хоста, который поддерживает соединение с одним MCP-сервером.
3. MCP Server — программа, которая предоставляет инструменты, ресурсы и промпты по стандартизированному протоколу.
Проще говоря: MCP делает для AI-агентов то же, что REST API сделал для веб-сервисов — универсальный способ взаимодействия, не зависящий от конкретной реализации.

Обзор стека: что и почему мы будем использовать

Практическая часть: пишем код

Часть 1. Создание MCP-сервера для работы с внешним миром

Начнём с создания MCP-сервера, который предоставит агенту два инструмента: получение погоды и создание GitHub Issue.
Установим FastMCP:

pip install fastmcp httpx

Создадим файл tools_server.py:

# tools_server.pyimport osimport httpxfrom fastmcp import FastMCP# Инициализируем MCP-сервер с именем "ExternalTools"mcp = FastMCP("ExternalTools")# ========== Инструмент 1: Получение погоды ==========@mcp.tool()async def get_weather(city: str) -> str:    """    Получает текущую погоду для указанного города.        Args:        city: Название города (например, "Moscow" или "London")        Returns:        Строка с описанием погоды    """    # Используем бесплатный Open-Meteo API (не требует ключа)    # Сначала получаем координаты города через geocoding API    async with httpx.AsyncClient() as client:        geo_response = await client.get(            "https://geocoding-api.open-meteo.com/v1/search",            params={"name": city, "count": 1, "language": "en", "format": "json"},            timeout=10.0        )        geo_response.raise_for_status()        geo_data = geo_response.json()                if not geo_data.get("results"):            return f"Город '{city}' не найден"                location = geo_data["results"][0]        lat, lon = location["latitude"], location["longitude"]        city_name = location["name"]                # Получаем погоду по координатам        weather_response = await client.get(            "https://api.open-meteo.com/v1/forecast",            params={                "latitude": lat,                "longitude": lon,                "current_weather": True,                "timezone": "auto"            },            timeout=10.0        )        weather_response.raise_for_status()        weather_data = weather_response.json()                current = weather_data["current_weather"]        return (            f"Погода в {city_name}:\n"            f"Температура: {current['temperature']}°C\n"            f"Скорость ветра: {current['windspeed']} км/ч\n"            f"Код погоды: {current['weathercode']}"        )# ========== Инструмент 2: Создание GitHub Issue ==========@mcp.tool()async def create_github_issue(    repo: str,    title: str,    body: str,    labels: list[str] | None = None) -> str:    """    Создаёт новый Issue в указанном GitHub-репозитории.        Args:        repo: Полное имя репозитория (например, "username/repo-name")        title: Заголовок Issue        body: Текст Issue (поддерживает Markdown)        labels: Список меток (опционально)        Returns:        Строка с результатом операции    """    github_token = os.environ.get("GITHUB_TOKEN")    if not github_token:        return "Ошибка: переменная окружения GITHUB_TOKEN не установлена"        url = f"https://api.github.com/repos/{repo}/issues"    headers = {        "Authorization": f"Bearer {github_token}",        "Accept": "application/vnd.github+json",        "X-GitHub-Api-Version": "2022-11-28"    }    payload = {"title": title, "body": body}    if labels:        payload["labels"] = labels        async with httpx.AsyncClient() as client:        response = await client.post(            url,            json=payload,            headers=headers,            timeout=30.0        )                if response.status_code == 201:            data = response.json()            return f"Issue успешно создан: {data['html_url']}"        elif response.status_code == 404:            return f"Ошибка: репозиторий '{repo}' не найден или нет доступа"        else:            return f"Ошибка GitHub API: {response.status_code} - {response.text}"if __name__ == "__main__":    # Запускаем сервер с транспортом stdio (стандартный ввод/вывод)    # Это позволяет клиенту запускать сервер как подпроцесс    mcp.run(transport="stdio")

Что здесь происходит:
1. Мы создаём экземпляр FastMCP и декорируем функции @mcp.tool() — FastMCP автоматически генерирует JSON-схему для параметров на основе сигнатуры функции и docstring.
2.get_weather использует бесплатный Open-Meteo API (не требует API-ключа).
3.create_github_issue требует токен GitHub с правами на создание issues (создайте его в настройках GitHub с scope repo).
4. Сервер запускается с транспортом stdio — это значит, что клиент будет запускать этот скрипт как подпроцесс и общаться с ним через стандартный ввод/вывод по протоколу JSON-RPC.
Запуск сервера (локально, для теста):

export GITHUB_TOKEN="your_github_personal_access_token"python tools_server.py

Для проверки можно использовать MCP Inspector, но мы сразу перейдём к интеграции с агентом.

Часть 2. Настройка RAG-модуля

Теперь создадим RAG-систему, которая будет индексировать PDF-документацию и предоставлять агенту инструмент для поиска.
Установим зависимости:

pip install langchain langchain-openai chromadb pypdf

Создадим файл rag_tool.py:

# rag_tool.pyimport osfrom pathlib import Pathfrom langchain_openai import OpenAIEmbeddingsfrom langchain_community.document_loaders import PyPDFLoaderfrom langchain_text_splitters import RecursiveCharacterTextSplitterfrom langchain_community.vectorstores import Chromafrom langchain.tools import tool# Путь для хранения векторной базыCHROMA_PATH = "./chroma_db"DATA_PATH = "./data"  # Папка с PDF-файламиdef initialize_vector_store(force_reload: bool = False) -> Chroma:    """    Инициализирует или загружает векторное хранилище ChromaDB.        Args:        force_reload: Если True, пересоздаёт базу заново из PDF-файлов        Returns:        Инстанс Chroma с загруженными документами    """    embeddings = OpenAIEmbeddings(model="text-embedding-3-small")        # Если база уже существует и не требуется перезагрузка — просто загружаем    if os.path.exists(CHROMA_PATH) and not force_reload:        return Chroma(            persist_directory=CHROMA_PATH,            embedding_function=embeddings        )        # Иначе — создаём новую базу из PDF-файлов    documents = []    data_folder = Path(DATA_PATH)        if not data_folder.exists():        data_folder.mkdir(parents=True)        print(f"Создана папка {DATA_PATH}. Поместите туда PDF-файлы и запустите снова.")        # Возвращаем пустую базу        return Chroma(            persist_directory=CHROMA_PATH,            embedding_function=embeddings        )        for pdf_file in data_folder.glob("*.pdf"):        loader = PyPDFLoader(str(pdf_file))        documents.extend(loader.load())        if not documents:        print(f"В папке {DATA_PATH} нет PDF-файлов")        return Chroma(            persist_directory=CHROMA_PATH,            embedding_function=embeddings        )        # Разбиваем документы на чанки    text_splitter = RecursiveCharacterTextSplitter(        chunk_size=1000,        chunk_overlap=200,        separators=["\n\n", "\n", ". ", " ", ""]    )    chunks = text_splitter.split_documents(documents)        # Создаём и сохраняем векторную базу    vector_store = Chroma.from_documents(        documents=chunks,        embedding=embeddings,        persist_directory=CHROMA_PATH    )    # В новых версиях Chroma persist() вызывать не нужно — from_documents уже сохраняет    print(f"Векторная база создана: {len(chunks)} чанков из {len(documents)} документов")        return vector_store# Глобальный экземпляр векторного хранилища_vector_store: Chroma | None = Nonedef get_vector_store() -> Chroma:    """Ленивая инициализация векторного хранилища."""    global _vector_store    if _vector_store is None:        _vector_store = initialize_vector_store()    return _vector_store@toolasync def search_documentation(query: str) -> str:    """    Ищет информацию во внутренней документации (базе знаний).    Используй этот инструмент, когда нужно ответить на вопрос, требующий    обращения к документации компании или техническим спецификациям.        Args:        query: Поисковый запрос на естественном языке        Returns:        Релевантные фрагменты из документации    """    vector_store = get_vector_store()        # Выполняем семантический поиск    docs = vector_store.similarity_search(query, k=3)        if not docs:        return "В документации не найдено информации по вашему запросу."        # Формируем ответ из найденных фрагментов    results = []    for i, doc in enumerate(docs, 1):        source = doc.metadata.get("source", "неизвестный источник")        results.append(f"[Фрагмент {i} из {source}]\n{doc.page_content}\n")        return "\n".join(results)# Функция для первоначальной загрузки документов (вызывается один раз при настройке)def setup_rag():    """Инициализирует RAG-систему, загружая все PDF из папки data/"""    print("Инициализация RAG-системы...")    store = initialize_vector_store(force_reload=True)    print(f"Готово. В базе {store._collection.count()} документов.")

Ключевые моменты:
1. Мы используем PyPDFLoader для загрузки PDF и RecursiveCharacterTextSplitter для разбивки на чанки с перекрытием.
2. Векторное хранилище сохраняется на диск в папке chroma_db/ — при повторных запусках не нужно переиндексировать документы.
3. Инструмент search_documentation обёрнут в декоратор @tool из LangChain — это делает его совместимым с LangGraph-агентом.
4. Важно: docstring инструмента — это часть промпта для модели. Чем точнее описано, когда и зачем использовать инструмент, тем лучше агент будет принимать решения.

Часть 3. Сборка агента с доступом к MCP

Теперь соберём всё вместе: агент на LangGraph, который использует и MCP-инструменты, и RAG. Установим оставшиеся зависимости:

pip install langchain-mcp-adapters langgraph langchain-anthropic

Создадим файл agent.py:

# agent.pyimport asyncioimport osfrom pathlib import Pathfrom langchain_anthropic import ChatAnthropicfrom langchain_mcp_adapters.client import MultiServerMCPClientfrom langgraph.prebuilt import create_react_agent# Импортируем наш RAG-инструментfrom rag_tool import search_documentation, setup_ragasync def main():    # ========== 1. Инициализация RAG ==========    print("Загрузка RAG-системы...")    setup_rag()  # Индексирует PDF при первом запуске        # ========== 2. Подключение к MCP-серверу ==========    # MultiServerMCPClient управляет подключениями к нескольким MCP-серверам    # В нашем случае сервер один, но архитектура позволяет легко добавлять новые    mcp_client = MultiServerMCPClient(        {            "external_tools": {                "transport": "stdio",  # Сервер запускается как подпроцесс                "command": "python",                # Указываем абсолютный путь к нашему серверу                "args": [str(Path(__file__).parent / "tools_server.py")],                # Передаём переменные окружения в подпроцесс                "env": {                    **os.environ,                    # Убеждаемся, что токен GitHub передаётся                }            }        }    )        # ========== 3. Получение инструментов ==========    # Получаем инструменты из MCP-сервера    mcp_tools = await mcp_client.get_tools()    print(f"Загружено MCP-инструментов: {len(mcp_tools)}")    for tool in mcp_tools:        print(f"  - {tool.name}: {tool.description[:50]}...")        # Объединяем MCP-инструменты с нашим RAG-инструментом    all_tools = mcp_tools + [search_documentation]    print(f"Всего инструментов: {len(all_tools)}")        # ========== 4. Создание агента ==========    # Используем Claude Sonnet 4 — у него отличная поддержка function calling    llm = ChatAnthropic(        model="claude-sonnet-4-6",        temperature=0,        max_tokens=4096    )    # Для использования OpenAI можно раскомментировать:    # from langchain_openai import ChatOpenAI    # llm = ChatOpenAI(model="gpt-4.1", temperature=0)        # create_react_agent из LangGraph создаёт готовый ReAct-агент    # Под капотом — граф с узлами: agent (вызов LLM) -> tools (выполнение) -> agent    agent = create_react_agent(        model=llm,        tools=all_tools,        # Опционально: можно передать system prompt с дополнительными инструкциями        # prompt=...    )        # ========== 5. Запуск агента ==========    print("\n" + "="*50)    print("Агент готов к работе!")    print("Примеры запросов:")    print("  1. Узнай погоду в Москве и создай тикет в GitHub")    print("  2. Поищи в документации, как настроить MCP сервер")    print("  3. Создай issue о баге в репозитории username/repo")    print("Введите 'exit' для выхода")    print("="*50 + "\n")        while True:        user_input = input("\n Ваш запрос: ")        if user_input.lower() in ("exit", "quit", "выход"):            break                # Запускаем агента с историей сообщений        # LangGraph автоматически управляет состоянием разговора        result = await agent.ainvoke(            {"messages": [{"role": "user", "content": user_input}]}        )                # Извлекаем последнее сообщение от агента        messages = result.get("messages", [])        if messages:            last_message = messages[-1]            print(f"\n Ответ: {last_message.content}")        else:            print("\n Агент не вернул ответа")if __name__ == "__main__":    asyncio.run(main())

Разбор ключевых моментов:
1. MultiServerMCPClient — центральный компонент для подключения к MCP-серверам. Он принимает конфигурацию, в которой для каждого сервера указывается транспорт (stdio или http) и параметры подключения.
2. Транспорт stdio означает, что клиент запускает Python-скрипт как подпроцесс и общается с ним через стандартный ввод/вывод. Это удобно для локальной разработки. Для продакшена можно использовать HTTP-транспорт, запустив сервер отдельно.
3.create_react_agent из LangGraph — это готовая реализация ReAct-агента. Под капотом создаётся граф с двумя узлами:
1. Agent Node: вызывает LLM с текущим состоянием и инструментами.
2. Tools Node: выполняет выбранные инструменты и возвращает результат.
4. Агент работает асинхронно (async/await), что важно для эффективной работы с внешними API.

Часть 4. Демонстрация работы

Поместим в папку data/ PDF-файл с документацией (например, руководство по работе с GitHub API или внутренний регламент создания тикетов) и запустим агента:

export ANTHROPIC_API_KEY="your_anthropic_api_key"export GITHUB_TOKEN="your_github_token"export OPENAI_API_KEY="your_openai_api_key"  # для эмбеддинговpython agent.py

Ваш запрос: Узнай погоду в Москве и создай тикет в репозитории myorg/docs с отчётом о погоде. Перед этим проверь в документации, как правильно оформлять такие тикеты.

[AGENT LOG] Thought: Мне нужно выполнить три действия:

1. Проверить документацию по оформлению тикетов

2. Узнать погоду в Москве

3. Создать тикет в GitHub с отчётом

Action: search_documentation Action Input: {“query”: “как оформлять тикеты о погоде”} Observation: [Фрагмент 1 из docs/internal-guide.pdf] Все отчёты о погоде должны содержать:

• Город и дату

• Температуру и скорость ветра

• Рекомендации на основе погодных условий…

Thought: Теперь я знаю формат. Получу погоду в Москве.

Action: get_weather Action Input: {“city”: “Moscow”} Observation: Погода в Moscow: Температура: 18.5°C Скорость ветра: 12 км/ч…

Thought: Теперь создам тикет с отчётом.

Action: create_github_issue Action Input: { “repo”: “myorg/docs”, “title”: “Ежедневный отчёт о погоде в Москве”, “body”: “## Погода в Москве\n- Температура: 18.5°C\n- Ветер: 12 км/ч\n- Рекомендации: комфортная погода для прогулок”, “labels”: [“weather-report”, “automated”] } Observation: Issue успешно создан.

Ответ: Я выполнил все запрошенные действия:

1. Проверил документацию по оформлению тикетов — все отчёты должны включать температуру, ветер и рекомендации.

2. Узнал текущую погоду в Москве: 18.5°C, ветер 12 км/ч.

3. Создал тикет в репозитории myorg/docs.

Что произошло:
1. Агент самостоятельно спланировал последовательность действий.
2. Вызвал RAG-инструмент для получения правил оформления.
3. Вызвал MCP-инструмент для получения погоды.
4. Вызвал ещё один MCP-инструмент для создания Issue.
5. Синтезировал финальный ответ.

Сравнение с альтернативами и выводы

Плюсы MCP

1. Масштабируемость: Экосистема MCP-серверов растёт — уже есть готовые серверы для GitHub, Slack, Google Drive, PostgreSQL и десятков других систем.

2. Разделение ответственности: Команда, отвечающая за интеграцию с внешними сервисами, может разрабатывать и поддерживать MCP-серверы независимо от команды, строящей агентов.

3. Единый стандарт: MCP поддерживается Anthropic, OpenAI (через Agents SDK) и другими крупными игроками-.

Минусы MCP

1. Дополнительная прослойка: Для простых прототипов запуск отдельного MCP-сервера может быть избыточным.

2. Молодость протокола: Спецификация всё ещё эволюционирует, могут быть breaking changes.

3. Отладка: Отлаживать взаимодействие через JSON-RPC сложнее, чем просто вызвать Python-функцию (хотя MCP Inspector частично решает эту проблему).

Заключение

Model Context Protocol — это не просто очередной фреймворк, а стандарт взаимодействия, который меняет подход к построению AI-агентов. Вместо того чтобы каждый раз изобретать велосипед для интеграции с очередным API, мы можем использовать готовые MCP-серверы или быстро создавать свои с помощью FastMCP.

В этой статье мы построили агента, который:

• Использует внешние инструменты через стандартизированный MCP-протокол;

• Имеет доступ к внутренней базе знаний через RAG;

• Принимает решения автономно, следуя ReAct-паттерну.

Это архитектура, которая легко масштабируется: добавить поддержку нового сервиса — значит просто подключить ещё один MCP-сервер в конфигурации MultiServerMCPClient. Добавить новые документы — бросить PDF в папку data/.

Будущее за модульными AI-системами, и MCP — один из ключевых кирпичиков в этом фундаменте. Пора внедрять.