До определенного момента ИИ-воркфлоу выглядел как один промпт, один вызов модели и один ответ. Затем появились цепочки — summarize → extract → classify.
Но чем сложнее задача, тем быстрее выясняется, что монолитный промпт или пайплайн начинает трещать. Один агент не может одновременно быть внимательным редактором, дотошным тестировщиком и креативщиком.
И именно на этом этапе появляется мультиагентная оркестрация. Идея простая — разбивать работу на роли и дать каждой свой промпт, свой набор инструментов и право голоса. Все по заветам Адама Смита и его разделении труда. Агент-кодер предлагает решение, ревьюер ищет регрессии, планировщик разбивает задачу на подшаги. Фреймворк берет на себя маршрутизацию сообщений, порядок реплик и завершение диалога.
AG2 — это один из тех фреймворков, с интересной историей разделения на AutoGen (ныне Microsoft Agents) и opensource-проект AutoGen2, его и разберем в этой статье, и узнаем, как создавать и оркестрировать мультиагентные системы.
Философия AG2 формулируется примерно так — многие реальные рабочие процессы проще моделировать как разговор между специализированными ролями, чем как один монолитный агент.
Как я уже говорил, AG2 — это community-форк оригинального AutoGen. В ноябре 2024 года команда создателей AutoGen отделилась от кодовой базы Microsoft и продолжила развитие под новым именем, с открытым управлением и собственной организацией ag2ai. Microsoft при этом остался со своим дистрибутивом под старым названием и впоследствии двинулся в сторону Microsoft Agent Framework.
Стоит отмотать в 2023 год. Тогда Microsoft Research публикует статью «AutoGen: Enabling Next-Gen LLM Applications» (также есть документ на arxiv) и выкладывает библиотеку с тем же именем. Идея выстрелила благодаря концепции ConversableAgent, где сущности общаются друг с другом через initiate_chat. Она оказалась настолько удобной, что фреймворк стал де-факто стандартом для мультиагентных экспериментов. Версия 0.2 до сих пор встречается в туториалах и копится в чьих-то legacy-проектах.
А дальше началось интересное. Внутри Microsoft решили переписать всё с нуля. AutoGen 0.4 принёс событийную архитектуру, типизацию и новый слой акторов — красиво, но совместимость API сломалась практически целиком. Параллельно у истоков проекта возникли разногласия о том, куда двигаться дальше, и в ноябре 2024 года Chi Wang с частью команды ушёл. Так появился форк под организацией ag2ai, который позиционирует себя как прямое продолжение: «AG2 (formerly AutoGen)». Впрочем, Microsoft не сдался — развивал свою линию, а позже и вовсе свернул усилия в Microsoft Agent Framework.
С версией 1.0, вышедшей в 2026 году, AG2 перестал быть обычной оберткой вокруг LLM API. Следуя трендам, он стал, во-первых, async-first (а не как более старые проекты, где async был дополнительной фичей) с маленьким предсказуемым ядром и набором opt-in примитивов, которые вы собираете под свою задачу. Цикл агента, вызовы инструментов и запросы к модели являются неблокирующими вызовами, со стримингом по умолчанию. Также поддерживаются протоколы MCP, A2A и AG-UI для фронтенда.
Собирать такое самому руками — боль. Каждый вызов модели надо обернуть в retry, каждый tool-call распарсить, историю диалога ужать до лимита контекста… Именно эту рутину и забирает наш фреймворк. Вы описываете агентов и правила их взаимодействия, библиотека делает остальное.
Но перед кодом — вопрос, где вообще брать модели? Можно брать локальные (ollama, vLLM) — бесплатно и приватно, но нужны GPU и терпение. Либо через облачный шлюз. Кстати, удобный вариант — BotHub — по реферальной ссылке дают 300 000 CAPS на тесты, а сам сервис предоставляет OpenAI-совместимый эндпоинт https://openai.bothub.chat/v1. Это значит, что AG2 подключается к нему как к обычному OpenAI — меняете только base_url и задаете токен. Список доступных моделей доступен по ссылке, включая новейшие Claude 5, Gemini 4, GPT 6, GLM, DeepSeek и другие.
from ag2.config import OpenAICompletionsConfig
config = OpenAICompletionsConfig(
model="claude-fable-5.2",
base_url="https://openai.bothub.chat/v1",
api_key="ВАШ_КЛЮЧ",
)
Архитектура и ключевые концепции
В AG2 функциональность ядра крутится вокруг Agent, Reply и метода ask. Агент — это обертка над моделью с вашим промптом, набором инструментов и правилами поведения. Отправляется запрос через agent.ask(...), в ответ получаете объект Reply, где лежит текст ответа и метаданные (какие инструменты агент вызывал, сколько потратил токенов, чем закончился цикл).
import asyncio
from ag2 import Agent
from ag2.config import OpenAICompletionsConfig
cfg = OpenAICompletionsConfig(
model="claude-fable-5.2",
base_url="https://openai.bothub.chat/v1",
api_key="ВАШ_КЛЮЧ",
)
agent = Agent(
"assistant",
prompt="Ты — вежливый технический ассистент.",
config=cfg
)
async def main() -> None:
reply = await agent.ask("Составь план тестирования REST API за 5 пунктов")
print(reply.body) # сам текст ответа
print(reply.tool_calls) # какие инструменты он дёргал
print(reply.usage) # расход токенов
asyncio.run(main())
Но основа — это не обертка вокруг шлюза LLM API. Декоратором @tool помечается обычная Python-функция — с докстрингом и аннотациями типов, — а дальше AG2 сам делает весь цикл. Модель просит вызов, библиотека парсит аргументы, выполняет функцию, скармливает результат обратно и повторяет, пока задача не решена.
import datetime
from ag2 import Agent, tool
from ag2.config import OpenAICompletionsConfig
@tool
async def get_weekday(date_string: str) -> str:
"""Возвращает день недели для даты в формате YYYY-MM-DD."""
return datetime.strptime(date_string, "%Y-%m-%d").strftime("%A")
@tool
async def days_until(deadline: str) -> int:
"""Сколько дней осталось до даты (YYYY-MM-DD) от сегодняшнего дня."""
target = datetime.strptime(deadline, "%Y-%m-%d").date()
return (target - datetime.now().date()).days
agent = Agent(
"planner",
prompt="Ты помогаешь планировать дедлайны. Используй инструменты для работы с датами.",
config=OpenAICompletionsConfig(model="gpt-6.1-sol"),
tools=[get_weekday, days_until],
)
reply = await agent.ask("1995-03-25 — какой это был день недели? И сколько дней прошло?")
Если инструмент запускает код, его лучше исполнять в песочнице. В AG2 есть SandboxCodeTool и SandboxShellTool с бэкендами E2B и boxd — агент пишет и гонит код внутри изолированной микроВМ.
from ag2.tools import SandboxCodeTool
sandbox = SandboxCodeTool(backend="e2b") # код крутится в облаке E2B
agent = Agent(
"coder",
prompt="Ты — инженер. Пиши и сразу проверяй код.",
config=cfg,
tools=[sandbox],
)
Отдельного внимания заслуживает human-in-the-loop. Библиотека позволяет поставить паузу в любом месте выполнения. Если агент вызвал context.input() — и всё замирает, пока человек не ответит, не подтвердит или не передаст недостающие данные. Существуют готовые хуки для CLI, веб-интерфейса и очередей сообщений.
from ag2.context import input
@tool
async def send_invoice(amount: float, recipient: str) -> str:
ok = await input(
f"Отправить счёт на {amount}$ для {recipient}? [да/нет]"
)
if ok.lower() != "да":
return "Отправка отменена пользователем"
...
Теперь про оркестрацию. В старом AutoGen за координацию нескольких агентов отвечали GroupChat и Handoffs. Но он имел компромиссы. Например, последовательность реплик управлялась LLM-«менеджером», который нередко зацикливался или терял контекст. В AG2 v1.x вместо него пришёл Network — оркестрация через хаб и типизированные каналы. Каждый агент публикует сообщения определённого типа и подписывается на нужные.
from ag2.network import Network, channel
class Draft(channel.Message):
text: str # черновик статьи
class Review(channel.Message):
approved: bool # вердикт критика
comments: list[str]
writer = Agent("writer", prompt="Пиши черновики статей.", config=cfg, publishes=Draft)
critic = Agent("critic", prompt="Оценивай черновики, будь строг.", config=cfg, subscribes=Draft)
editor = Agent("editor", prompt="Финализируй одобренный текст.", config=cfg, subscribes=Review)
net = Network(agents=[writer, critic, editor])
result = await net.run("Напиши статью про векторные базы данных")
print(result["editor"].body)
Также доступны и Middleware — те же прослойки, что в веб-фреймворках, вешаются на конвейер декоратором:
from ag2 import middleware
@middleware
async def log_tools(call):
print(f"→ {call.tool}({call.args})")
result = await call.next() # передаём управление дальше по цепочке
print(f"← {call.tool} вернул {len(str(result))} символов")
return result
agent = Agent("audit", prompt="...", config=cfg, tools=[...], middleware=[log_tools])
Structured outputs — агент возвращает ответ по Pydantic-схеме:
from pydantic import BaseModel
class Plan(BaseModel):
steps: list[str]
estimate_hours: float
plan = await agent.ask("Распланируй миграцию БД", response_format=Plan)
print(plan.steps, plan.estimate_hours) # уже типизированные поля
Концепций, описанных здесь, хватает для многих задач. Остальное — opt-in примитивы: субагенты, персистентная память, телеметрия, интеграции с MCP и A2A.
Установка и первый агент
Тут всё скучно-надёжно: питон 3.11 или новее, виртуальное окружение, одна команда.
uv init .
uv add ag2
После можно уже и писать код.
import os
from ag2 import Agent
from ag2.config import OpenAICompletionsConfig
cfg = OpenAICompletionsConfig(
model=os.environ["AG2_MODEL"], # например, claude-5.1-fable
base_url=os.environ.get("AG2_BASE_URL"), # шлюз, если нужен
api_key=os.environ["AG2_API_KEY"],
)
Не забудьте задать нужные переменные окружения!
Вот уже знакомый вам пример работы агента. Контекст запоминается.
import asyncio
async def main() -> None:
agent = Agent("hello", prompt="Ты кратко отвечаешь на вопросы.", config=cfg)
reply = await agent.ask("Объясни event loop в Python в двух абзацах")
print(reply.body)
followup = await agent.ask("А теперь то же самое, но для junior-разработчика")
print(followup.body)
asyncio.run(main())
Инструменты и tool-calling
Про механику @tool мы уже говорили выше, так что заденем другие темы. Вот, допустим, пример с двумя инструментами — получением погоды и поиском по википедии.
import httpx
from ag2 import tool
@tool
async def get_weather(city: str) -> dict:
r = await httpx.get(f"https://wttr.in/{city}?format=j1", timeout=10)
cur = r.json()["current_condition"][0]
return {"temp_c": cur["temp_C"], "desc": cur["weatherDesc"][0]["value"]}
@tool
async def wiki_search(query: str) -> str:
r = await httpx.get(
"https://en.wikipedia.org/api/rest_v1/page/summary/" + query.replace(" ", "_"),
timeout=10,
)
return r.json().get("extract", "ничего не нашлось")
Второй вопрос — контроль над циклом. Модель может увлечься и вызывать инструменты до бесконечности, сжигая ваши токены. Для предотвращения этого можно задать число максимальных итераций:
agent = Agent(
"researcher",
prompt="Найди информацию о Новосибирске и собери краткую справку.",
config=cfg,
tools=[get_weather, wiki_search],
max_tool_iterations=8,
)
Ошибки инструментов — это часть контракта. Если функция бросила исключение, AG2 отдаст модели текст ошибки, и та, как правило, скорректирует аргументы и попробует снова. Но надёжнее валидировать самому и возвращать человекочитаемое сообщение.
Мультиагентные системы: Network
Я также упоминал и мультиагентные системы как концепцию. Давайте изучим это поподробнее.
Допустим, есть исследование темы. Один агент ищет, второй проверяет факты, третий собирает справку. В AG2 это реализуется через сообщения и подписки (чем-то похоже на брокеры сообщений)
from ag2.network import Network, channel
class Found(channel.Message):
topic: str
facts: list[str]
class Verified(channel.Message):
facts: list[str]
rejected: list[str]
class Report(channel.Message):
markdown: str
researcher = Agent(
"researcher",
prompt="Ищи информацию по теме, выдавай факты с источниками.",
config=cfg, tools=[wiki_search],
publishes=Found,
)
factchecker = Agent(
"factchecker",
prompt="Проверяй факты. Отсекай сомнительные.",
config=cfg, tools=[wiki_search],
subscribes=Found, publishes=Verified,
)
writer = Agent(
"writer",
prompt="Пиши краткую справку в markdown только из проверенных фактов.",
config=cfg, subscribes=Verified, publishes=Report,
)
net = Network(agents=[researcher, factchecker, writer])
result = await net.run("Подготовь справку о квантовых вычислениях")
Сообщение типа Found получит только тот агент, который подписан на него — factchecker, и так далее, то есть появляется цепочка, а при сложных сценариях — и древо агентов.
Human-in-the-loop и безопасность
Про context.input() мы упомянули мельком.
Смотрите, что случилось в 2025-м. В AG2 закрыли уязвимость (патч v1.1.1, CVE), суть которой в лобовой атаке через инструменты. Модель-агент, доверяющая контексту, получала вредоносную инструкцию из внешнего источника — например, из страницы, которую сам же и читал, — и выполняла её как свою задачу. Классический prompt injection, но с правами вашей Python-функции.
Так что любое действие с побочными операциями нужно проводить через явное подтверждение (context.input() или хук). Инструменты выполняются с минимальными правами, а у агента есть бюджет — лимит шагов и лимит spend за запуск.
agent = Agent(
"ops",
prompt="Ты — дежурный инженер. Действуй по runbook.",
config=cfg,
tools=[sandbox, restart_service],
max_tool_iterations=15,
spend_limit_usd=0.50, # не больше полудоллара за запуск
)
Skills: знания, которые агент подгружает сам
Теперь время поговорить про Agent Skills. Идея элементарная, навык — это папка с файлом SKILL.md, где лежат инструкции (а рядом — опциональные скрипты и справочники). Агент читает описание навыка заранее, а саму инструкцию подгружает только тогда, когда задача реально её требует. Контекст не забивается заранее, знания приходят по запросу.
AG2 поддерживает конвенцию agentskills.io из коробки. Скиллы можно держать в директории на диске, а можно объявлять инлайн прямо в коде.
from ag2 import Agent
agent = Agent(
"dev-assistant",
prompt="Ты — ассистент разработчика. Используй навыки для работы с AG2.",
config=cfg,
skills="./skills", # агент сканирует папку и знает, что здесь есть
)
MCP: подключаем context7
Где skills закрывают «как делать», MCP закрывает «чем». Model Context Protocol — важная вещь. Теперь подключим реальный сервер и посмотрим, как мало для этого нужно кода.
AG2 работает с MCP в роли клиента: подключается к серверу, тот сам докладывает, какие инструменты у него есть, и AG2 мапит их на агента. Ручной регистрации ничего не требуется:
from ag2.tools import MCPToolkit
docs = MCPToolkit(
command="npx",
args=["-y", "@upstash/context7-mcp"],
)
agent = Agent(
"coder",
prompt="Пиши код на свежих версиях библиотек. Сверяйся с документацией через инструменты.",
config=cfg,
tools=[docs],
)
Для примера взят context7 — сервер от Upstash, который подтягивает актуальную документацию библиотек прямо в контекст модели. Штука полезная до боли. Главная причина галлюцинаций в коде — устаревшее знание модели о версии API, или вообще слишком новая библиотека. Агент спрашивает у него актуальные сигнатуры и пишет код по ним, а не по веб-поиску или памяти.
Серверов можно подключить несколько, и AG2 разрулит конфликт имён. Не забывайте про безопасность — MCP-сервер — чужой процесс, запускайте только те, которым доверяете.
Оркестрация с правами
Раз AG2 — фреймворк для мультиагентных систем, то стоит задеть тему оркестрации и прав агентов. У одиночного агента гранулярность простая: список tools + лимиты. В мультиагентной системе иногда приходится думать, что делать, когда один агент должен пользоваться инструментами другого.
Многие советуют делать так, чтобы каждый агент получал ровно те инструменты, без которых его роль не выполняется. Исследователь умеет искать, но не умеет писать в файлы. Писатель умеет писать файлы, но в песочницу и без доступа в сеть.
researcher = Agent(
"researcher",
prompt="Только сбор фактов. Ничего не сохраняй и никуда не отправляй.",
config=cfg, tools=[wiki_summary],
max_tool_iterations=8, spend_limit_usd=0.10,
)
writer = Agent(
"writer",
prompt="Пиши текст из проверенных фактов.",
config=cfg, tools=[write_file],
)
reviewer = Agent(
"reviewer",
prompt="Проверяй и подтверждай ключевые действия.",
config=cfg, tools=[],
human_input=True,
)
Второй слой прав — Network-каналы. Типизированные сообщения уже отсекают, кто что видит, но можно докрутить. Например, чтобы агент мог публиковать только в свои каналы.
Ну и также можно делать middleware для защиты запросов:
@middleware
async def guard(call):
if call.agent.name == "researcher" and call.tool not in ALLOWED_RESEARCH:
return "запрещено политикой безопасности"
return await call.next()
Тестирование
Обязательно стоит разобраться с тестированием. Агента стоит тестировать, ибо он также оперирует инструментами, функциями, или проверять влияние на систему и цикл работы.
В AG2 тестирование встроено в библиотеку, и построено оно на трёх привычных по обычному CI примитивах: score, compare и regression-тесты.
Вот банальный пример:
from ag2.eval import EvalCase, score
cases = [
EvalCase(
name="weekday",
query="2026-01-15 — какой это день недели?",
checker=score.exact("Thursday"),
),
EvalCase(
name="refuses-nonsense",
query="Столица несуществующей страны Псевдонии?",
checker=score.not_regex(r"столица Псевдонии"),
),
EvalCase(
name="uses-tool",
query="Какая погода в Новосибирске?",
checker=score.tool_called("get_weather"),
),
]
Три типа проверки уже видны из примера. exact и regex — для случаев, где ответ детерминирован. tool_called — проверка поведения агента, который должен дёрнуть инструмент. Для всего остального есть LLM-судья, который сравнивает ответ агента с рубрикой и ставит балл.
from ag2.eval import rubric
rubric_quality = rubric("""
1 балл — ответ содержит конкретные факты с числами;
2 балла — факты верны, структура понятная;
3 балла — верно, структурно, и есть источники.
""")
report = await cases.score(agent, judge=rubric_quality)
print(report.passed, report.mean_score, report.failures)
Сравнение вариантов — вторая половина системы. Допустим, вы сомневаетесь между двумя промптами или между моделями. Прогоняете один и тот же набор случаев на обоих агентах и смотрите результаты:
a = await cases.score(agent_v1, judge=rubric_quality)
b = await cases.score(agent_v2, judge=rubric_quality)
print(a.compare(b)) # где выросло, где просело, на каких кейсах
И третья часть — регрессионные тесты, которые гоняются на каждый коммит. Логика идентична unit-тестам.
AG2 в экосистеме
Чтобы понимать место AG2, надо помнить, что поле агентных фреймворков к этому году устоялось. LangChain/LangGraph — графы состояний и бездонный зоопарк интеграций. CrewAI — ролевые команды агентов, максимально простой старт. Google ADK — официальный вход в мир Gemini и Vertex. AG2 — разговорные модели с упором на оркестрацию и типизированные сети.
Можно сравнить с другими альтернативами:
|
|
AG2 |
LangGraph |
CrewAI |
Google ADK |
|---|---|---|---|---|
|
Основная модель мира |
разговор агентов |
граф состояний |
роли в команде |
экосистема Gemini |
|
Порог входа |
низкий |
средний |
очень низкий |
средний |
|
Оркестрация |
Network, типизированные каналы |
рёбра графа, циклы |
процесс (sequential/hierarchical) |
классы оркестрации |
|
Human-in-the-loop |
встроенный, |
через точки прерывания |
частично |
встроенный |
|
Async-first с 1.0 |
да |
да |
частично |
да |
|
MCP / A2A |
да, нативно |
через адаптеры |
частично |
да |
|
Своё железо-продукт |
AG2 Space (macOS) |
LangSmith/платформа |
CrewAI Enterprise |
Vertex AI |
MCP к этому году стал де-факто способом подключать инструменты — серверы есть у десятков вендоров, и любой фреймворк, который их не умеет, собственно, вряд ли конкурентоспособен. AG2 держит нативную поддержку, включая A2A для связи агентов между собой и AG-UI для фронтендов.
Еще хочется сказать про AG2 Space — это отдельный продукт команды, десктопное приложение для macOS, где люди и агенты работают в общем пространстве. Кто-то заскринкастил, показал задачу, агент выполняет. Веса фреймворку не добавляет, но все равно интересно.
Практический мини-проект
Попробуем напакостить собрать в некую идею и мини-MVP, дабы узнать, что можно сделать при помощи нашего AG2. Задача состоит в том, что агент-исследователь получает тему, ищет информацию в Википедии, пишет отчёт в markdown, и перед тем, как что-то «сохранить», показывает черновик человеку на подтверждение.
import asyncio
import os
import httpx
from pydantic import BaseModel
from ag2.context import input
from ag2 import Agent, tool
from ag2.config import OpenAICompletionsConfig
cfg = OpenAICompletionsConfig(
model=os.environ.get("AG2_MODEL", "gpt-4o-mini"),
base_url=os.environ.get("AG2_BASE_URL"),
api_key=os.environ["AG2_API_KEY"],
)
@tool
async def wiki_summary(topic: str) -> str:
r = await httpx.get(
"https://en.wikipedia.org/api/rest_v1/page/summary/" + topic.strip().replace(" ", "_"),
timeout=10,
)
data = r.json()
return data.get("extract") or "статья не найдена, попробуй другое название"
@tool
async def save_report(filename: str, content: str) -> str:
ok = await input(f"Сохранить отчёт ({len(content)} символов) в {filename}? [да/нет]")
if ok.strip().lower() != "да":
return "отменено пользователем"
with open(filename, "w", encoding="utf-8") as f:
f.write(content)
return f"сохранено: {filename}"
class Report(BaseModel):
title: str
summary: str
body_markdown: str
async def main() -> None:
agent = Agent(
"research-agent",
prompt=(
"Ты — исследователь. По теме: 1) получи факты через wiki_summary "
"(попробуй 2-3 формулировки, если не нашлось); 2) напиши отчёт в markdown "
"только из найденных фактов, без фантазий; 3) сохрани через save_report."
),
config=cfg,
tools=[wiki_summary, save_report],
max_tool_iterations=12,
spend_limit_usd=0.50,
)
topic = "vector databases"
result = await agent.ask(
f"Подготовь и сохрани отчёт по теме: {topic}",
response_format=Report,
)
print("Заголовок:", result.title)
print("Резюме:", result.summary[:200])
asyncio.run(main())
Инструменты — обычные функции с докстрингами. save_report внутри содержит запрос к человеку, когда агент дойдёт до сохранения, остановится и спросит. response_format=Report вернёт итог в типизированной структуре, которую удобно передавать дальше по пайплайну. Лимиты (max_tool_iterations, spend_limit_usd) гарантируют, что неудачный запуск обойдётся в копейки, а не в сюрприз на счетах провайдера.
Можно вынести поиск в MCP-сервер вместо ручного httpx, добавить фактчекера через Network (схема из раздела выше ложится сюда напрямую), и завернуть EvalCase-набор в CI.
Возможно, вам полезно будет также почитать про Harness² — новое поколение ИИ-агентов от Google Research или Pydantic AI: типизированные агенты на своих моделях.
Заключение
Даже нечего и сказать особо. AG2 — интересный и качественный фреймворк для мультиагентных систем, разрабатывающийся весьма хорошими разработчиками (один из авторов — создатель фреймворка для брокеров сообщений FastStream).
Полезные ссылки:
-
docs.ag2.ai — официальная документация: User Guide, примеры, страница миграции с GroupChat.
-
github.com/ag2ai/ag2 — исходники, релизы и changelog. Проект будет рад контрибьютерам!
-
github.com/ag2ai/ag2-skills — каталог навыков для кодинг-ассистентов.
И напоследок практическое. Все примеры из статьи писались под модели, подключённые через шлюз — отдельно качать локальные веса или заводить биллинг у каждого провайдера не обязательно. Если будете пробовать — по реферальной ссылке дают 300 000 CAPS на тесты, список моделей — на странице моделей, а OpenAI-совместимый эндпоинт https://openai.bothub.chat/v1 из раздела про установку подойдёт как есть. Удачной эксплуатации агентов, товарищи капиталисты!
Автор: DrArgentum


