Як використовувати multi-agent системи на Python для автоматизації складних задач

Якщо ти коли-небудь намагався змусити одну AI-модель одночасно шукати інформацію в інтернеті, аналізувати дані й писати звіт — знаєш, як швидко вона починає плутатися. Multi-agent системи вирішують цю проблему: кожен агент відповідає за свою ділянку роботи, а координатор збирає результати докупи. У цьому туторіалі ми побудуємо реальну систему з трьох агентів, яка автоматично досліджує тему, аналізує дані й генерує готовий звіт — займе це близько 60-90 хвилин. Для старту потрібен Python 3.11+, API-ключ OpenAI або Anthropic і базове розуміння синтаксису Python.

🛠️ Що знадобиться

• Python 3.11+ — основна мова, безкоштовний; встанови з python.org якщо ще немає
• LangGraph 0.3+ — фреймворк для побудови графів агентів від LangChain; безкоштовний, встановлюється через pip
• OpenAI API або Anthropic Claude API — мозок агентів; платний, але нові акаунти OpenAI дають $5 кредитів безкоштовно
• Tavily Search API — інструмент для веб-пошуку всередині агентів; є безкоштовний план на 1000 запитів/місяць
• VS Code або PyCharm — редактор коду; обидва безкоштовні для базового використання

📋 Покрокова інструкція

Крок 1: Встановлення залежностей та налаштування середовища

Відкрий термінал і створи нову папку проєкту: введи mkdir multi_agent_demo && cd multi_agent_demo. Потім створи віртуальне середовище командою python -m venv venv і активуй його — на Windows: venv\Scripts\activate, на Mac/Linux: source venv/bin/activate. Встанови всі необхідні пакети однією командою: pip install langgraph langchain langchain-openai langchain-community tavily-python python-dotenv. Створи файл .env у корені проєкту і додай туди: OPENAI_API_KEY=sk-твій_ключ_тут та TAVILY_API_KEY=tvly-твій_ключ_тут — ключі беруться з platform.openai.com і app.tavily.com відповідно у розділі API Keys.

Крок 2: Визначення інструментів для агентів

Створи файл tools.py — тут ми опишемо, що вміють робити наші агенти. Кожен інструмент — це звичайна Python-функція з декоратором @tool. Скопіюй цей код у файл:

from langchain_community.tools.tavily_search import TavilySearchResults
from langchain.tools import tool
from dotenv import load_dotenv
import json

load_dotenv()

search_tool = TavilySearchResults(max_results=5)

@tool
def analyze_data(data: str) -> str:
    """Аналізує текстові дані та виділяє ключові факти"""
    lines = data.split('\n')
    facts = [line for line in lines if len(line) > 50]
    return f"Знайдено {len(facts)} ключових фактів:\n" + '\n'.join(facts[:5])

@tool
def write_report(topic: str, findings: str) -> str:
    """Формує структурований звіт на основі даних"""
    return f"# Звіт: {topic}\n\n## Основні висновки\n{findings}\n\n## Дата: 2026"

Підводний камінь: документаційний рядок (docstring) у кожному @tool — це не просто коментар, а інструкція для агента. Якщо він порожній або незрозумілий — агент не знатиме, коли використовувати цей інструмент.

Крок 3: Створення агентів та їх ролей

Створи файл agents.py. Ми визначимо трьох спеціалізованих агентів: дослідника, аналітика і редактора. Кожен отримує свою системну підказку і свій набір інструментів:

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
from tools import search_tool, analyze_data, write_report

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

def create_researcher():
    prompt = ChatPromptTemplate.from_messages([
        ("system", "Ти — дослідник. Шукай актуальну інформацію по темі. Завжди використовуй пошук."),
        ("human", "{input}"),
        ("placeholder", "{agent_scratchpad}")
    ])
    agent = create_tool_calling_agent(llm, [search_tool], prompt)
    return AgentExecutor(agent=agent, tools=[search_tool], verbose=True)

def create_analyst():
    prompt = ChatPromptTemplate.from_messages([
        ("system", "Ти — аналітик. Отримуєш сирі дані та виділяєш головне."),
        ("human", "{input}"),
        ("placeholder", "{agent_scratchpad}")
    ])
    agent = create_tool_calling_agent(llm, [analyze_data], prompt)
    return AgentExecutor(agent=agent, tools=[analyze_data], verbose=True)

def create_writer():
    prompt = ChatPromptTemplate.from_messages([
        ("system", "Ти — редактор. Пишеш фінальний звіт на основі аналізу."),
        ("human", "{input}"),
        ("placeholder", "{agent_scratchpad}")
    ])
    agent = create_tool_calling_agent(llm, [write_report], prompt)
    return AgentExecutor(agent=agent, tools=[write_report], verbose=True)

Крок 4: Побудова графу координації через LangGraph

Тепер найцікавіше — з’єднуємо агентів у граф. Створи файл graph.py. LangGraph дозволяє визначити, в якому порядку агенти передають роботу один одному, і навіть додати умовну логіку:

from langgraph.graph import StateGraph, END
from typing import TypedDict
from agents import create_researcher, create_analyst, create_writer

class AgentState(TypedDict):
    topic: str
    research_result: str
    analysis_result: str
    final_report: str

researcher = create_researcher()
analyst = create_analyst()
writer = create_writer()

def research_node(state: AgentState) -> AgentState:
    result = researcher.invoke({"input": f"Досліди тему: {state['topic']}"})
    return {**state, "research_result": result["output"]}

def analysis_node(state: AgentState) -> AgentState:
    result = analyst.invoke({"input": state["research_result"]})
    return {**state, "analysis_result": result["output"]}

def writing_node(state: AgentState) -> AgentState:
    result = writer.invoke({
        "input": f"Напиши звіт по темі '{state['topic']}'. Дані: {state['analysis_result']}"
    })
    return {**state, "final_report": result["output"]}

workflow = StateGraph(AgentState)
workflow.add_node("researcher", research_node)
workflow.add_node("analyst", analysis_node)
workflow.add_node("writer", writing_node)

workflow.set_entry_point("researcher")
workflow.add_edge("researcher", "analyst")
workflow.add_edge("analyst", "writer")
workflow.add_edge("writer", END)

app = workflow.compile()

Крок 5: Запуск системи та отримання результату

Створи головний файл main.py і запусти систему. Введи в термінал python main.py — в консолі побачиш, як кожен агент по черзі виконує свою частину роботи:

from graph import app

initial_state = {
    "topic": "Тренди штучного інтелекту в 2026 році",
    "research_result": "",
    "analysis_result": "",
    "final_report": ""
}

result = app.invoke(initial_state)

print("\n" + "="*50)
print("ФІНАЛЬНИЙ ЗВІТ:")
print("="*50)
print(result["final_report"])

with open("report.md", "w", encoding="utf-8") as f:
    f.write(result["final_report"])
print("\nЗвіт збережено у файл report.md")

Фінальний результат — файл report.md з повноцінним структурованим звітом, який дослідник знайшов, аналітик відфільтрував, а редактор оформив. Весь процес займає 30-60 секунд залежно від API.

⚠️ Типові помилки та як їх уникнути

• Агент зациклюється у нескінченному пошуку — встанови параметр max_iterations=5 при створенні AgentExecutor, інакше агент може робити десятки запитів і спустошити API-кредити
• TypeError: AgentState missing keys — при ініціалізації state всі поля TypedDict мають бути присутні, навіть якщо порожні рядки; не пропускай жодного ключа
• RateLimitError від OpenAI — додай між викликами агентів time.sleep(1) або перейди на модель gpt-4o-mini замість gpt-4o — вона дешевша і має вищі ліміти
• Агент ігнорує інструменти і відповідає “зі своєї голови” — перевір, що в системному промпті є явна інструкція типу “завжди використовуй доступні інструменти”; без цього LLM може вирішити обійтися власними знаннями

💡 Поради для кращого результату

По-перше, роби стан (State) якомога детальнішим — додай поля на кшталт errors: list і iteration_count: int, щоб відстежувати, що відбувається всередині графу під час налагодження. По-друге, використовуй verbose=True лише під час розробки — у продакшені він генерує гігабайти логів; замість цього підключи LangSmith (безкоштовний план) для нормального трейсингу через LANGCHAIN_TRACING_V2=true у .env. По-третє, якщо система виконує одноманітні задачі, кешуй результати пошуку в JSON-файл і перевіряй кеш перед кожним запитом до Tavily — це заощадить до 80% API-викликів. По-четверте, для паралельного виконання незалежних агентів використовуй workflow.add_node з asyncio — LangGraph підтримує async-ноди нативно, що пришвидшує роботу вдвічі.

❓ Часті запитання (FAQ)

1. Чи можна використовувати безкоштовні моделі замість GPT-4?
Так, LangGraph працює з будь-якою моделлю через LangChain. Заміни ChatOpenAI на ChatOllama(model="llama3.2") для локального запуску через Ollama — повністю безкоштовно, але агенти з інструментами потребують моделі з підтримкою function calling, тому бери llama3.2 або mistral-nemo.

2. Скільки агентів можна додати в одну систему?
Технічних обмежень немає, але практика показує: більше 7-8 агентів в одному графі стають важкими для налагодження. Краще групувати агентів у підграфи і використовувати ієрархічну архітектуру — supervisor агент керує групами з 2-3 спеціалізованих.

3. Як зробити систему стійкою до помилок окремого агента?
Додай у ноду блок try-except і поверни стан з полем помилки замість виключення. Далі в графі додай умовне ребро: workflow.add_conditional_edges — якщо є помилка, перенаправ на агента-ретрайєра або завершуй граф із частковим результатом.

4. Чи підходить LangGraph для продакшену чи це тільки для прототипів?
LangGraph активно використовується в продакшені у 2026 році — він підтримує персистентний стан через базу даних (PostgreSQL, SQLite), checkpoint-и для відновлення після збоїв і потокове виконання. Для серйозних проєктів розгляни також хмарний LangGraph Platform.

5. Яка різниця між LangGraph і AutoGen від Microsoft?
AutoGen більш орієнтований на розмовні multi-agent системи, де агенти “спілкуються” між собою в чаті. LangGraph — це граф з явно визначеними переходами та станом, що дає більше контролю над потоком виконання. Для детермінованих пайплайнів обирай LangGraph, для гнучкіших дискусійних систем — AutoGen.

🏁 Підсумок

Ти побудував повноцінну multi-agent систему: дослідник шукає інформацію через веб, аналітик її структурує, а редактор формує готовий звіт — і все це автоматично через LangGraph-граф з явним управлінням станом. Тепер ти знаєш, як визначати інструменти, створювати спеціалізованих агентів, з’єднувати їх у граф і запускати складні пайплайни одним рядком коду.

Почни прямо зараз: склонуй цей код, запусти python main.py зі своєю темою і подивись на результат у report.md. Наступний крок — додай четвертого агента-критика, який перевіряє звіт і повертає його редактору на доопрацювання, якщо знаходить слабкі місця. Це зробить систему по-справжньому потужною.