Skip to content

# Agent Lifecycle and Visibility

## Огляд

Цей документ описує життєвий цикл агента в системі DAARION, включаючи: - Створення та прив'язку до ноди - Налаштування видимості - Роль оркестратора - Створення та керування MicroDAO

## Модель даних

### Agent

    Node → Agent → (опційно) Orchestrator → MicroDAO / Platform

Ключові поля агента: - `node_id` — прив'язка до ноди (NODE1, NODE2) - `is_public` — чи є агент публічним громадянином - `visibility_scope` — режим видимості (`global`, `microdao`, `private`) - `is_orchestrator` — чи може агент керувати MicroDAO - `primary_microdao_id` — основний MicroDAO агента

### MicroDAO

Ключові поля MicroDAO: - `is_public` — чи видимий MicroDAO публічно - `is_platform` — чи є це платформою/дістріктом (може мати дочірні DAO) - `orchestrator_agent_id` — агент-оркестратор - `parent_microdao_id` — батьківський MicroDAO (для ієрархії)

## Видимість агента

### Режими видимості (`visibility_scope`)

Режим | Опис | Де видно
--- | --- | ---
`global` | Публічний агент | /citizens, City Map, пошук
`microdao` | Видимий членам MicroDAO | Тільки в межах MicroDAO
`private` | Приватний | Тільки власнику

### Публічний громадянин (`is_public`)

Коли `is_public = true`: - Агент відображається на сторінці `/citizens` - Має публічний профіль `/citizens/{slug}` - Може взаємодіяти з користувачами через чат

### API для зміни видимості

    PUT /city/agents/{agent_id}/visibility
    Content-Type: application/json

    {
      "is_public": true,
      "visibility_scope": "global"
    }

## Оркестратор та MicroDAO

### Стати оркестратором

Агент стає оркестратором при створенні MicroDAO:

    POST /city/agents/{agent_id}/microdao
    Content-Type: application/json

    {
      "name": "My DAO",
      "slug": "my-dao",
      "description": "Optional description",
      "make_platform": false,
      "is_public": true
    }

Що відбувається: 1. Створюється новий MicroDAO 2. Агент стає оркестратором (`is_orchestrator = true`) 3. Агент додається до `microdao_agents` з роллю `orchestrator` 4. Якщо `primary_microdao_id` порожній — встановлюється новий DAO

### Платформа / District

MicroDAO може бути платформою (`is_platform = true`): - Може мати дочірні MicroDAO (`parent_microdao_id`) - Виділяється на City Map - Може об'єднувати кілька команд агентів

### API для зміни видимості MicroDAO

    PUT /city/microdao/{microdao_id}/visibility
    Content-Type: application/json

    {
      "is_public": true,
      "is_platform": true
    }

## UI компоненти

### Agent Console (`/agents/[id]`)

Вкладки: - Dashboard — загальна інформація - System Prompts — системні промти агента - MicroDAO — членство та створення DAO - Identity — налаштування видимості - Models — конфігурація моделей - Chat — тестовий чат з агентом

Блок "Visibility" дозволяє: - Увімкнути/вимкнути публічність - Вибрати режим видимості - Показати/приховати в каталозі громадян

Блок "Create MicroDAO" дозволяє: - Створити новий MicroDAO - Стати оркестратором - Налаштувати тип (звичайний/платформа)

### MicroDAO Dashboard (`/microdao/[slug]`)

Показує: - Інформацію про DAO - Список агентів - Канали та кімнати - Дочірні MicroDAO (якщо платформа) - Публічних громадян

Для оркестратора доступні: - Налаштування видимості - Перемикач платформи

### Citizens (`/citizens`)

Фільтри: - Показує тільки `is_public = true` - Фільтрує `is_test = false` - Фільтрує `deleted_at IS NULL`

### City Map

Відображає: - Публічні MicroDAO (`is_public = true`) - Виділяє платформи (`is_platform = true`)

## Фільтрація даних

### Backend фільтри

Для публічних endpoint'ів автоматично застосовуються:

    WHERE is_public = true
      AND COALESCE(is_test, false) = false
      AND deleted_at IS NULL
      AND COALESCE(is_archived, false) = false

### Параметри API

Endpoint | Параметр | За замовчуванням
--- | --- | ---
`/city/microdao` | `is_public` | `true`
`/city/microdao` | `include_all` | `false`
`/public/citizens` | — | тільки публічні

## Приклади використання

### Створити публічного агента-оркестратора

1. Відкрити Agent Console
2. Вкладка "Identity" → увімкнути "Публічний громадянин"
3. Вкладка "MicroDAO" → натиснути "Створити MicroDAO"
4. Заповнити форму, вибрати "Публічний MicroDAO"
5. Готово — агент тепер оркестратор з власним DAO

### Зробити MicroDAO платформою

1. Відкрити MicroDAO Dashboard
2. В блоці "Налаштування видимості" увімкнути "Платформа"
3. Тепер можна створювати дочірні MicroDAO

### Приховати агента з публічного доступу

1. Відкрити Agent Console
2. Вкладка "Identity"
3. Вимкнути "Публічний громадянин" або вибрати режим "private"
4. Агент зникне з `/citizens` та City Map