# NODA1 Agent Architecture

**Дата:** 2026-02-11
**Версія:** 2.1.0

## Огляд

NODA1 використовує уніфіковану систему агентів з єдиним джерелом істини (`config/agent_registry.yml`).

---

## Схема підключення агентів

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           TELEGRAM USERS                                     │
│                    (публічні канали та приватні чати)                        │
└────────────────────────────────┬────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     GATEWAY (dagi-gateway-node1:9300)                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ agent_registry.json (generated from config/agent_registry.yml)      │   │
│  │ ─────────────────────────────────────────────────────────────────── │   │
│  │ 13 Telegram Agents:                                                 │   │
│  │   • daarwizz (Meta-Orchestrator, Digital Mayor)                     │   │
│  │   • helion (Energy Research, Energy Union)                          │   │
│  │   • alateya (R&D Lab OS, Interdisciplinary Research)               │   │
│  │   • druid (Ayurveda, Cosmetics R&D)                                │   │
│  │   • nutra (Nutraceutical Research)                                  │   │
│  │   • agromatrix (AgroMatrix Platform)                               │   │
│  │   • greenfood (Craft Food ERP)                                      │   │
│  │   • clan (Community Spirit)                                         │   │
│  │   • eonarch (Consciousness Evolution)                              │   │
│  │   • yaromir (Private Tech Lead) [whitelist]                        │   │
│  │   • soul (Spiritual Mentor)                                         │   │
│  │   • senpai (Trading Advisor)                                        │   │
│  │   • sofiia (Chief AI Architect)                                     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  Features:                                                                  │
│  • registry_loader.py - читає agent_registry.json                         │
│  • Multimodal: photo, voice (STT), documents                              │
│  • Memory context integration                                              │
└────────────────────────────────┬────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     ROUTER (dagi-router-node1:9102 -> :8000)                  │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ router_agents.json (generated from config/agent_registry.yml)       │   │
│  │ ─────────────────────────────────────────────────────────────────── │   │
│  │ 15 Agents with routing:                                             │   │
│  │   • 13 top-level (user-facing)                                     │   │
│  │   • 2 internal (monitor, devtools)                                 │   │
│  │                                                                      │   │
│  │ Per agent: keywords[], domains[], llm_profile, visibility          │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  Endpoints:                                                                 │
│  • POST /v1/agents/{agent_id}/infer - виклик агента                       │
│  • GET /health - статус                                                    │
│  • GET /metrics - Prometheus метрики                                       │
│                                                                             │
│  Features:                                                                  │
│  • Tool Manager (11 tools per agent)                                       │
│  • Intent routing                                                           │
│  • LLM profile selection                                                   │
└────────────────────────────────┬────────────────────────────────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
                    ▼            ▼            ▼
┌───────────────────────┐ ┌───────────┐ ┌─────────────────────┐
│   LLM PROVIDERS       │ │  MEMORY   │ │     CREWAI          │
│ ───────────────────── │ │ SERVICE   │ │ (dagi-staging-      │
│ • Ollama (local)      │ │ :8000     │ │  crewai-service)    │
│   - qwen3:8b          │ ├───────────┤ │ ─────────────────── │
│   - mistral:7b        │ │ • Qdrant  │ │ crewai_agents.json  │
│   - qwen2.5:3b        │ │ • Neo4j   │ │                     │
│ • DeepSeek (cloud)    │ │ • Postgres│ │ 11 Orchestrators    │
│ • Mistral (cloud)     │ └───────────┘ │ + Teams per agent   │
└───────────────────────┘               └─────────────────────┘
```

---

## Canonical Source of Truth

```
config/agent_registry.yml  ←── ЄДИНЕ джерело істини
         │
         │  tools/agents generate
         ▼
┌────────────────────────────────────────────────────────┐
│ Generated configs (НЕ редагувати вручну!)              │
│                                                        │
│ • gateway-bot/agent_registry.json  → Gateway          │
│ • config/router_agents.json        → Router           │
│ • config/crewai_agents.json        → CrewAI           │
└────────────────────────────────────────────────────────┘
```

---

## Агенти за класами

### TOP-LEVEL (User-facing, 13 agents)

| ID | Display | Telegram | Visibility | Domain |
|----|---------|----------|------------|--------|
| `daarwizz` | DAARWIZZ | public | public | Meta-Orchestrator |
| `helion` | Helion | public | public | Energy |
| `alateya` | Aletheia | public | public | R&D Lab |
| `druid` | DRUID | public | public | Ayurveda/Cosmetics |
| `nutra` | NUTRA | public | public | Nutraceuticals |
| `agromatrix` | Степан Матрікс | public | public | Agriculture |
| `greenfood` | GREENFOOD | public | public | Food ERP |
| `clan` | CLAN | public | public | Community |
| `eonarch` | EONARCH | public | public | Consciousness |
| `yaromir` | YAROMIR | whitelist | private | Tech Lead |
| `soul` | SOUL | public | public | Spiritual |
| `senpai` | SENPAI | public | public | Trading |
| `sofiia` | SOFIIA | public | public | AI Architecture |

### INTERNAL (Service agents, 2 agents)

| ID | Display | Telegram | Scope | Purpose |
|----|---------|----------|-------|---------|
| `monitor` | MONITOR | off | node_local | Observability, alerts |
| `devtools` | DevTools | off | global | Development tools |

---

## Tools per Agent (Standard Stack)

Всі 13 top-level агентів мають доступ до стандартного стеку:

| Tool | Description |
|------|-------------|
| `memory_search` | Пошук в памяті (Qdrant) |
| `graph_query` | Knowledge Graph запити (Neo4j) |
| `web_search` | Пошук в інтернеті |
| `web_extract` | Витяг даних з веб |
| `crawl4ai_scrape` | Глибокий скрейпінг |
| `remember_fact` | Збереження факту про користувача |
| `image_generate` | Генерація зображень |
| `tts_speak` | Текст у мовлення |
| `presentation_create` | Створення презентацій |
| `presentation_status` | Статус презентації |
| `presentation_download` | Завантаження презентації |

---

## CrewAI Teams

Кожен top-level агент може мати CrewAI команду:

```yaml
# Приклад: ALATEYA має 5 "професорів"
alateya:
  team:
    - role: "Prof-Erudite"
      skills: [search, verification, analogies]
    - role: "Prof-Analyst"
      skills: [decomposition, triz, formalization]
    - role: "Prof-Creative"
      skills: [lateral_thinking, cross_domain]
    - role: "Prof-Optimizer"
      skills: [feasibility, risk_assessment]
    - role: "Prof-Communicator"
      skills: [synthesis, presentation]
```

---

## Feature Flags

```bash
# Увімкнено по замовчуванню
AGENT_REGISTRY_ENABLED=true

# Генерація конфігів
feature_flags:
  registry_enabled: true
  generate_prompts: true
  generate_router_config: true
  generate_crewai_config: true
```

---

## Як додати нового агента

1. Редагувати `config/agent_registry.yml`
2. Створити `gateway-bot/<agent>_prompt.txt`
3. `python3 tools/agents validate`
4. `python3 tools/agents generate`
5. `python3 tools/agents smoke --id <agent_id>`
6. Restart gateway: `docker restart dagi-gateway-node1`
7. Commit changes

---

## Мережева конфігурація

```
dagi-network:
  - dagi-gateway-node1
  - dagi-staging-router
  - dagi-staging-crewai-service
  - dagi-memory-service-node1
  - dagi-qdrant-node1
  - dagi-nats-node1
  - swapper-service-node1
  - ...
```

---

## Monitoring

- Gateway metrics: `:9300/metrics`
- Router metrics: `:8000/metrics`
- Prober: `:9108/metrics`
- Prometheus: `:9090`
- Grafana: `:3030`

---

## ⚠️ KNOWN GAP: Router → CrewAI Integration (2026-01-29)

### Current State

Router **always** uses direct LLM call. CrewAI service exists but is **not called**.

```
Current:   Gateway → Router → LLM (always)
                              ↓
                         CrewAI (unused!)
```

### Target State

```
Target:    Gateway → Router → Decision?
                        │
            ┌───────────┴───────────┐
            ↓                       ↓
       Direct LLM             CrewAI /crew/run
       (simple)               (complex tasks)
```

### Integration Point

File: `services/router/main.py` function `agent_infer()`

Add after line ~540:

```python
from crewai_client import should_use_crewai, call_crewai

# Decision: direct LLM or CrewAI?
use_crew, reason = should_use_crewai(agent_id, request.prompt, agent_config)
logger.info(f"🎭 CrewAI decision: {use_crew} ({reason})")

if use_crew:
    crew_result = await call_crewai(agent_id, request.prompt, context)
    if crew_result["success"]:
        return InferResponse(
            response=crew_result["result"],
            model="crewai",
            ...
        )
    # Fallback to direct LLM if CrewAI failed
```

### Prepared Files

- `services/router/crewai_client.py` - ready
- `config/crewai_agents.json` - generated from registry