AGENTBUILDER.md: Agent Builder -suunnitelma ja building blockit
Kuvaa hahmolomakkeen arkkitehtuurin: agenttiskeema, rooli-templatet, malli-valitsin, avatar-grid, docs-kenttä, localStorage-tallennus, export/import ja 4-vaiheinen toteutussuunnitelma. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
215
network-poc/AGENTBUILDER.md
Normal file
215
network-poc/AGENTBUILDER.md
Normal file
@@ -0,0 +1,215 @@
|
|||||||
|
# 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
|
||||||
|
|
||||||
|
```js
|
||||||
|
// 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
|
||||||
|
|
||||||
|
```js
|
||||||
|
{
|
||||||
|
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)
|
||||||
|
|
||||||
|
```js
|
||||||
|
// 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
|
||||||
|
|
||||||
|
```js
|
||||||
|
// 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) │
|
||||||
|
└──────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user