Зачем нужна оркестрация: от одного агента к рою

В 2025 году одиночный AI-агент с парой инструментов уже не удивляет. Реальные бизнес-задачи — исследование рынка, код-ревью, генерация контента с фактчекингом — требуют координации множества агентов. Именно здесь появляется оркестрация: дисциплина, отвечающая на вопрос «как заставить 3, 5 или 20 агентов работать как единая система, а не как толпа, перебивающая друг друга».

Ключевая проблема — state management. Когда пять агентов параллельно исследуют тему, кто-то должен агрегировать результаты, разрешать конфликты, отслеживать контекст и не дать системе уйти в бесконечный цикл рассуждений. Оркестратор решает три критические задачи: маршрутизацию (кому какую подзадачу), управление состоянием (что уже сделано, какой контекст накоплен) и обработку ошибок (что делать, если агент вернул бред или упал).

Без оркестрации вы получаете «эффект испорченного телефона»: Researcher нашёл 10 фактов, Writer использовал 3 не тех, Reviewer пропустил галлюцинации. С оркестрацией — Researcher передаёт структурированный контекст, Writer получает только проверенные данные, Reviewer видит полную цепочку рассуждений. Разница в качестве результата — порядка 40–60%, по нашим замерам на реальных кейсах.

К 2026 году экосистема оркестрации разделилась на два лагеря: Python-инструменты исследовательского класса (CrewAI, AutoGen, LangGraph) — гибкие, с богатой экосистемой LLM-интеграций, и TypeScript/JS production-фреймворки (Mastra, Vercel AI SDK) — с observability из коробки, edge-деплоем и жёсткой типизацией.

Отдельно стоит отметить появление MCP-совместимых оркестраторов (Model Context Protocol). В 2026 году практически все серьёзные фреймворки поддерживают MCP — это позволяет агентам динамически подключать инструменты и сервисы без жёсткой привязки к конкретному вендору. Агент, написанный для CrewAI, может использовать MCP-сервер для доступа к базе данных, а тот же сервер без изменений подключится к агенту в AutoGen или LangGraph.

Ещё один важный тренд — стоимостная оптимизация оркестрации. Каждый вызов агента стоит денег (токены), и когда у вас цепочка из пяти агентов, каждый из которых делает по три вызова к LLM, счёт за API может достигать десятков долларов за один запуск. Умные оркестраторы научились кэшировать результаты, использовать дешёвые модели для простых задач (например, классификация интента через GPT-4o-mini вместо GPT-4o) и применять routing: перед запуском полной цепочки делается быстрая проверка, действительно ли задача требует всех пяти агентов.

Паттерны оркестрации: от простого к сложному

За последние два года кристаллизовались пять устойчивых паттернов. Каждый решает свой класс задач, и выбор паттерна — первое архитектурное решение, которое вы принимаете при проектировании multi-agent системы.

1. Sequential (Последовательный)

Самый интуитивный паттерн: цепочка A → B → C, где каждый следующий агент получает на вход результат предыдущего. Идеален для linear pipelines: research → draft → review. Плюс — простота отладки и предсказуемость. Минус — latency растёт линейно, bottleneck на самом медленном агенте.

На практике sequential-паттерн отлично работает для контентных пайплайнов: подбор ключевых слов → генерация статьи → SEO-оптимизация → фактчекинг. Каждый этап логически зависит от предыдущего, и распараллеливание здесь только внесёт ошибки. Ключевой инженерный приём — structured output между этапами: Researcher возвращает не свободный текст, а JSON с полями facts, sources, confidence — Writer получает строго типизированные данные и не выдумывает факты из воздуха.

2. Parallel (Параллельный)

Coordinator раздаёт независимые подзадачи группе агентов и агрегирует результаты. Применяется для скрапинга нескольких источников, параллельного фактчекинга, генерации вариантов с последующим выбором лучшего. Резко снижает latency, но требует merge-стратегии: голосование, averaging эмбеддингов, LLM-агрегатор.

3. Hierarchical / Manager-Worker

Manager-агент (часто на более мощной модели, например GPT-4o или Claude Opus) декомпозирует задачу, распределяет подзадачи worker-агентам (на более лёгких/дешёвых моделях), валидирует результаты и принимает решение о завершении. Золотой стандарт для complex reasoning — написание технической документации, multi-step код-ревью, due diligence. CrewAI реализует именно этот паттерн.

Важный нюанс: Manager должен иметь чёткий критерий остановки. Без него он может бесконечно отправлять задачи на доработку, генерируя счета за токены. Рекомендуется задавать максимальное количество итераций (обычно 3-5) и порог качества: если improvement между итерациями меньше 5%, цикл останавливается. Также полезно разделять Manager на две роли: Planner (что делать) и Executor (как делать) — это снижает когнитивную нагрузку на одну модель и улучшает качество декомпозиции.

4. Debate / Adversarial

Три (или более) агента с разными перспективами генерируют аргументы за и против, а Judge-агент выносит вердикт. Используется для фактчекинга, risk assessment,合规审查. Главный плюс — резкое снижение галлюцинаций (агенты исправляют друг друга). Цена — 3× токенов. AutoGen реализует этот паттерн через group chat с ролями.

5. Swarm (Рой)

Децентрализованный паттерн: агенты динамически spawn'ят друг друга, передают задачи через общую шину сообщений. Нет единого оркестратора — координация emergent. Подходит для открытых исследований, симуляций, market-making агентов. Самый сложный в отладке, но самый масштабируемый. OpenAI Swarm и Microsoft AutoGen 0.4+ реализуют этот подход.

CrewAI: исследовательская команда из 3 агентов

CrewAI — самый популярный Python-фреймворк для role-based оркестрации. Модель: вы определяете агентов с ролями, целями и backstory, затем объединяете их в Crew с задачами и процессом (sequential или hierarchical). В 2026 году CrewAI обзавёлся встроенной поддержкой MCP-серверов, native function calling и интеграцией с LangSmith.

from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

# Инициализация инструментов
search_tool = SerperDevTool()
scrape_tool = ScrapeWebsiteTool()

# Agent 1: Researcher — ищет и агрегирует информацию
researcher = Agent(
    role="Senior Market Researcher",
    goal="Find and verify the latest data on {topic} from 5+ sources",
    backstory="15 years in equity research. Known for finding non-obvious data points.",
    tools=[search_tool, scrape_tool],
    verbose=True,
    allow_delegation=False,
    llm="gpt-4o"
)

# Agent 2: Writer — превращает данные в связный текст
writer = Agent(
    role="Financial Copywriter",
    goal="Transform research into a compelling 800-word market report",
    backstory="Ex-Bloomberg writer. Specialist in structured, actionable reports.",
    verbose=True,
    allow_delegation=False,
    llm="claude-sonnet-4-20250514"
)

# Agent 3: Reviewer — валидирует и полирует
reviewer = Agent(
    role="Chief Editor & Fact-Checker",
    goal="Verify every claim, fix inconsistencies, ensure professional tone",
    backstory="20 years in financial journalism. Zero tolerance for inaccuracies.",
    verbose=True,
    allow_delegation=True,
    llm="gpt-4o"
)

# Задачи
research_task = Task(
    description="Research {topic}: market size, key players, trends, risks. Use 5+ sources.",
    expected_output="Structured research brief with citations",
    agent=researcher
)

writing_task = Task(
    description="Write a market report based on the research. Include executive summary.",
    expected_output="800-word polished report with clear sections",
    agent=writer,
    context=[research_task]
)

review_task = Task(
    description="Review the report. Check facts, grammar, flow. Approve or request revision.",
    expected_output="Final approved report with review notes",
    agent=reviewer,
    context=[writing_task]
)

# Сборка Crew — sequential процесс
crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, writing_task, review_task],
    process=Process.sequential,
    verbose=True
)

# Запуск
result = crew.kickoff(inputs={"topic": "AI semiconductors market Q3 2026"})
print(result)

Ключевая фича CrewAI — передача контекста между задачами через параметр context=[previous_task]. Writer получает структурированный вывод Researcher, Reviewer видит и исходные данные, и черновик. Это радикально снижает галлюцинации по сравнению с независимыми вызовами агентов.

Для hierarchical-процесса замените Process.sequential на Process.hierarchical — CrewAI автоматически создаст manager-агента, который будет декомпозировать задачи и управлять worker'ами. В production рекомендуется включать memory=True для сохранения контекста между запусками.

AutoGen: conversational agents с group chat

AutoGen (Microsoft) использует принципиально другой подход: агенты общаются через чат-сообщения, а не через фиксированный pipeline. Архитектура: Agent ↔ Runtime (сообщения, инструменты, code execution). Это даёт невероятную гибкость, но требует аккуратного проектирования termination conditions — иначе агенты могут болтать бесконечно.

В 2026 году AutoGen 0.7+ перешёл на event-driven архитектуру с поддержкой distributed agent runtime — агенты могут жить в разных процессах и даже на разных машинах.

import asyncio
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
from autogen_core import CancellationToken

# Модельный клиент (GPT-4o, Claude, или локальная модель)
model_client = OpenAIChatCompletionClient(
    model="gpt-4o",
    api_key="sk-..."
)

# Agent 1: Критик — ищет проблемы в коде
critic = AssistantAgent(
    name="CodeCritic",
    model_client=model_client,
    system_message="""You are a senior code reviewer. Analyze the code for:
- Security vulnerabilities (OWASP Top 10)
- Performance bottlenecks
- Code smells and anti-patterns
- Type safety issues
Be specific: cite line numbers, explain the risk, suggest fix.""",
    description="Senior code reviewer — finds bugs, security issues, and anti-patterns"
)

# Agent 2: Оптимизатор — предлагает улучшения
optimizer = AssistantAgent(
    name="PerfOptimizer",
    model_client=model_client,
    system_message="""You are a performance engineer. Focus on:
- Algorithmic complexity (Big-O analysis)
- Memory allocation and garbage collection
- Database query optimization
- Caching strategies
Suggest concrete refactorings with complexity estimates.""",
    description="Performance engineer — optimizes algorithms and queries"
)

# Agent 3: Арбитр — финальное решение на основе дискуссии
arbiter = AssistantAgent(
    name="TechLead",
    model_client=model_client,
    system_message="""You are a tech lead. Review the discussion between CodeCritic and PerfOptimizer.
Synthesize their findings into a final code review report with:
- Critical issues (must-fix)
- Performance improvements (sorted by impact)
- Style/readability suggestions
End your report with the phrase APPROVED if the code is acceptable.""",
    description="Tech lead — synthesizes findings into a final report"
)

# Group Chat с RoundRobin — каждый агент говорит по очереди
termination = TextMentionTermination("APPROVED")

team = RoundRobinGroupChat(
    participants=[critic, optimizer, arbiter],
    termination_condition=termination,
    max_turns=10
)

# Асинхронный запуск (production-ready)
async def review_code(code: str):
    cancellation_token = CancellationToken()
    
    stream = team.run_stream(
        task=f"Review this code:\n\n```python\n{code}\n```",
        cancellation_token=cancellation_token
    )
    
    async for message in stream:
        # Каждое сообщение содержит: source (кто сказал), content (текст)
        print(f"[{message.source}] {message.content[:200]}...")
    
    return stream.messages

# Запуск
result = asyncio.run(review_code("""
def process_orders(orders):
    results = []
    for order in orders:
        query = f"SELECT * FROM users WHERE id = {order['user_id']}"
        db.execute(query)
        results.append(calculate_total(order))
    return results
"""))

Сила AutoGen — в гибкости коммуникационных паттернов. RoundRobinGroupChat — лишь один из вариантов. Доступны также SelectorGroupChat (LLM выбирает, кто говорит следующим) и Swarm (агенты сами решают, кому передать задачу через handoff). Termination condition критически важен — без TextMentionTermination или MaxMessageTermination агенты могут уйти в бесконечную дискуссию.

LangGraph: графовая оркестрация с checkpoint'ами

LangGraph (от LangChain) предлагает третий подход: оркестрация как направленный граф состояний. Вы описываете узлы (агенты или функции), рёбра (переходы) и условные ветвления. Главное преимущество — встроенный checkpointing: состояние графа сохраняется после каждого шага, что даёт pause/resume, human-in-the-loop, replay и audit trail из коробки.

from typing import TypedDict, Annotated, Literal
from langgraph.graph import StateGraph, END
from langgraph.checkpoint.memory import MemorySaver
from langchain_openai import ChatOpenAI

# Состояние графа — все данные, которые текут между узлами
class AgentState(TypedDict):
    query: str                          # Исходный запрос
    research_notes: Annotated[list, "append"]  # Результаты research (накапливаются)
    draft: str                          # Черновик ответа
    review_feedback: str                # Обратная связь от review
    revision_count: int                 # Счётчик ревизий
    final_answer: str                   # Финальный ответ

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

# Узел 1: Researcher — собирает информацию
def research_node(state: AgentState) -> AgentState:
    response = llm.invoke(f"""Research the following query thoroughly:
Query: {state['query']}
Provide key facts, data points, and verified information. Be comprehensive.""")
    return {"research_notes": [response.content]}

# Узел 2: Writer — пишет ответ на основе research
def writer_node(state: AgentState) -> AgentState:
    research = "\n".join(state["research_notes"])
    feedback = state.get("review_feedback", "")
    
    prompt = f"Write a comprehensive answer based on research.\nResearch:\n{research}"
    if feedback:
        prompt += f"\n\nIncorporate this feedback:\n{feedback}"
    
    response = llm.invoke(prompt)
    return {"draft": response.content}

# Узел 3: Reviewer — проверяет качество
def reviewer_node(state: AgentState) -> AgentState:
    review = llm.invoke(f"""Review this draft for accuracy and completeness.
Query: {state['query']}
Research: {state['research_notes']}
Draft: {state['draft']}

If issues found, explain what to fix. If perfect, say 'APPROVED'.""")
    
    return {
        "review_feedback": review.content,
        "revision_count": state.get("revision_count", 0) + 1
    }

# Условный роутер: одобрен → END, иначе → writer (ревизия)
def should_continue(state: AgentState) -> Literal["writer", "END"]:
    if "APPROVED" in state["review_feedback"]:
        return "END"
    if state["revision_count"] >= 3:  # max 3 попытки ревизии
        return "END"
    return "writer"

# Сборка графа
builder = StateGraph(AgentState)

builder.add_node("researcher", research_node)
builder.add_node("writer", writer_node)
builder.add_node("reviewer", reviewer_node)

builder.set_entry_point("researcher")
builder.add_edge("researcher", "writer")
builder.add_edge("writer", "reviewer")
builder.add_conditional_edges("reviewer", should_continue, {
    "writer": "writer",
    "END": END
})

# Checkpointer — сохраняет состояние после каждого шага
memory = MemorySaver()
graph = builder.compile(checkpointer=memory)

# Запуск с human-in-the-loop (возможность прервать и проверить)
config = {"configurable": {"thread_id": "thread-1"}}

for event in graph.stream(
    {"query": "What are the key trends in AI agent orchestration in 2026?"},
    config,
    interrupt_before=["reviewer"]  # Пауза перед review — человек может вмешаться
):
    node_name = list(event.keys())[0]
    print(f"[{node_name}] ✓")

# Получить состояние (для отладки или ручного вмешательства)
state = graph.get_state(config)
print(f"Current step: {state.next}")
print(f"Draft preview: {state.values.get('draft', '')[:300]}")

Главное преимущество LangGraph — checkpointing и branching. Каждый thread_id — это независимая ветка выполнения. Вы можете в любой момент загрузить состояние, изменить его вручную и продолжить выполнение. Это незаменимо для production-систем, где нужен human-in-the-loop: агент пишет черновик, человек проверяет, вносит правки — система продолжает с исправленного состояния. LangGraph также поддерживает persistent checkpointing через PostgresSaver или SqliteSaver для продакшена.

Mastra: TypeScript-фреймворк для production-агентов

Mastra — это ответ экосистемы TypeScript на оркестрацию агентов. В отличие от Python-фреймворков, Mastra изначально проектировался для production-деплоя: observability через OpenTelemetry из коробки, structured logging, метрики, eval-пайплайны и serverless-деплой на edge. Если ваш стек — TypeScript/Node.js, Mastra — безальтернативный выбор на 2026 год.

import { Mastra, Agent, Step, Workflow } from "@mastra/core";
import { createOpenAI } from "@ai-sdk/openai";
import { createLogger } from "@mastra/loggers";

// Инициализация с OpenTelemetry observability
const mastra = new Mastra({
  logger: createLogger({
    type: "OTEL",
    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
  }),
});

// Модели — можно использовать разные для разных агентов
const gpt4o = createOpenAI({ model: "gpt-4o" });
const claude = createOpenAI({ model: "claude-sonnet-4-20250514" });

// Agent 1: Researcher
const researcher = new Agent({
  name: "Researcher",
  model: gpt4o,
  instructions: `You are a senior market researcher.
Research the topic thoroughly. Provide:
- Market size with sources
- Key players and their market share
- Growth trends (CAGR, YoY)
- Risk factors
Always cite your sources.`,
  tools: {
    web_search: async (query: string) => { /* ваша реализация поиска */ },
    scrape_url: async (url: string) => { /* ваш скрапер */ },
  },
});

// Agent 2: Analyst — строит financial model
const analyst = new Agent({
  name: "FinancialAnalyst",
  model: claude,
  instructions: `You are a financial analyst. Build a DCF model based on research data.
Output a structured JSON with:
- revenue_projections: number[] (5 years)
- ebitda_margins: number[]
- terminal_growth_rate: number
- valuation_range: { low: number, mid: number, high: number }
- key_assumptions: string[]`,
});

// Agent 3: Writer — генерирует investment memo
const writer = new Agent({
  name: "InvestmentWriter",
  model: gpt4o,
  instructions: `Write a professional investment memorandum based on research and financial analysis.
Include: Executive Summary, Market Analysis, Financial Projections, Risk Assessment, Recommendation.
Use formal investment banking language. Target: 1500 words.`,
});

// Workflow — оркестрация агентов в production pipeline
const researchWorkflow = new Workflow({
  name: "investment-research",

  steps: {
    // Step 1: Research
    gatherData: new Step({
      agent: researcher,
      input: (ctx) => `Research: ${ctx.trigger.topic}`,
      onComplete: async (result, ctx) => {
        ctx.state.research = result.text;
        await ctx.log("Research completed", { length: result.text.length });
      },
    }),

    // Step 2: Financial Analysis (зависит от research)
    analyze: new Step({
      agent: analyst,
      dependsOn: ["gatherData"],
      input: (ctx) => `Build DCF model from: ${ctx.state.research}`,
      onComplete: async (result, ctx) => {
        ctx.state.financials = JSON.parse(result.text);
      },
    }),

    // Step 3: Write memo (зависит от обоих предыдущих)
    writeMemo: new Step({
      agent: writer,
      dependsOn: ["analyze"],
      input: (ctx) => `
Research: ${ctx.state.research}
Financials: ${JSON.stringify(ctx.state.financials, null, 2)}

Write the investment memo.
`,
    }),
  },
});

// Production-ready запуск с метриками
const result = await mastra.run(researchWorkflow, {
  trigger: { topic: "NVIDIA AI chips competitive landscape 2026" },
  // Автоматический retry при transient ошибках
  retry: { maxAttempts: 3, backoff: "exponential" },
  // Таймаут всего workflow
  timeout: 300_000, // 5 минут
});

console.log("Workflow completed!");
console.log("Metrics:", result.metrics);
console.log("Duration:", result.durationMs, "ms");
console.log("Token usage:", result.tokenUsage);

Ключевое отличие Mastra от Python-фреймворков — production-first архитектура. Workflow поддерживает retry с exponential backoff, таймауты, structured logging через OpenTelemetry, и метрики (duration, token usage, success rate) из коробки. Для деплоя достаточно npx mastra deploy — и ваш workflow на Vercel/Cloudflare Workers с автоскейлингом.

Сравнение фреймворков: что выбрать в 2026

Production-деплой: Docker, мониторинг и алерты

Продакшен — это не только код агентов, но и инфраструктура. Вот минимальный production-ready стек для деплоя multi-agent системы в 2026 году.

Docker-упаковка

# Dockerfile для CrewAI/LangGraph агентов
FROM python:3.12-slim

# Системные зависимости для opentelemetry
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl ca-certificates && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Зависимости
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Код агентов
COPY agents/ ./agents/
COPY orchestration/ ./orchestration/

# Health check — критически важен для оркестрации
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

# Non-root user
RUN useradd -m -u 1000 agent && chown -R agent:agent /app
USER agent

# OpenTelemetry auto-instrumentation
ENV OTEL_SERVICE_NAME="agent-orchestrator"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="http://jaeger:4317"

CMD ["python", "-m", "orchestration.server"]

Мониторинг через OpenTelemetry

from opentelemetry import trace, metrics
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.resources import Resource
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter

# Инициализация трассировки
resource = Resource.create({"service.name": "agent-orchestrator"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://jaeger:4317"))
)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

# Кастомные метрики для агентов
meter = MeterProvider(resource=resource).get_meter("agent-metrics")

# Счётчики и гистограммы
agent_calls = meter.create_counter(
    "agent.calls",
    description="Number of agent invocations"
)
agent_duration = meter.create_histogram(
    "agent.duration_ms",
    description="Agent execution duration in milliseconds"
)
agent_tokens = meter.create_counter(
    "agent.tokens",
    description="Token usage per agent"
)
agent_errors = meter.create_counter(
    "agent.errors",
    description="Agent execution errors"
)

# Декорирование агентов трейсингом
def traced_agent(agent_name: str):
    def decorator(func):
        async def wrapper(*args, **kwargs):
            with tracer.start_as_current_span(
                f"agent.{agent_name}",
                attributes={"agent.name": agent_name}
            ) as span:
                start = time.time()
                try:
                    result = await func(*args, **kwargs)
                    agent_calls.add(1, {"agent": agent_name, "status": "success"})
                    return result
                except Exception as e:
                    agent_errors.add(1, {"agent": agent_name, "error": type(e).__name__})
                    span.record_exception(e)
                    raise
                finally:
                    elapsed = (time.time() - start) * 1000
                    agent_duration.record(elapsed, {"agent": agent_name})
        return wrapper
    return decorator

# Использование
@traced_agent("researcher")
async def run_research(query: str) -> str:
    # ... вызов LLM, обработка результатов
    pass

Docker Compose для полного стека

# docker-compose.yml — полный production-стек
version: "3.9"

services:
  # Оркестратор агентов
  orchestrator:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
      - jaeger
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      retries: 3

  # Redis — кэш и state management
  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

  # Jaeger — распределённая трассировка
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"  # UI
      - "4317:4317"    # OTLP gRPC
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    restart: unless-stopped

  # Prometheus — сбор метрик
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    restart: unless-stopped

  # Grafana — дашборды и алерты
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    restart: unless-stopped

volumes:
  redis_data:
  grafana_data:

Алерты: что мониторить

Для production-системы оркестрации критически важны следующие алерты:

• agent.errors > 5 за 5 минут — агент упал или возвращает некорректные данные. Возможные причины: rate limit API, изменение формата ответа модели, ошибка в промпте.
• agent.duration_ms p95 > 30s — агент работает медленнее ожидаемого. Проверьте: не деградировало ли API, не вырос ли контекст, не зациклился ли агент.
• agent.tokens rate spike > 2× baseline — аномальный расход токенов. Часто сигнализирует о «verbosity creep» — агент стал генерировать избыточно длинные ответы.
• orchestrator.health check fail — оркестратор не отвечает. Критический алерт — вся multi-agent система в дауне.
• task.queue_depth > 100 — очередь задач растёт быстрее, чем обрабатывается. Нужно масштабирование.