Архитектура Agent Mesh

Hercules спроектирован как микро-агент: минимально возможная автономная единица, способная рассуждать, помнить и совершенствоваться. Этот документ объясняет, как несколько агентов Hercules можно объединить в agent mesh — децентрализованную сеть специализированных агентов, которые находят, вызывают и учатся друг у друга, как микросервисы формируют прикладную архитектуру.

1. Зачем микро-агенты?

Один большой ассистент пытается быть хорошим во всём. Это порождает проблемы:

Микро-агент делает наоборот:

2. Анатомия микро-агента Hercules

┌─────────────────────────────────────────┐
│           Агент Hercules                │
│  ┌─────────┐  ┌─────────┐  ┌────────┐ │
│  │ Навыки  │  │ Память  │  │Инструм.│ │
│  │ .md/json│  │ .md/json│  │ schema │ │
│  └────┬────┘  └────┬────┘  └───┬────┘ │
│       └─────────────┴───────────┘      │
│                  │                      │
│           ┌─────────────┐              │
│           │  AgentCore  │              │
│           │  Router     │              │
│           │  Planner    │              │
│           │  Reflector  │              │
│           └──────┬──────┘              │
│                  │                      │
│  ┌───────────────┴───────────────┐      │
│  │  LLM client (IChatClient)   │      │
│  │  YandexGPT / Ollama / Local  │      │
│  └─────────────────────────────┘      │
│                  │                      │
│         ┌────────────────┐             │
│         │  HTTP/gRPC API │             │
│         │  + manifest    │             │
│         └────────────────┘             │
└─────────────────────────────────────────┘

Каждый агент:

3. Манифест агента

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

{
  "agentId": "hercules-code-assistant",
  "version": "1.2.0",
  "displayName": "Code Assistant",
  "description": "Refactors, explains, and generates C# code.",
  "endpoint": "http://localhost:5001",
  "transport": "http",
  "auth": { "type": "apikey", "header": "X-Api-Key" },
  "capabilities": [
    { "name": "csharp-refactor", "triggers": ["refactor", "clean up", "simplify"] },
    { "name": "code-review", "triggers": ["review", "check this code"] }
  ],
  "models": {
    "primary": "yandexgpt",
    "fallback": ["ollama-local"]
  },
  "health": "http://localhost:5001/api/health"
}

Манифест отдаётся по well-known URL, например GET /agent.manifest.json.

4. Межагентный протокол

Агенты общаются через небольшой JSON-конверт.

Запрос

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "sender": "hercules-orchestrator",
  "intent": "csharp-refactor",
  "payload": {
    "message": "Refactor this method to use async/await",
    "context": { "file": "Program.cs", "line": 42 }
  },
  "replyTo": "http://localhost:8421/api/mesh/callback",
  "timeoutMs": 30000,
  "traceId": "abc123"
}

Ответ

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ok",
  "agent": "hercules-code-assistant",
  "mode": "skill",
  "skill": "csharp-refactor",
  "result": {
    "text": "Here is the refactored method...",
    "confidence": 0.91
  },
  "traceId": "abc123"
}

Протокол намеренно минимален. Он может работать поверх HTTP, gRPC или шины сообщений.

5. Маршрутизация в mesh

Получив запрос, локальный агент сначала пытается решить задачу сам. Если не может — пересылает peer’у.

Пользователь ──▶ Оркестратор-агент
                    │
                    ├─▶ локальный навык? ──да──▶ ответ
                    │
                    └─▶ нет ──▶ найти peer по intent ──▶ forward ──▶ ответ

Решение о маршрутизации принимается на основе:

  1. Локального совпадения навыка и уверенности.
  2. Capability-манифеста peer’а.
  3. Исторического success rate каждого peer’а для этого intent.
  4. Задержки, стоимости и текущей нагрузки.
  5. Согласия пользователя и политики доверия.

Выделенный модуль Mesh Router делает это решение прозрачным и тестируемым.

6. Паттерны discovery

Агенты могут находить друг друга несколькими способами:

Паттерн Лучше всего подходит для
Статический конфиг Локальная разработка, небольшие фиксированные топологии
Реестр Production mesh с известным каталогом агентов
mDNS / Bonjour LAN mesh, zero-config setup
Шина сообщений Event-driven mesh, динамическое масштабирование

Сам реестр может быть ещё одним агентом Hercules или простым сервисом на SQLite.

7. Совместное обучение

Каждый агент учится самостоятельно, но mesh может улучшаться коллективно:

8. Доверие и безопасность

Mesh безопасен ровно настолько, насколько безопасен его самый слабый узел. Минимальные меры:

9. Примеры топологий

Одна машина, несколько агентов

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Code      │     │   Writing   │     │   Planner   │
│   Agent     │◀───▶│   Agent     │◀───▶│   Agent     │
│   :5001     │     │   :5002     │     │   :5003     │
└─────────────┘     └─────────────┘     └─────────────┘

Mesh за gateway

                       ┌──────────────┐
                       │   Gateway    │
                       │  (ingress)   │
                       └──────┬───────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
    ┌────▼────┐          ┌─────▼─────┐        ┌────▼────┐
    │ Agent A │◀────────▶│  Agent B  │◀──────▶│ Agent C │
    └─────────┘          └───────────┘        └─────────┘

Mesh на шине сообщений

         ┌──────────┐
         │   NATS   │
         │  / Rabbit│
         └────┬─────┘
              │
    ┌─────────┼─────────┐
    │         │         │
┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│Agent 1│ │Agent 2│ │Agent 3│
└───────┘ └───────┘ └───────┘

10. Сравнение с микросервисами

Аспект Микросервисы Agent Mesh
Единица Сервис Микро-агент
Интерфейс REST/gRPC/events Intent-based сообщения
Масштабирование Горизонтальные поды Агенты с одинаковыми манифестами
Discovery Service registry Capability registry + mDNS
Обработка отказов Retry / circuit breaker То же, плюс LLM fallback
Reasoning Внешнее Встроенное
Память База данных Локальная + shared memory sync
Обучение Re-deploy Самообучающиеся навыки

11. Пример IoT-развёртывания

Идея микро-агента особенно удобна для edge-развёртываний на Raspberry Pi. На одном Pi работает один агент Hercules с одной чёткой ответственностью. Например:

Во всех случаях Pi — это runtime агента, а LLM работает внешне через облачного провайдера. Это делает устройство дешёвым, энергоэффективным и простым для массового развёртывания. Полный каталог B2C и B2B сценариев — в docs/IOT-SCENARIOS-RU.md.

12. Связь с roadmap

Mesh строится по фазам:

  1. Phase 1 — один автономный микро-агент работает.
  2. Phase 2 — навыки и инструменты становятся переносимыми пакетами.
  3. Phase 3 — агенты умеют находить и вызывать друг друга.
  4. Phase 4 — mesh умеет маршрутизировать, ретраить и учиться коллективно.
  5. Phase 5 — mesh наблюдаем, безопасен и готов к production.

Даты и доставляемые результаты — в docs/ROADMAP-RU.md.

13. Открытые вопросы

Ответы будут получены через прототипы и обсуждения по мере движения проекта через Phase 3 и Phase 4.