AutoGen: создание multi-agent систем — полное руководство 2026 — Гайд Qantcore

🔧

AutoGen: создание multi-agent систем — полное руководство 2026

Практическое руководство по Microsoft AutoGen: от установки до создания сложных multi-agent систем с групповым чатом и расширяемой архитектурой

🤖 multi-agent ⏱ 25 мин

# 1. Что такое AutoGen и зачем он нужен

Microsoft AutoGen — это open-source фреймворк для создания multi-agent AI-приложений, способных работать автономно или совместно с человеком. Разработанный в Microsoft Research, AutoGen реализует многослойную архитектуру, в которой агенты обмениваются сообщениями, координируют действия и решают сложные задачи через групповые чаты (GroupChat). Ключевая идея: вместо одного монолитного LLM-запроса вы создаёте команду специализированных агентов, каждый со своей ролью, которые совместно приходят к решению.

AutoGen построен на трёх уровнях: Core API (низкоуровневая событийная система с message-passing), AgentChat API (высокоуровневая оркестрация с шаблонами GroupChat и Team) и Extensions API (подключение любых LLM: OpenAI, Azure, Anthropic, Ollama и других). Это позволяет использовать фреймворк на любом уровне абстракции — от быстрого прототипа до production-системы.

Важное обновление 2025–2026: AutoGen переведён в режим поддержки (maintenance mode). Для новых проектов Microsoft рекомендует Microsoft Agent Framework (MAF) — enterprise-преемника AutoGen. Однако существующие проекты на AutoGen продолжают работать, и фреймворк остаётся отличным инструментом для изучения multi-agent архитектур.

# Ключевые концепции AutoGen v0.4
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import SelectorGroupChat
from autogen_ext.models.openai import OpenAIChatCompletionClient

# Агент — это автономная единица с ролью и LLM-клиентом
# GroupChat — команда агентов, общающихся через общий чат
# Selector — умный роутер, выбирающий следующего агента

# 2. Установка и настройка окружения

AutoGen требует Python 3.10+. Установка выполняется через pip — вы устанавливаете пакеты autogen-agentchat (высокоуровневый API) и autogen-ext[openai] (расширения с поддержкой OpenAI). Для работы с другими провайдерами доступны отдельные расширения.

# Шаг 1: Создаём виртуальное окружение
python3.12 -m venv autogen-env
source autogen-env/bin/activate

# Шаг 2: Устанавливаем базовые пакеты AutoGen
pip install -U "autogen-agentchat" "autogen-ext[openai]"

# Шаг 3 (опционально): AutoGen Studio для no-code прототипирования
pip install -U autogenstudio

# Шаг 4: Устанавливаем API-ключ OpenAI
export OPENAI_API_KEY="sk-your-key-here"

# Проверка установки
python -c "from autogen_agentchat.agents import AssistantAgent; print('OK')"
OK

Структура проекта после установки: рекомендуется создать директорию my-autogen-project/ с файлами agents.py, teams.py и main.py. Для production-сценариев добавьте .env файл с ключами и используйте python-dotenv.

# 3. Создание первого агента

Базовый строительный блок AutoGen — AssistantAgent. Это агент, подключённый к LLM-модели через model_client. Агент получает задачу (task), обрабатывает её и возвращает ответ. Всё работает асинхронно через asyncio.

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def main():
    # Создаём клиент модели — мост к LLM
    model_client = OpenAIChatCompletionClient(
        model="gpt-4.1",
        # temperature=0.7,  # опционально
    )

    # Создаём агента с системным промптом
    agent = AssistantAgent(
        name="python_expert",
        model_client=model_client,
        system_message="Ты — senior Python-разработчик. 
        Отвечай на русском, показывай код с пояснениями.",
        description="Python-эксперт для помощи с кодом",
    )

    # Отправляем задачу агенту
    result = await agent.run(
        task="Напиши функцию для парсинга JSON с обработкой ошибок"
    )
    print(result)

    # Важно: закрываем клиент модели
    await model_client.close()

asyncio.run(main())

Ключевые параметры AssistantAgent: name (уникальное имя), model_client (LLM-клиент), system_message (системный промпт, определяющий роль агента), description (краткое описание для роутера), tools (список инструментов) и max_tool_iterations (максимум циклов вызова инструментов).

# 4. Multi-agent система с групповым чатом

Главная «фишка» AutoGen — групповой чат агентов. Вместо одного агента вы создаёте команду: например, аналитик собирает требования, архитектор проектирует, разработчик пишет код, а ревьюер проверяет. SelectorGroupChat — это умный роутер, который на каждом шаге выбирает, какому агенту передать слово, анализируя контекст диалога.

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import SelectorGroupChat
from autogen_agentchat.conditions import TextMentionTermination
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def main():
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")

    # Создаём команду специализированных агентов
    analyst = AssistantAgent(
        name="analyst",
        model_client=model_client,
        system_message="Ты — бизнес-аналитик. Собирай требования, 
        уточняй детали. Отвечай на русском.",
        description="Бизнес-аналитик",
    )

    developer = AssistantAgent(
        name="developer",
        model_client=model_client,
        system_message="Ты — senior Python-разработчик. 
        Пиши чистый код с тестами. Отвечай на русском.",
        description="Python-разработчик",
    )

    reviewer = AssistantAgent(
        name="reviewer",
        model_client=model_client,
        system_message="Ты — код-ревьюер. Проверяй код 
        на безопасность, читаемость и баги. На русском.",
        description="Код-ревьюер",
    )

    # Критерий остановки: ревьюер говорит "APPROVED"
    termination = TextMentionTermination("APPROVED")

    # Групповой чат с умным селектором
    team = SelectorGroupChat(
        participants=[analyst, developer, reviewer],
        model_client=model_client,
        termination_condition=termination,
        max_turns=10,
        allow_repeated_speaker=False,
    )

    # Запускаем команду — агенты общаются между собой
    stream = team.run_stream(
        task="Нужно создать REST API для интернет-магазина 
        на FastAPI с авторизацией через JWT."
    )
    await Console(stream)
    await model_client.close()

asyncio.run(main())

Как работает SelectorGroupChat: на каждом шаге селектор (по умолчанию LLM-based) анализирует весь контекст диалога и решает, кто должен говорить следующим. Условие TextMentionTermination останавливает чат, когда любой агент произносит ключевую фразу (например, «APPROVED»). Параметр max_turns страхует от бесконечных циклов.

# 5. Настройка памяти и инструментов

Для создания по-настоящему полезных агентов необходимо оснастить их инструментами (tools) и памятью (memory). AutoGen позволяет агентам вызывать функции Python, обращаться к внешним API, выполнять код в песочнице и хранить контекст между вызовами через ChatCompletionContext.

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import TextMessage
from autogen_core import CancellationToken
from autogen_core.tools import FunctionTool
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_core.model_context import BufferedChatCompletionContext
import asyncio, json

# === 1. Создаём инструмент (функцию) ===
async def search_docs(query: str, source: str = "internal") -> str:
    """Поиск по внутренней документации.
    Args:
        query: поисковый запрос
        source: источник ('internal', 'api', 'faq')
    """
    # В реальном проекте — запрос к векторной БД
    docs = {
        "FastAPI": "FastAPI — async Python web-фреймворк",
        "JWT": "JSON Web Token для аутентификации",
        "Docker": "Платформа контейнеризации",
    }
    result = docs.get(query, "Документация не найдена")
    return json.dumps({"query": query, "result": result, "source": source})

# Оборачиваем в FunctionTool
search_tool = FunctionTool(search_docs, description="Поиск по документации")

async def main():
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")

    # === 2. Настройка буферизованной памяти ===
    memory = BufferedChatCompletionContext(buffer_size=20)
    # Хранит последние 20 сообщений в контексте агента

    # === 3. Агент с инструментами и памятью ===
    agent = AssistantAgent(
        name="tool_user",
        model_client=model_client,
        system_message="Ты — инженер. Используй search_docs 
        для поиска информации перед ответом. Русский язык.",
        tools=[search_tool],
        model_context=memory,
        max_tool_iterations=5,
    )

    # Агент сам решит, когда вызвать инструмент
    result = await agent.run(task="Расскажи про FastAPI и JWT")
    print(result)
    await model_client.close()

asyncio.run(main())

Типы памяти в AutoGen: BufferedChatCompletionContext (буфер последних N сообщений), TokenLimitedChatCompletionContext (ограничение по токенам) и кастомные реализации через ChatCompletionContext. Для сложных сценариев используйте McpWorkbench для подключения MCP-совместимых серверов инструментов.

# 6. Интеграция с разными LLM-провайдерами

Одно из главных преимуществ AutoGen — абстракция над LLM-провайдерами. Вы можете использовать любую модель, реализующую интерфейс ChatCompletionClient: OpenAI, Azure OpenAI, Anthropic Claude, Google Gemini, локальные модели через Ollama и даже OpenRouter для доступа к сотням моделей. Замена провайдера не требует изменений в коде агентов — только в создании клиента.

# ===== Вариант 1: OpenAI =====
from autogen_ext.models.openai import OpenAIChatCompletionClient
client = OpenAIChatCompletionClient(
    model="gpt-4.1",
    api_key="sk-...",  # или через env: OPENAI_API_KEY
)

# ===== Вариант 2: Azure OpenAI =====
from autogen_ext.models.openai import AzureOpenAIChatCompletionClient
client = AzureOpenAIChatCompletionClient(
    model="gpt-4.1",
    azure_endpoint="https://your-resource.openai.azure.com",
    api_key="...",
    api_version="2024-08-01-preview",
)

# ===== Вариант 3: Anthropic Claude =====
# pip install autogen-ext[anthropic]
from autogen_ext.models.anthropic import AnthropicChatCompletionClient
client = AnthropicChatCompletionClient(
    model="claude-sonnet-4-20250514",
    api_key="...",
)

# ===== Вариант 4: Локальная модель через Ollama =====
# pip install autogen-ext[ollama]
from autogen_ext.models.ollama import OllamaChatCompletionClient
client = OllamaChatCompletionClient(
    model="llama3.1:8b",
    base_url="http://localhost:11434/v1",
)

# ===== Вариант 5: Google Gemini =====
# pip install autogen-ext[google]
from autogen_ext.models.google import GoogleAIChatCompletionClient
client = GoogleAIChatCompletionClient(
    model="gemini-2.5-flash",
    api_key="...",
)

# ===== Вариант 6: OpenRouter (единый доступ к 200+ моделям) =====
# Используем OpenAI-совместимый endpoint
from autogen_ext.models.openai import OpenAIChatCompletionClient
client = OpenAIChatCompletionClient(
    model="openai/gpt-4.1",
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-...",
    # headers={"HTTP-Referer": "https://myapp.com"},  # опционально
)

# Агенты работают одинаково с любым клиентом!
agent = AssistantAgent("agent", model_client=client)
# ... использование идентично, независимо от провайдера

Важный нюанс: при использовании разных провайдеров учитывайте их лимиты и особенности. Например, Anthropic требует заголовок anthropic-version, а локальные модели через Ollama могут не поддерживать function-calling — тогда агенту нужно передавать инструменты вручную через промпт. Для OpenRouter убедитесь, что модель поддерживает tool-use.

# 7. Продвинутые паттерны: иерархические агенты и routing

Когда простого GroupChat недостаточно, AutoGen предлагает продвинутые паттерны оркестрации. AgentTool позволяет одному агенту вызывать другого как инструмент — это основа иерархических систем. Кастомные селекторы дают полный контроль над маршрутизацией сообщений. А Magentic-One — эталонная multi-agent система от Microsoft Research, построенная на AutoGen, демонстрирует эти паттерны в действии.

from autogen_agentchat.tools import AgentTool
from autogen_agentchat.teams import SelectorGroupChat
from autogen_agentchat.conditions import (
    TextMentionTermination, MaxMessageTermination
)

async def create_hierarchical_system(model_client):
    # === Паттерн 1: Иерархические агенты через AgentTool ===

    # Специализированный агент для математики
    math_agent = AssistantAgent(
        name="math_expert",
        model_client=model_client,
        system_message="Ты — эксперт по математике. Решай 
        задачи пошагово, показывай все вычисления. Русский.",
        description="Математический эксперт",
    )
    # Оборачиваем агента в инструмент!
    math_tool = AgentTool(math_agent, return_value_as_last_message=True)

    # Агент-оркестратор с доступом к math_tool
    orchestrator = AssistantAgent(
        name="orchestrator",
        model_client=model_client,
        system_message="Ты — оркестратор. Используй 
        math_expert для вычислений. Русский.",
        tools=[math_tool],
        max_tool_iterations=8,
    )

    return orchestrator

# === Паттерн 2: Кастомный селектор для GroupChat ===
from autogen_agentchat.teams._group_chat._selector_group_chat \
    import SelectorFunc

def custom_selector(messages) -> str:
    """Правила роутинга на основе контента сообщений."""
    last_msg = messages[-1].content.lower()

    if "ошибка" in last_msg or "баг" in last_msg:
        return "debugger"       # к дебаггеру
    elif "код" in last_msg or "напиши" in last_msg:
        return "developer"      # к разработчику
    elif "архитектур" in last_msg or "проект" in last_msg:
        return "architect"      # к архитектору
    else:
        return "analyst"        # по умолчанию

# Создаём GroupChat с кастомным селектором
team = SelectorGroupChat(
    participants=[analyst, developer, debugger, architect],
    model_client=model_client,
    selector_func=custom_selector,  # свой роутер!
    termination_condition=TextMentionTermination("DONE"),
)

# === Паттерн 3: Magentic-One ===
# Готовая multi-agent команда из коробки:
# pip install autogen-ext[magentic-one]
# from autogen_ext.teams.magentic_one import MagenticOneGroupChat
# — включает WebSurfer, FileSurfer, Coder, Executor

Когда использовать какой паттерн: AgentTool — когда нужна чёткая иерархия (оркестратор → специалисты); кастомный селектор — когда нужны детерминированные правила роутинга без затрат на LLM; Magentic-One — для сложных исследовательских задач с браузингом и выполнением кода. Комбинируя эти паттерны, можно построить систему любой сложности.

✅ Итог и лучшие практики

Microsoft AutoGen — мощный фреймворк для создания multi-agent AI-систем, который, несмотря на переход в maintenance mode, остаётся отличной платформой для изучения и прототипирования. За 25 минут мы разобрали полный путь: от установки и создания первого агента до сложных иерархических систем с кастомными роутерами.

Ключевые рекомендации:

Начинайте с малого: один агент → два агента → GroupChat. Не стройте систему из 10 агентов сразу.
System message — критичен: качество промпта агента определяет качество всей системы. Пишите чёткие роли, ограничения и ожидаемый формат ответа.
Termination conditions — обязательны: всегда задавайте TextMentionTermination или MaxMessageTermination, чтобы избежать бесконечных циклов и лишних затрат на API.
Используйте дешёвые модели для роутинга: селектор GroupChat может работать на GPT-4o-mini, а основные агенты — на GPT-4.1 или Claude.
Память — экономно: BufferedChatCompletionContext с буфером 10–20 сообщений покрывает большинство сценариев. Не храните весь диалог без необходимости — это увеличивает latency и стоимость.
Для новых проектов: рассмотрите миграцию на Microsoft Agent Framework (MAF) — enterprise-преемник AutoGen с production-поддержкой и улучшенной архитектурой.
Изучайте Magentic-One: это эталонная реализация multi-agent системы от Microsoft Research, показывающая лучшие практики использования AutoGen.

AutoGen открыл дверь в мир multi-agent AI, показав, что команда специализированных агентов, координируемая умным роутером, способна решать задачи, недоступные одиночному LLM. Эти принципы легли в основу нового поколения agentic frameworks, и понимание AutoGen — ключ к эффективной работе с любыми современными multi-agent системами.