AGENTS SERVICE SPEC (PORT 7002)¶

Version: 1.0.0¶

0. PURPOSE¶

Agents Service — це центральний сервіс текстових агентів DAGI:

надає API для виклику Helion, Helix, Metamorph та інших текстових агентів;
інтегрується з DAGI Router / ProjectBus / Mesh Directory;
застосовує:
Agent Registry,
Context Router,
Silence Policy,
Throttling,
TeamDefinition/ProjectBus контекст.

Це логічний "Runtime осередок" для текстової частини DAGI.

Порт за замовчуванням (NODE1/NODE2): 7002.

1. HIGH-LEVEL ARCHITECTURE¶

[ Gateway (Telegram/Web/Matrix/...) ]
         ↓
  [ DAGI Router (gateway.daarion.city) ]
         ↓
    [ Agents Service (7002) ]
         ↓
   [ LLM Providers / Swapper / DAGI Mesh ]

Agents Service отримує RouterEvent-like запити від DAGI Router (або внутрішніх сервісів) та:

Визначає, які агенти доступні (через AgentRegistry + Mesh Directory + TeamDefinition).
Обирає найвідповіднішого/декількох (Context Router).
Перевіряє Silence Policy.
Застосовує throttling.
Викликає відповідний LLM / backend агента.
Повертає відповідь + metadata.

2. DEPENDENCIES¶

2.1. Внутрішні модулі¶

Agents Service використовує:

configs/AGENT_REGISTRY.yaml
configs/AGENT_REGISTRY_SCHEMA.yaml
services/agent_registry_loader.py
services/agent_context_router.py
services/agent_silence_policy.py
services/agent_throttle.py
services/agent_mesh_directory.py
configs/team_definition.yaml
configs/project_bus_config.yaml

2.2. Зовнішні сервіси¶

LLM Provider / Swapper Service (NODE1/NODE2)
NATS (або інший event-bus) для:
ProjectBus,
Mesh Directory,
M2M-комунікації між агентами.
PostgreSQL / Redis (опційно) для:
кешу відповідей,
logging / traces.

3. CONFIGURATION¶

ENV-змінні:

AGENTS_SERVICE_PORT=7002

AGENT_REGISTRY_PATH=configs/AGENT_REGISTRY.yaml
AGENT_REGISTRY_SCHEMA_PATH=configs/AGENT_REGISTRY_SCHEMA.yaml

TEAM_DEFINITION_PATH=configs/team_definition.yaml
PROJECT_BUS_CONFIG_PATH=configs/project_bus_config.yaml

MESH_DIRECTORY_MODE=inprocess   # "inprocess" | "nats" | "http"
MESH_DIRECTORY_NATS_SUBJECT_BASE=agent.directory

LLM_PROVIDER_BASE_URL=http://localhost:8890  # або інший super-service/swapper

AGENT_THROTTLE_LIMIT_PER_MINUTE=3
AGENT_THROTTLE_WINDOW_SECONDS=60

4. PUBLIC API (HTTP)¶

4.1. `POST /agents/invoke`¶

Основний endpoint для DAGI Router та внутрішніх сервісів.

Request:

{
  "event": {
    "event_id": "tg:123",
    "source": "telegram",
    "chat": { "id": "123", "type": "group" },
    "user": { "id": "user1", "username": "alex" },
    "team_id": "team-daariandao-core",
    "project_id": "proj-daariandao",
    "text": "helix, перевір api",
    "attachments": {
      "images": [],
      "docs": [],
      "audio": [],
      "geo": [],
      "tables": []
    },
    "flags": {
      "command": null,
      "reply_to": null,
      "confidential_mode": "public"
    }
  },
  "options": {
    "force_agent_id": null,          // якщо заповнено, обійти context router
    "allow_panel_mode": true,        // дозволити кільком агентам відповісти
    "max_agents": 2                  // верхня межа для panel-режиму
  }
}

Response (успішний сценарій):

{
  "status": "ok",
  "replies": [
    {
      "agent_id": "ag_helix",
      "text": "Ось аналіз API ...",
      "meta": {
        "model": "HELIX_ENGINEER_MODEL",
        "tokens_in": 123,
        "tokens_out": 256,
        "latency_ms": 900
      }
    }
  ],
  "context": {
    "project_id": "proj-daariandao",
    "team_id": "team-daariandao-core",
    "reply_mode": "panel"
  }
}

Response (ніхто не має відповідати):

{
  "status": "silent",
  "reason": "no_agent_or_policy",
  "context": {
    "project_id": "proj-daariandao",
    "team_id": "team-daariandao-core"
  }
}

Response (throttling):

{
  "status": "throttled",
  "reason": "rate_limit",
  "agent_id": "ag_helion"
}

4.2. `GET /agents/registry`¶

Повертає список агентів (тільки для адміністраторів / системних агентів):

Response:

{
  "agents": [
    {
      "agent_id": "ag_helion",
      "name": "Helion",
      "role": "assistant",
      "priority": 5,
      "model": "HELION_TEXT_MODEL",
      "skills": ["допоможи", "поясни"],
      "modalities": ["text"],
      "description": "Головний асистент DAARION."
    }
  ]
}

4.3. `GET /agents/instances`¶

Проксі до Mesh Directory (видно інстанси):

{
  "instances": [
    {
      "agent_id": "ag_helion",
      "instance_id": "ag_helion@noda1-01",
      "node_id": "NODA1",
      "status": "online",
      "project_ids": ["proj-daariandao"],
      "microdao_id": "microdao-root",
      "last_seen": 1732450200.123
    }
  ]
}

5. INTERNAL LOGIC¶

5.1. Pipeline для `/agents/invoke`¶

Покроковий алгоритм:

Parse event
прийняти event (RouterEvent-сумісний payload),
витягнути project_id, team_id, chat.id.
Load TeamDefinition
знайти команду по team_id (або по project_id → команди, які працюють у цьому проекті),
зчитати reply_mode:
- single / panel / silent,
- max_agents_per_message.
Load AgentRegistry & MeshDirectory
завантажити список агентів із registry,
для кожного, хто в TeamDefinition:
- перевірити, чи є онлайн інстанси (Mesh Directory).
Context Router
побудувати AgentDescriptor для кожного доступного агента (з skills, priority),
викликати select_best_agent(event, descriptors):
- для single: обрати 1,
- для panel: обрати до max_agents_per_message,
- для silent: можна одразу повернути status: silent.
Silence Policy (per-agent) Для кожного кандидата:
should_agent_reply(agent_id, event):
- прямі згадки,
- команди,
- приватні чати,
- контекстна релевантність.

Якщо жоден не проходить → status: silent.

Throttling (per-agent, per-chat) Для кожного, хто пройшов silence policy:
throttle.can_reply(agent_id, chat_id):
- якщо ні → позначити throttled,
- якщо хоча б один агент може відповідати → продовжуємо.
Invoke agents (LLM Provider) Для кожного дозволеного агента:
сформувати system prompt (на основі AGENT_REGISTRY, ролі, skills),
сформувати user/context prompt (із події),
відправити в LLM Provider / Swapper Service:
- POST /llm/invoke (або NATS subject llm.invoke).
Aggregate response
зібрати replies (до N агентів),
зібрати meta (latency, tokens),
повернути у DAGI Router HTTP-відповідь.

6. INTEGRATION WITH DAGI ROUTER¶

6.1. З боку DAGI Router¶

При текстовій гілці (без мультимодальності):

# dagi_router.py (схематично)
resp = http.post("http://agents-service:7002/agents/invoke", json={
    "event": router_event_dict,
    "options": {
        "force_agent_id": None,
        "allow_panel_mode": True,
        "max_agents": 2
    }
})

Router далі:

бере resp["replies"],
конвертує в повідомлення для Gateway (Telegram/Web/Matrix),
застосовує свої policy (наприклад, фільтрацію ненормативу, якщо треба).

7. NATS / PROJECT BUS INTEGRATION¶

Agents Service також:

Слухає ProjectBus:
project.<project_id>.chat.mixed (через DAGI Router),
project.<project_id>.tasks (можна робити автоматичну обробку задач).
Може публікувати події:
project.<project_id>.agents (наприклад, "Helix взяв task t123"),
project.<project_id>.m2m.* (M2M/R2D2 комунікація).

Це дозволяє:

агентам працювати в командах,
не тільки як chatbot, а як учасники mesh-процесів.

8. HEALTHCHECK & METRICS¶

8.1. Healthcheck¶

GET /healthz:

{
  "status": "ok",
  "registry_loaded": true,
  "mesh_directory_mode": "inprocess",
  "uptime_seconds": 12345
}

8.2. Prometheus метрики¶

agents_invocations_total{agent_id, project_id, status}
agents_throttled_total{agent_id}
agents_silent_decisions_total{reason}
agents_llm_latency_ms_bucket{agent_id, le=...}

9. LOGGING¶

Кожен виклик /agents/invoke логувати:

event_id, source, chat.id, project_id, team_id,
кандидатів агентів + scores (debug-level),
остаточно обраних агентів,
статус: ok / silent / throttled / error,
latency LLM.

Формат: JSON-лог для подальшого аналізу (ELK / Loki / Grafana).

10. TEST PLAN (SHORT)¶

Unit-тести (pytest):

test_single_agent_selection()
один агент у команді, простий текст, немає throttling → відповідає.
test_panel_mode_two_agents()
reply_mode: panel, max_agents_per_message: 2,
питання, релевантне Helix і Guardian → відповідають двоє.
test_silence_policy_mentions()
повідомлення без згадок і без ключових слів → status: silent.
test_throttling_per_agent()
4 виклики поспіль у межах 60 сек,
limit_per_minute=3,
4-й → status: throttled.
test_team_definition_loading()
агрегація команд з team_definition.yaml,
мапінг на project_id.

11. SUMMARY¶

Agents Service (7002) — це:

офіційний текстовий runtime DAGI,
точка входу для Helion/Helix/Metamorph та інших текстових агентів,
шар, який:
"бачить" всю конфігурацію агентів (Registry),
"бачить" живі інстанси (Mesh Directory),
враховує TeamDefinition/ProjectBus,
контролює поведінку агентів у чатах (silence/panel/throttle).

Після реалізації цього сервісу DAGI Router зможе:

делегувати всю текстову логіку в єдиний, стандартизований компонент,
який легко масштабувати між НОДА1/НОДА2 і далі.