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

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

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

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

RAG (Retrieval-Augmented Generation)

Model Context Protocol (MCP)

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

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

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

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

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

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 vecto

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

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=... ) # =

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

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

Плюсы MCP

Минусы MCP

Заключение