microdao-daarion/docs/tasks/TASK_PHASE_AGENT_SYSTEM_PROMPTS_MVP_v1.md

TASK_PHASE_AGENT_SYSTEM_PROMPTS_MVP_v1

Проєкт

microdao-daarion (MVP DAARION.city)

Статус

✅ COMPLETED — 2025-11-30

Мета

Зробити так, щоб системні промти агентів:

• зберігались у реальній БД (agent_prompts таблиця)
• завантажувались через API
• редагувалися через UI на сторінці /agents/:slug (вкладка System Prompts)

Після виконання цієї фази вкладка System Prompts перестає бути "плейсхолдером" і працює як повноцінний редактор системних промтів для ключових агентів DAARION.city.

---

Виконані роботи

1. Аналіз проблеми

Причина порожніх промтів:

• Backend routes (routes_city.py) викликали функції update_agent_prompt() та get_agent_prompt_history(), які не були імплементовані в repo_city.py
• Функція get_agent_prompts() вже існувала і правильно повертала дані

Структура, яка вже працювала:

• ✅ Міграція 016_agent_prompts.sql — таблиця створена
• ✅ GET /city/agents/{agent_id}/dashboard — повертає system_prompts
• ✅ Frontend компонент AgentSystemPromptsCard.tsx
• ✅ Next.js API routes proxy

2. Backend: Додані функції в repo_city.py

update_agent_prompt(agent_id, kind, content, created_by, note)

• Деактивує попередню версію промта
• Створює нову версію з інкрементованим номером
• Повертає оновлений запис

get_agent_prompt_history(agent_id, kind, limit)

• Повертає історію всіх версій промту
• Впорядковано по версії (DESC)

Файл: services/city-service/repo_city.py (рядки ~628-705)

3. Seed Data: Міграція 034_agent_prompts_seed.sql

Створено детальні системні промти для ключових агентів:

Агент	Промти	Роль
DAARWIZZ	core, safety, governance	City Mayor / Orchestrator
DARIA	core, safety	Technical Support
DARIO	core	Community Manager
SOUL	core, safety	District Lead (Wellness)
Spirit	core	Guidance Agent
Logic	core	Information Agent
Helion	core, safety, tools	District Lead (Energy)
GREENFOOD	core, safety	District Lead (Supply-Chain)

---

API Reference

Отримати всі промти агента

GET /city/agents/{agent_id}/dashboard

Повертає system_prompts об'єкт з 4 типами: core, safety, governance, tools

Оновити промт

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

{
  "content": "New prompt content...",
  "note": "Optional change note"
}

Отримати історію промту

GET /city/agents/{agent_id}/prompts/{kind}/history?limit=10

---

Схема БД: agent_prompts

CREATE TABLE agent_prompts (
    id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    agent_id     text NOT NULL,
    kind         text NOT NULL CHECK (kind IN ('core', 'safety', 'governance', 'tools')),
    content      text NOT NULL,
    version      integer NOT NULL DEFAULT 1,
    created_at   timestamptz NOT NULL DEFAULT now(),
    created_by   text,
    note         text,
    is_active    boolean NOT NULL DEFAULT true
);

Індекси:

• idx_agent_prompts_agent_kind — пошук активних промтів
• idx_agent_prompts_agent_created_at — сортування по часу
• idx_agent_prompts_active — фільтр активних

---

Frontend

Сторінка агента

/agents/[agentId] → вкладка "System Prompts"

Компоненти

• apps/web/src/app/agents/[agentId]/page.tsx — головна сторінка
• apps/web/src/components/agent-dashboard/AgentSystemPromptsCard.tsx — редактор промтів
• apps/web/src/lib/agent-dashboard.ts — API клієнт

Можливості

• Перемикання між типами промтів (core/safety/governance/tools)
• Редагування тексту промта
• Збереження змін з індикацією статусу
• Перегляд версії та часу останнього оновлення

---

Застосування міграції

# На сервері
cd /opt/microdao-daarion
psql -U postgres -d daarion < migrations/034_agent_prompts_seed.sql

Або через Docker:

docker exec -i dagi-postgres psql -U postgres -d daarion < migrations/034_agent_prompts_seed.sql

---

Acceptance Criteria

• ✅ Для будь-якого агента з seed-промтами: /agents/:id → вкладка System Prompts показує реальний текст з БД
• ✅ Редагування промта з UI: змінює запис у БД, після перезавантаження новий текст відображається
• ✅ API GET/PUT працюють коректно
• ✅ Версіонування: кожне збереження створює нову версію
• ✅ Seed-дані для 8 ключових агентів

---

Out of Scope (на потім)

• UI для перегляду історії версій
• Перемикання на попередню версію (rollback)
• RBAC перевірки (хто може редагувати)
• Інтеграція з DAGI Router runtime

---

Файли змінені/створені

Змінені

• services/city-service/repo_city.py — додані функції update_agent_prompt, get_agent_prompt_history

Створені

• migrations/034_agent_prompts_seed.sql — детальні промти для ключових агентів
• docs/tasks/TASK_PHASE_AGENT_SYSTEM_PROMPTS_MVP_v1.md — цей документ

Вже існували (без змін)

• migrations/016_agent_prompts.sql — схема таблиці
• services/city-service/routes_city.py — API routes
• apps/web/src/components/agent-dashboard/AgentSystemPromptsCard.tsx — UI компонент
• apps/web/src/lib/agent-dashboard.ts — API клієнт
• apps/web/src/app/api/agents/[agentId]/prompts/[kind]/route.ts — Next.js proxy

---

Тестування

Backend (curl)

# Отримати dashboard з промтами
curl http://localhost:7001/city/agents/AGENT_ID/dashboard | jq '.system_prompts'

# Оновити промт
curl -X PUT http://localhost:7001/city/agents/AGENT_ID/prompts/core \
  -H "Content-Type: application/json" \
  -d '{"content": "Test prompt", "note": "Test update"}'

# Отримати історію
curl http://localhost:7001/city/agents/AGENT_ID/prompts/core/history

Frontend

1. Відкрити http://localhost:8899/agents
2. Вибрати агента (DAARWIZZ, DARIA, тощо)
3. Перейти на вкладку "System Prompts"
4. Перевірити що відображаються seed-промти
5. Змінити текст та натиснути "Save"
6. Перезавантажити сторінку — зміни збережені

---

Версія: 1.0.0
Дата: 2025-11-30
Автор: DAARION AI Team