Agent API

API agenta umožňuje vašim skriptom, úlohám CI a nástrojom komunikovať s agentom cez HTTP. Overíte sa osobným API tokenom, pošlete správu a odpoveď dostanete buď po dokončení behu, alebo priebežne streamovanú. Všetko, čo spustenie vykoná, je bežný beh konverzácie: rovnaké nástroje, oprávnenia, Projekty a účtovanie spotreby ako pri správe napísanej vo webovej aplikácii.

Príklady používajú https://elowen.example.com; nahraďte ju adresou, na ktorej Elowen otvárate. Všetky cesty vedú cez toho istého hostiteľa pod /api.

Osobné API tokeny

Token koná za vás. Má presne taký prístup, aký má váš účet, vrátane práv administrátora, takže s ním zaobchádzajte ako s heslom.

Vytvorte token

1. Otvorte Účet → API tokeny.
2. Vyberte Nový token, zadajte názov, ktorý neskôr spoznáte, a prípadne zvoľte posledný deň, kedy má token fungovať. Ak necháte dátum prázdny, token funguje, kým ho neodstránite. Prestane fungovať na konci zvoleného dňa v UTC.
3. Skopírujte token z okna, ktoré sa otvorí. Zobrazí sa len raz. Elowen ukladá jeho odtlačok, nie token samotný, takže ho už nikto nemôže zobraziť. Ak ho stratíte, vyberte v riadku tokenu Kopírovať a v dialógu potvrďte Vytvoriť novú hodnotu. Token dostane celkom novú hodnotu, ktorá sa zobrazí raz a uloží sa do schránky. Všetko, čo ďalej používa starú hodnotu, okamžite prestane fungovať; názov, limity a zaznamenané využitie zostanú.

Každý token začína na elw_, takže uniknutý token ľahko spoznáte v zázname alebo vo vloženom texte. Účty chatbotov tokeny mať nemôžu.

Riadok Volanie agenta pod kartou tokenov skopíruje hotový príklad curl pre endpoint spustenia, už s vyplnenou adresou vašej inštancie Elowen.

Využitie a limity

Tokeny nájdete v jednej karte, každý na vlastnom riadku, s posledným použitím, platnosťou a prefixom a s tlačidlami Kopírovať, Limity a Odstrániť. Otvorením riadku zobrazíte behy tokenu, zodpovedané aj zlyhané behy a náklady za deň, a tiež limity, podľa ktorých token beží. Náklady sa počítajú pre obdobie, ktoré zvolíte vedľa grafu; zvolené obdobie potom platí pre všetky tokeny. Dni sa počítajú v UTC.

Výberom Limity dáte tokenu strop. Každý limit je nepovinný a každý má vlastný prepínač Bez obmedzenia:

Ak beh spotreboval tokeny a nič ich neocenilo — poskytovateľ nehlásil žiadnu sumu a Elowen nemal pre model cenu (žiadny záznam v katalógu ani nastavenú cenu pre daný model) — sú náklady toho dňa neznáme. Elowen nikdy nepovažuje neznáme za nulu: token zobrazuje Cena neznáma a token s denným limitom nákladov sa odmieta do konca toho dňa v UTC, token s mesačným limitom do konca toho mesiaca v UTC. Limit nákladov počíta, čo behy už spotrebovali, takže behy, ktoré stále prebiehajú, keď sa spúšťa nové, môžu deň alebo mesiac mierne prekročiť.

Ak sa Elowen restartuje počas spustenia, toto spustenie sa počíta ako zlyhané a jeho útratu už nemožno tokenu pripísať. Deň, kedy začalo, a deň restartu sa potom počítajú ako neznáme náklady, takže token s denným limitom nákladov sa odmieta do konca týchto dní v UTC a token s mesačným limitom do konca mesiacov, do ktorých tieto dni patria.

Odstráňte token

V riadku tokenu vyberte Odstrániť. Všetko, čo ho používa, okamžite prestane fungovať a zaznamenané využitie sa zmaže. Zmazaním účtu sa zmažú aj všetky vaše tokeny.

Čo token nevie

Token sa nemôže odhlásiť, zmeniť vaše heslo, vydávať sa za iný účet ani vytvárať, upravovať, obnovovať či odstraňovať tokeny, vrátane seba samého. To vyžaduje vaše prihlásenie vo webovej aplikácii a API na také požiadavky odpovedá 403.

Overovanie

Token posielajte v hlavičke Authorization pri každej požiadavke:

export ELOWEN_URL=https://elowen.example.com
export ELOWEN_TOKEN=elw_…   # the token you copied

curl -sS "$ELOWEN_URL/api/auth/me" -H "Authorization: Bearer $ELOWEN_TOKEN"

Chýbajúci, neznámy, zmazaný alebo prepadnutý token dostane 401 {"error":"unauthorized"}. To isté sa stane po tom, čo tokenu vytvoríte novú hodnotu: stará hodnota je od tej chvíle mŕtva.

Spustite agenta

POST /api/v1/agent/runs pošle jednu správu a spustí jeden beh agenta.

Počkajte na odpoveď

curl -sS "$ELOWEN_URL/api/v1/agent/runs" \
  -H "Authorization: Bearer $ELOWEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarise the failed builds from yesterday"}'

{ "conversationId": "brain-12-…", "reply": "Two builds failed…", "usage": { "tokens": 1840, "costUsd": 0.012 } }

usage.costUsd je null, keď spustenie nič neocenilo: poskytovateľ nehlásil žiadnu sumu a Elowen nemal pre model cenu, ani cenu z katalógu, ani cenu pre daný model. Cena, ktorú Elowen pre model má, je odhad a suma, ktorú hlási sám poskytovateľ, má prednosť, vrátane hlásenej $0.

Volanie čaká až dve minúty. Ak beh trvá dlhšie, dostanete 202 s { "conversationId": "…", "reply": null, "usage": null }. Beh pokračuje ďalej a jeho odpoveď pristane v tejto konverzácii; pri dlhej práci radšej streamujte.

Streamujte beh

curl -sSN "$ELOWEN_URL/api/v1/agent/runs" \
  -H "Authorization: Bearer $ELOWEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Check the open pull requests","stream":true}'

Odpoveď má typ text/event-stream. Každá udalosť má názov a riadok data s JSON:

event: start
data: {"conversationId":"brain-12-…"}

event: tool
data: {"phase":"start","id":"t1","name":"Bash","detail":"gh pr list"}

event: tool
data: {"phase":"end","id":"t1","ok":true}

event: delta
data: {"text":"There are three open"}

event: delta
data: {"text":" pull requests…"}

event: final
data: {"conversationId":"brain-12-…","reply":"There are three open pull requests…","usage":{"tokens":2210,"costUsd":0.019}}

Ak sa odpojíte, beh pokračuje ďalej a jeho odpoveď pristane v konverzácii.

Konverzácie

Každé spustenie v odpovedi uvádza conversationId, ktoré použilo. Pošlite ho späť a budete pokračovať v tej istej konverzácii, s jej históriou a kontextom:

curl -sS "$ELOWEN_URL/api/v1/agent/runs" \
  -H "Authorization: Bearer $ELOWEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Open an issue for the second one","conversationId":"brain-12-…"}'

• Bez conversationId každé spustenie začne novú konverzáciu.
• Môžete pokračovať v ktorejkoľvek svojej konverzácii, vrátane tých, ktoré ste začali vo webovej aplikácii. Konverzácia iného účtu alebo neexistujúci identifikátor dostane 404 {"error":"unknown conversation"}.
• Konverzácia spracúva vždy jeden beh. Spustenie do konverzácie, ktorá už pracuje — či už na inom spustení, alebo na správe napísanej vo webovej aplikácii — sa odmietne s 409 {"error":"conversation_busy"} a nič sa nezapočíta. Počkajte, kým druhý beh skončí, a pošlite požiadavku znova, alebo začnite novú konverzáciu.
• Spustenia cez API nikdy nemenia, ktorú konverzáciu vaša webová aplikácia alebo CLI otvorí.
• Konverzácie z API sa v histórii konverzácií zobrazujú ako každá iná.

Modely

Vypíšte modely, ktoré môžete použiť

curl -sS "$ELOWEN_URL/api/brain/models" -H "Authorization: Bearer $ELOWEN_TOKEN"

[
  { "provider": "anthropic", "providerLabel": "Anthropic", "model": "claude-sonnet-4-5", "exec": "anthropic/claude-sonnet-4-5", "contextWindow": 200000, "…": "…" }
]

Zoznam obsahuje len modely, ktoré váš účet smie používať. Hodnota exec, <provider>/<model>, je to, čo odovzdáte pri výbere modelu.

Vyberte model pre jedno spustenie

Pridajte do spustenia model. Konverzácia sa na tento model prepne pred začiatkom behu a zostane na ňom aj pre ďalšie spustenia:

curl -sS "$ELOWEN_URL/api/v1/agent/runs" \
  -H "Authorization: Bearer $ELOWEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Review this diff","model":"anthropic/claude-sonnet-4-5"}'

Prepnite model konverzácie

POST /api/brain/model prepne existujúcu konverzáciu rovnako ako výber modelu vo webovej aplikácii. Konverzáciu vždy odovzdávajte ako session; bez neho sa prepnutie použije na konverzáciu, ktorú má webová aplikácia otvorenú.

curl -sS "$ELOWEN_URL/api/brain/model" \
  -H "Authorization: Bearer $ELOWEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-4-5","session":"brain-12-…"}'

{ "model": "claude-sonnet-4-5" }

Obe cesty sa riadia rovnakými pravidlami ako webová aplikácia. Model, ktorý nesmiete používať, alebo ten, ktorý nemôže túto konverzáciu prevziať, dostane 409 s rovnakou chybovou správou, akú zobrazuje webová aplikácia, a žiadny beh neprebehne.

Chyby

Každé telo chyby je JSON s poľom error.

Odmietnutia limitom

429 vždy nesie Retry-After, počet sekúnd, ktoré treba počkať, a reason, s ktorým môže skript pracovať:

Keď je naraz dosiahnutých viac limitov nákladov, odpoveď uvádza širšie okno: mesiac pred dňom, takže Retry-After je čas, kedy spustenie skutočne môže uspieť.

curl -sS -D - "$ELOWEN_URL/api/v1/agent/runs" \
  -H "Authorization: Bearer $ELOWEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"One more"}'

HTTP/1.1 429 Too Many Requests
Retry-After: 52380
Content-Type: application/json

{"error":"limit_exhausted","reason":"daily_cost"}

Spustenie odmietnuté limitom nič nevytvorí: žiadnu konverzáciu, žiadny beh, a nič sa nezapočíta do behov tokenu. Ani spustenie odmietnuté ako conversation_busy, pre neznámu konverzáciu či model alebo preto, že jeho beh nemohol začať, sa nepočíta.