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