agentic-studio/network-poc/AGENTBUILDER.md

Kipinä Agent Builder — Suunnitelma

Käyttäjä voi rakentaa omia agentteja "hahmolomakkeella": valitsee avatarin, roolin, kielimallin ja muokkaa prompteja. Agentit tallentuvat localStorageen ja ovat käytettävissä pipelineissa.

Nykytila

// Kovakoodattu agentPrompts-objekti
const agentPrompts = {
    manager: { name: 'Manageri', model: 'qwen2.5-coder:7b', default: '...' },
    coder:   { name: 'Koodari', model: 'qwen2.5-coder:7b', default: '...' },
    tofuist: { name: 'Tofuist', model: 'qwen2.5-coder:7b', docs: '/docs/tofu-cheatsheet.md', default: '...' },
    // ...
};

Ongelma: Uuden agentin lisääminen vaatii koodimuutoksen index.html:ään.

Tavoite

┌─────────────────────────────────────────────────────┐
│  Agent Builder -lomake                              │
│                                                     │
│  ┌─────────┐  Nimi: [Tofuist          ]             │
│  │ 🦎      │  Rooli: [IaC / Infra    ▼]            │
│  │ avatar  │  Malli: [qwen2.5-coder:7b ▼]          │
│  └─────────┘  Docs:  [/docs/tofu-cheatsheet.md]    │
│                                                     │
│  System Prompt:                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │ You are an OpenTofu/Terraform IaC specialist│    │
│  │ ...                                         │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  LLM-parametrit:                                    │
│  Temperature: [0.7]  Top-k: [40]  Max tokens: [512]│
│                                                     │
│  [💾 Tallenna]  [🗑️ Poista]  [📤 Export JSON]       │
└─────────────────────────────────────────────────────┘

Building Blocks

1. Agenttiskeema

{
    id: 'tofuist',                          // uniikki tunniste
    name: 'Tofuist',                        // näyttönimi
    avatar: '/avatars/gecko_notext.png',     // avatar-kuvan polku
    role: 'iac',                             // rooli-template
    model: 'qwen2.5-coder:7b',             // eksakti Ollama-mallinimi
    color: '#e3a336',                        // teemaväri UI:ssa
    docs: '/docs/tofu-cheatsheet.md',        // valinnainen referenssidokumentti
    prompt: 'You are an OpenTofu...',        // system prompt
    params: {                                // LLM-parametrit
        temperature: 0.7,
        top_k: 40,
        max_tokens: 512,
        repetition_penalty: 1.15
    }
}

2. Rooli-templatet (alasvetovalikko)

Valmiit pohjat jotka tuovat oletuspromptit ja parametrit:

Rooli	Oletusprompt	Parametrit
Koodari	"Kirjoita selkeää, testattavaa koodia"	temp 0.7, max 512
QA / Testaus	"Kirjoita testejä, etsi virheitä"	temp 0.4, max 512
DevOps	"Dockerfile, Compose, CI/CD"	temp 0.5, max 512
DevSecOps	"Tietoturva-auditointi, OWASP"	temp 0.3, max 512
Arkkitehti	"Järjestelmäsuunnittelu, rajapinnat"	temp 0.6, max 512
IaC / Infra	"OpenTofu/Terraform HCL-koodi"	temp 0.5, max 512
Data	"Tietokannat, SQL, datamallit"	temp 0.5, max 512
Manageri	"Tehtävien jako ja koordinointi"	temp 0.8, max 200
Kirjoittaja	"Dokumentaatio, README, ohjeet"	temp 0.8, max 512
Vapaa	(tyhjä, käyttäjä kirjoittaa)	temp 0.7, max 512

3. Malli-valitsin

Lista saatavilla olevista malleista — haetaan dynaamisesti:

Hub-kysely: GET /api/models → palauttaa yhdistettyjen solmujen mallit

Tai staattinen lista:
- qwen2.5-coder:7b    (oletus, natiivi GPU)
- qwen2.5-coder:1.5b  (kevyt)
- qwen2.5-coder:0.5b  (selain Wasm)
- deepseek-r1          (reasoning)
- llama3.2:3b          (yleiskäyttö)

Pitkän aikavälin tavoite: hub ilmoittaa WebSocketin kautta mitkä mallit ovat saatavilla.

4. Avatar-valitsin

Valmiit avatarit + mahdollisuus ladata oma:

Hahmo	Tiedosto	Eläin
Asiakas	kettu_notext.png	Kettu
Manageri	karhunpentu.png	Karhunpentu
Koodari	kipina_notext.png	Salamanteri
Data	pesukarhu_notext.png	Pesukarhu
QA	susi_notext.png	Pikkususi
DevOps	laiskiainen_notext.png	Laiskiainen
Tarkkailija	aikuinen_susi.png	Aikuinen susi
Tofuist	gecko_notext.png	Gecko/Lisko
Arkkitehti	???	(tulossa)
DevSecOps	???	(tulossa)

5. Docs-kenttä (referenssidokumentti)

Agentti voi viitata ulkoiseen dokumenttiin joka ladataan promptiin:

docs: '/docs/tofu-cheatsheet.md'  →  haetaan fetch():llä, cachetetaan _docsCache-kenttään

Toiminta:

1. Ensimmäisellä kpnRun-kutsulla ladataan docs-URL
2. Sisältö cachetetaan agent._docsCache-kenttään
3. Liitetään promptiin: "Reference:\n" + docsContent
4. Ei ladata uudelleen saman session aikana

Rajoitukset:

• Max ~3000 tokenia (~10 KB) — pidempi docs tiivistetään
• Vain tekstitiedostot (.md, .txt)

6. Tallennus (localStorage)

// Tallennusavain
'kpn-custom-agents' → JSON.stringify([ agentSkeema1, agentSkeema2, ... ])

// Ladattaessa
const customAgents = JSON.parse(localStorage.getItem('kpn-custom-agents') || '[]');
const defaultAgents = { manager: {...}, coder: {...}, ... };
const agentPrompts = { ...defaultAgents };
for (const agent of customAgents) {
    agentPrompts[agent.id] = agent;
}

Oletusagentit (manager, coder, tester, qa, data) ovat aina mukana — niitä ei voi poistaa, mutta prompteja voi muokata.

Käyttäjäagentit (tofuist, arkkitehti, devsecops, ...) tallentuvat localStorageen ja latautuvat käynnistyksessä.

7. Export / Import

// Export — JSON-tiedosto
const blob = new Blob([JSON.stringify(agent, null, 2)], { type: 'application/json' });
// → agent-tofuist.json

// Import — tiedoston valinta tai drag & drop
// Validoidaan skeema, lisätään agentPrompts-objektiin

Mahdollistaa agenttien jakamisen tiimin kesken.

Toteutusvaiheet

Vaihe 1: Hahmolomake UI

• Avatar-grid valitsin
• Rooli-template alasvetovalikko (täyttää oletuspromptit)
• Malli-valitsin
• System prompt -tekstikenttä
• LLM-parametrit (temperature, top-k, max_tokens)
• Tallenna/Poista-napit

Vaihe 2: Dynaaminen agenttirekisteri

• agentPrompts ladataan localStoragesta
• Oletusagentit + käyttäjän agentit yhdistetään
• Avatar-kortit renderöidään dynaamisesti (ei HTML:ssä)
• Värimapit generoidaan agenttiskeemasta

Vaihe 3: Pipeline käyttää dynaamisia agentteja

• Pipeline-vaiheet viittaavat agentin id:hen (ei kovakoodattuun nimeen)
• Käyttäjä voi valita mitkä agentit osallistuvat pipelineen
• Tofuist voi korvata DevOpsin IaC-projekteissa

Vaihe 4: Mallirekisteri (hub-integraatio)

• Hub tarjoaa /api/models-endpointin
• Saatavilla olevat mallit näkyvät valitsimessa reaaliajassa
• Solmun liittyessä/poistuessa mallit päivittyvät

Arkkitehtuurikaavio

┌──────────────────────────────────────────────────┐
│  Agent Builder UI                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ Avatar   │ │ Rooli    │ │ Malli-valitsin   │  │
│  │ Grid     │ │ Template │ │ (hub/staattinen) │  │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘  │
│       └─────────────┼───────────────┘             │
│                     ▼                             │
│  ┌──────────────────────────────────────────────┐ │
│  │  Agent Schema  { id, name, avatar, model,   │ │
│  │                  role, color, docs, prompt,  │ │
│  │                  params }                    │ │
│  └──────────────────┬───────────────────────────┘ │
│                     │                             │
│       ┌─────────────┼─────────────┐               │
│       ▼             ▼             ▼               │
│  localStorage   Org Chart    Pipeline             │
│  (persist)      (render)     (execute)            │
└──────────────────────────────────────────────────┘