AgentOrchestrator 1.0.0

AgentOrchestrator

Оркестратор консольных ИИ-агентов. Он держит в одном окне несколько панелей-терминалов (каждая — это запущенный агент вроде qwen, pi, claude, gigacode) и умеет запускать воркфлоу — сценарии, в которых агенты по заранее описанным правилам общаются между собой: один написал код, другой его отревьюил, третий записал протокол, а итог пришёл человеку.

Всё, что зависит от конкретного агента (какой командой его запускать, какие переменные окружения ему нужны, где он ведёт свой журнал), и все правила воркфлоу вынесены в JSON-файлы. Менять поведение — значит править файл, а не пересобирать программу.

Установка и запуск

Через dnx (без установки, нужен .NET 10 SDK)

dnx — это возможность .NET 10 запустить инструмент прямо из NuGet, ничего заранее не устанавливая (идея как у npx в мире Node). Программа сама скачается в кэш и запустится:

dnx AgentOrchestrator

Можно закрепить конкретную версию:

dnx AgentOrchestrator@1.0.0

Как обычный .NET-инструмент (ставится один раз)

dotnet tool install --global AgentOrchestrator
agent-orchestrator

Имя команды после установки — agent-orchestrator. Дальше в этом описании команды пишутся именно так; при запуске через dnx замените начало на dnx AgentOrchestrator -- ….

Запуск без аргументов открывает оконный интерфейс с панелями агентов. Всё остальное — это режимы, у каждого своя подкоманда. Полный список подскажет справка:

agent-orchestrator --help
agent-orchestrator wf --help

Настройки: файл appsettings.json

В файле appsettings.json описан список агентов и их параметры. Внутри файла разрешены комментарии и висячие запятые — он рассчитан на ручную правку. Если файл сломан или отсутствует, программа не падает, а стартует на встроенном списке по умолчанию.

Одна запись агента выглядит так:

{
  "id": "qwen",                 // короткий ключ; его же можно передать в командной строке
  "displayName": "Qwen",        // как назвать панель в списке слева
  "command": "qwen",            // что запустить внутри псевдотерминала
  "environmentVariables": {     // необязательно: переменные окружения для процесса
    "QWEN_CODE_SYNCHRONIZED_OUTPUT": "1"
  },
  "sessionIdArgument": "--session-id",   // необязательно: флаг, которым CLI передаётся id сессии
  "sessionLog": {                        // необязательно: как читать журнал этого CLI
    "format": "QwenJsonl",               // "QwenJsonl" | "PiJsonl" | "None"
    "projectsRoot": "%USERPROFILE%\\.qwen\\projects"
  }
}

Значения полей на примерах:

• format: "QwenJsonl" — формат журнала qwen-code и его форков (например gigacode): у них одинаковая раскладка папок, отличается только корень в projectsRoot.
• format: "PiJsonl" — формат агента pi.
• format: "None" (или отсутствие блока sessionLog) — журнал не читается; так сейчас устроен claude.

Внизу файла — какой агент открывать в новой панели по умолчанию:

"defaultAgentId": "qwen"

Где лежит appsettings.json и как его править при запуске через dnx

Программа ищет настройки рядом со своим исполняемым файлом, а не в текущей папке. Это сделано намеренно: агент запускается в папке того проекта, над которым работает, и настройки не должны «уезжать» вместе с ней.

При запуске через dnx исполняемый файл лежит в кэше NuGet (%USERPROFILE%\.nuget\packages\agentorchestrator\<версия>\…), а это папка «только для чтения» — править файл там нельзя, при обновлении версии правки пропадут. Поэтому предусмотрена переменная окружения AO_SETTINGS: если она задана, настройки берутся из указанного ею файла.

# PowerShell: своя копия настроек в удобном месте
$env:AO_SETTINGS = "C:\demo\agents.json"
dnx AgentOrchestrator

:: cmd
set AO_SETTINGS=C:\demo\agents.json
dnx AgentOrchestrator

Порядок поиска настроек:

1. если задана AO_SETTINGS — берётся файл по этому пути;
2. иначе — appsettings.json рядом с исполняемым файлом (встроенные значения по умолчанию).

За основу для своего файла возьмите appsettings.json из репозитория проекта и меняйте под себя.

Воркфлоу: агенты, которые общаются между собой

Воркфлоу — это JSON-файл: кто участвует и какие события какое сообщение вызывают. Формат тоже допускает комментарии и висячие запятые, и так же не роняет программу при ошибке — сломанный файл стоит вам воркфлоу, а не всего приложения.

Из чего состоит файл

• agents — участники. У каждого:
  • name — имя внутри воркфлоу (по нему адресуют source/target);
  • agentType — какого агента запускать (qwen, pi, claude, dev…);
  • description — роль (попадает в приветствие и в ответ на show_workflow);
  • initialMessage — первая задача, приходит вместе с приветствием;
  • workDir — рабочая папка процесса;
  • group — метка для адресации нескольких агентов сразу (пишется как @имя);
  • isParent: true — это уже работающая панель человека, её процессом не создают. Такому участнику тоже можно задать initialMessage — например, велеть координатору ничего не трогать и просто ждать итог.
• events — правила «когда случилось X у агента A → отправить текст агенту B». Поля:
  • source — за чьими фактами следить ("Coder", "*" — любой, "@team" — группа, "parent");
  • target — кому отправить (те же формы плюс "self");
  • type — какой факт (TurnFinished — модель закончила ход, ApiError — сбой провайдера, AgentExited — процесс завершился, и т. д.);
  • filter — регулярное выражение, которое должно встретиться в тексте факта; круглые скобки запоминают кусок и подставляются как {{Match.1}};
  • message — что отправить. В тексте доступны подстановки: {{Text}}, {{Source}}, {{History[^2..]}} (последние сообщения), {{Match.1}} и другие.

Пример: тройка на ревью кода

В пакет вложен готовый пример examples/workflows/code-review-trio.json. В нём:

• Coder пишет код, Critic придирается к нему — они в диалоге, петля обрывается по вердикту «ПРИНЯТО»;
• Scribe ни с кем не разговаривает, только получает события (вердикты, сбои, завершения) и ведёт из них протокол в файле;
• Main (isParent) — панель человека; его initialMessage велит просто ждать, а в конце ему приходит итог.

Сокращённо это выглядит так:

{
  "name": "code-review-trio",
  "agents": [
    {
      "name": "Main",
      "isParent": true,
      "initialMessage": "Ты координатор. Пока идёт ревью — ничего не делай, просто жди. Когда код примут — перескажи итог одной-двумя фразами."
    },
    {
      "name": "Coder",
      "agentType": "pi",
      "group": "team",
      "workDir": "C:/demo/inn",
      "initialMessage": "Напиши функцию validate_inn(...) в inn.py и коротко опиши, что сделал."
    },
    {
      "name": "Critic",
      "agentType": "pi",
      "group": "team",
      "workDir": "C:/demo/inn",
      "initialMessage": "Ты ревьюер. Проверяй inn.py и всегда заканчивай строкой 'ВЕРДИКТ: ПРИНЯТО' или 'ВЕРДИКТ: НУЖНЫ ПРАВКИ'."
    },
    {
      "name": "Scribe",
      "agentType": "pi",
      "workDir": "C:/demo/inn",
      "initialMessage": "Ты секретарь. На каждое событие дописывай строку в report.md."
    }
  ],
  "events": [
    { "source": "Coder",  "target": "Critic", "type": "TurnFinished",
      "message": "Программист закончил проход:\n{{History[^2..]}}\nПроверь и вынеси вердикт." },
    { "source": "Critic", "target": "Coder",  "type": "TurnFinished",
      "filter": "ВЕРДИКТ:\\s*НУЖНЫ ПРАВКИ",
      "message": "Ревьюер вернул замечания:\n{{Text}}\nИсправь." },
    { "source": "Critic", "target": "parent", "type": "TurnFinished",
      "filter": "ВЕРДИКТ:\\s*ПРИНЯТО",
      "message": "Ревью закончено, код принят:\n{{Text}}" }
  ]
}

Полную версию с подробными комментариями смотрите в файле примера, который едет вместе с пакетом.

Как запускать воркфлоу

Все команды воркфлоу собраны в ветке wf. Команды принимают путь к файлу воркфлоу — сохраните его туда, куда вам удобно (например, C:\demo\code-review-trio.json), и укажите этот путь. Готовый пример code-review-trio.json вложен в пакет: при установке через dnx/dotnet tool он лежит внутри распакованного пакета в кэше NuGet (%USERPROFILE%\.nuget\packages\agentorchestrator\<версия>\examples\workflows\), а также есть в репозитории проекта. Скопируйте его к себе и запускайте по своему пути.

Запустить воркфлоу без интерфейса — стартует всех агентов, применяет правила и печатает каждое сообщение шины по порядку, с отметками времени. Это же — самый простой способ увидеть, что вообще происходит:

agent-orchestrator wf run C:\demo\code-review-trio.json

Проверить файл, ничего не запуская — читает воркфлоу и печатает, как он понят: участников, правила и все найденные ошибки (например, опечатку в имени агента):

agent-orchestrator wf validate C:\demo\code-review-trio.json

Остальные диагностические режимы ветки wf:

agent-orchestrator wf send <агент> "<текст>"       # запустить одного агента и отправить ему одно сообщение
agent-orchestrator wf parse <путь-к-журналам>      # что парсер команд извлёк из журналов агента (по пути)
agent-orchestrator wf parse --text "<текст>"       # то же, но по тексту прямо из командной строки
agent-orchestrator wf turns <путь-к-журналам>      # где в журналах определяется конец хода модели

Через dnx та же команда пишется так (аргументы инструменту идут после --):

dnx AgentOrchestrator -- wf run C:\demo\code-review-trio.json

Требования

• .NET 10 SDK — и для dnx, и для установки как глобального инструмента.
• Установленные CLI тех агентов, которых вы указываете в appsettings.json (qwen, pi, claude и т. д.). Программа их только запускает, но не ставит.