microdao-daarion/docs/tasks/TASK_PHASE_AGENT_MANAGEMENT_v1.md

TASK_PHASE_AGENT_MANAGEMENT_v1

Title

TASK_PHASE_AGENT_MANAGEMENT_v1 — Agent Create/Delete + Crew Teams Integration

1. Overview

Implement full lifecycle management for DAARION agents:

• Create agent
• Delete agent
• Assign to:
  • Node
  • MicroDAO
  • District (city zone)
  • Crew (team)
• Prepare room integration for CrewAI teams (each crew has its own room).

This task does not change runtime orchestration logic (NATS, Router, etc.) — only registry & UI.

---

2. Current State

• Database:

  • Table agents already exists (used by city-service).
  • There is a sync-node2-dagi-agents.py script populating 50 agents for NODE2 from agents_city_mapping.yaml.

• Backend:

  • repo_city.get_node_agents(node_id) returns agents for Node Cabinet.
  • repo_city.get_agents(...) provides listing for /agents UI.
  • Existing fields:
    • node_id
    • district
    • primary_room_slug
    • model
    • is_public
    • home_node_id
    • home_microdao_id
    • crew_team_key

• Frontend:

  • /agents page lists agents with:
    • status (online/offline)
    • node badge (НОДА1 / НОДА2)
    • visibility badges (Personal / Public)
  • /agents/[slug] has Identity tab with visibility toggles.
  • No button to create or delete an agent from UI.

---

3. Goals

1. Create agent from UI:

   • Minimal form.
   • Pre-fill microDAO/context when creation initiated from MicroDAO.

2. Delete agent from UI:

   • Soft-delete (mark as deleted/archived).

3. Crew / Team attribute:

   • Each agent may belong to a crew_team_key.

4. Prepare for Crew rooms integration:

   • For each crew (unique crew_team_key) we can later auto-create a room.

---

4. Database & Backend Tasks

4.1. Verify agents table fields

Existing fields to use:

• node_id - which node agent belongs to
• home_node_id - home node
• home_microdao_id - home MicroDAO
• district - city district key
• crew_team_key - crew/team key
• is_archived - soft delete flag
• deleted_at - deletion timestamp

4.2. Models & Repo

services/city-service/models_city.py:

class CreateAgentRequest(BaseModel):
    slug: str
    display_name: str
    kind: str = "assistant"
    role: Optional[str]
    model: Optional[str]
    node_id: Optional[str]
    home_microdao_id: Optional[str]
    district: Optional[str]
    crew_team_key: Optional[str]
    is_public: bool = False
    avatar_url: Optional[str]
    color_hint: Optional[str]

services/city-service/repo_city.py:

async def create_agent(data: dict) -> dict:
    """Create new agent in database"""
    pool = await get_pool()
    # INSERT INTO agents ...
    
async def delete_agent(agent_id: str) -> bool:
    """Soft delete agent (set is_archived=true, deleted_at=now())"""
    pool = await get_pool()
    # UPDATE agents SET is_archived = true, deleted_at = NOW() WHERE id = $1

4.3. API routes

services/city-service/routes_city.py:

@router.post("/city/agents")
async def create_agent(body: CreateAgentRequest):
    """Create new agent"""
    # Validate slug uniqueness
    # Insert into database
    # Return created agent

@router.delete("/city/agents/{agent_id}")
async def delete_agent(agent_id: str):
    """Soft delete agent"""
    # Set is_archived = true, deleted_at = now()
    return {"ok": True, "message": "Agent archived"}

---

5. Frontend Tasks

Files:

• apps/web/src/app/agents/page.tsx
• apps/web/src/app/agents/new/page.tsx (new)
• apps/web/src/app/microdao/[slug]/page.tsx
• apps/web/src/app/agents/[agentId]/page.tsx

5.1. API client

// lib/api/agents.ts
export async function createAgent(payload: CreateAgentPayload) {
  return apiClient.post('/city/agents', payload);
}

export async function deleteAgent(id: string) {
  return apiClient.delete(`/city/agents/${id}`);
}

5.2. "New Agent" page

1. On /agents page:

   • Add button + Новий агент in header.
   • Click → navigate to /agents/new.

2. New page /agents/new:

Form fields:

• Ім'я (display_name, required)
• Slug (auto-generated from name, editable)
• Роль / Title (optional)
• Тип агента (kind: orchestrator, assistant, specialist, etc.)
• Нода (select: NODE1, NODE2 — fetch from /nodes)
• MicroDAO (dropdown, fetch from /microdao)
• Район (dropdown: leadership, security, engineering, etc.)
• Команда / Crew (free text or dropdown)
• Модель (optional: list of Swapper models)
• Видимість:
  • is_public (switch, default false)
• Аватар URL (optional)
• Колір (optional color picker)

On submit:

• POST /city/agents
• Redirect to /agents/[slug].

5.3. "Create Agent" from MicroDAO

On /microdao/[slug]:

• In "Агенти MicroDAO" section, add button:

<Link href={`/agents/new?microdao=${microdaoId}`}>
  <Button>
    <Plus className="w-4 h-4 mr-2" />
    Створити агента
  </Button>
</Link>

• On /agents/new:
  • If query ?microdao=... present — pre-fill MicroDAO field.

5.4. Delete Agent action

On /agents/[agentId]:

• Add "Видалити агента" button in settings/danger section.

Flow:

• Confirm dialog: "Видалити агента? Його не буде видно у місті."
• On confirm → DELETE /city/agents/{id}.
• After success: redirect to /agents with toast.

---

6. Crew Teams (Preparation)

This task prepares data for Crew rooms:

• Each agent can have crew_team_key.
• Display crew_team_key as badge on agent card.
• Later: auto-create room for each unique crew_team_key.

---

7. Acceptance Criteria

1. /agents page has + Новий агент button.
2. /agents/new allows creating a new agent.
3. /microdao/[slug] has "Створити агента" button.
4. /agents/[agentId] has "Видалити агента" button.
5. Deleted agents disappear from listings.
6. crew_team_key is visible on agent cards.