Agent API

API agenta umožňuje vašim skriptům, úlohám CI a nástrojům komunikovat s agentem přes HTTP. Ověříte se osobním API tokenem, pošlete zprávu a odpověď dostanete buď po dokončení běhu, nebo průběžně streamovanou. Vše, co spuštění provede, je běžný běh konverzace: stejné nástroje, oprávnění, Projekty a účtování spotřeby jako u zprávy napsané ve webové aplikaci.

Příklady používají https://elowen.example.com; nahraďte ji adresou, na které Elowen otevíráte. Všechny cesty vedou přes stejného hostitele pod /api.

Osobní API tokeny

Token jedná za vás. Má přesně takový přístup, jaký má váš účet, včetně práv administrátora, takže s ním zacházejte jako s heslem.

Vytvořte token

1. Otevřete Účet → API tokeny.
2. Vyberte Nový token, zadejte název, který později poznáte, a případně zvolte poslední den, kdy má token fungovat. Necháte-li datum prázdné, token funguje, dokud jej neodstraníte. Přestane fungovat na konci zvoleného dne v UTC.
3. Zkopírujte token z okna, které se otevře. Zobrazí se jen jednou. Elowen ukládá jeho otisk, ne token samotný, takže jej už nikdo nemůže zobrazit. Pokud jej ztratíte, vyberte v řádku tokenu Kopírovat a v dialogu potvrďte Vytvořit novou hodnotu. Token dostane zcela novou hodnotu, která se zobrazí jednou a uloží se do schránky. Vše, co dál používá starou hodnotu, okamžitě přestane fungovat; název, limity a zaznamenané využití zůstanou.

Každý token začíná na elw_, takže uniklý token snadno poznáte v protokolu nebo ve vloženém textu. Účty chatbotů tokeny mít nemohou.

Řádek Volání agenta pod kartou tokenů zkopíruje hotový příklad curl pro endpoint spuštění, s už vyplněnou adresou vaší instance Elowen.

Využití a limity

Tokeny najdete v jedné kartě, každý na vlastním řádku, s posledním použitím, platností a prefixem a s tlačítky Kopírovat, Limity a Odstranit. Otevřením řádku zobrazíte běhy tokenu, zodpovězené i nezdařené běhy a náklady za den, a také limity, podle kterých token běží. Náklady se počítají pro období, které zvolíte vedle grafu; zvolené období pak platí pro všechny tokeny. Dny se počítají v UTC.

Výběrem Limity dáte tokenu strop. Každý limit je nepovinný a každý má vlastní přepínač Bez omezení:

Pokud běh spotřeboval tokeny a nic je neocenilo — poskytovatel nehlásil žádnou částku a Elowen neměl pro model cenu (žádný záznam v katalogu ani nastavenou cenu pro daný model) — jsou náklady toho dne neznámé. Elowen nikdy nepovažuje neznámé za nulu: token ukazuje Cena neznámá a token s denním limitem nákladů se odmítá do konce toho dne v UTC, token s měsíčním limitem do konce toho měsíce v UTC. Limit nákladů počítá, co běhy už spotřebovaly, takže běhy, které stále probíhají, když se spouští nový, mohou den nebo měsíc mírně překročit.

Pokud se Elowen restartuje během spuštění, toto spuštění se počítá jako nezdařené a jeho útratu už nelze tokenu připsat. Den, kdy začalo, a den restartu se pak počítají jako neznámé náklady, takže token s denním limitem nákladů se odmítá do konce těchto dnů v UTC a token s měsíčním limitem do konce měsíců, do kterých tyto dny patří.

Odstraňte token

V řádku tokenu vyberte Odstranit. Vše, co jej používá, okamžitě přestane fungovat a zaznamenané využití se smaže. Smazáním účtu se smažou i všechny vaše tokeny.

Co token neumí

Token se nemůže odhlásit, změnit vaše heslo, vydávat se za jiný účet ani vytvářet, upravovat, obnovovat či odstraňovat tokeny, včetně sebe sama. To vyžaduje vaše přihlášení ve webové aplikaci a API na takové požadavky odpovídá 403.

Ověřování

Token posílejte v hlavičce Authorization u každého požadavku:

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"

Chybějící, neznámý, smazaný nebo propadlý token dostane 401 {"error":"unauthorized"}. Totéž se stane poté, co tokenu vytvoříte novou hodnotu: stará hodnota je od té chvíle mrtvá.

Spusťte agenta

POST /api/v1/agent/runs pošle jednu zprávu a spustí jeden běh agenta.

Počkejte na odpověď

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, když spuštění nic neocenilo: poskytovatel nehlásil žádnou částku a Elowen neměl pro model cenu, ani cenu z katalogu, ani cenu pro daný model. Cena, kterou Elowen pro model má, je odhad, a částka, kterou hlásí sám poskytovatel, má přednost, včetně hlášené $0.

Volání čeká až dvě minuty. Pokud běh trvá déle, dostanete 202 s { "conversationId": "…", "reply": null, "usage": null }. Běh pokračuje dál a jeho odpověď přistane v této konverzaci; u dlouhé práce raději streamujte.

Streamujte běh

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}'

Odpověď má typ text/event-stream. Každá událost má název a řádek 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}}

Pokud se odpojíte, běh pokračuje dál a jeho odpověď přistane v konverzaci.

Konverzace

Každé spuštění v odpovědi uvádí conversationId, které použilo. Pošlete jej zpět a budete pokračovat ve stejné konverzaci, s její historií a kontextem:

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é spuštění začne novou konverzaci.
• Můžete pokračovat v kterékoli své konverzaci, včetně těch, které jste začali ve webové aplikaci. Konverzace jiného účtu nebo neexistující identifikátor dostane 404 {"error":"unknown conversation"}.
• Konverzace zpracovává vždy jeden běh. Spuštění do konverzace, která už pracuje — ať na jiném spuštění, nebo na zprávě napsané ve webové aplikaci — se odmítne s 409 {"error":"conversation_busy"} a nic se nezapočítá. Počkejte, až druhý běh skončí, a pošlete požadavek znovu, nebo začněte novou konverzaci.
• Spuštění přes API nikdy nemění, kterou konverzaci vaše webová aplikace nebo CLI otevře.
• Konverzace z API se v historii konverzací zobrazují jako každá jiná.

Modely

Vypište modely, které můžete použít

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, "…": "…" }
]

Seznam obsahuje jen modely, které váš účet smí používat. Hodnota exec, <provider>/<model>, je to, co předáte při výběru modelu.

Vyberte model pro jedno spuštění

Přidejte do spuštění model. Konverzace se na tento model přepne před začátkem běhu a zůstane na něm i pro další spuštění:

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"}'

Přepněte model konverzace

POST /api/brain/model přepne existující konverzaci stejně jako výběr modelu ve webové aplikaci. Konverzaci vždy předávejte jako session; bez něj se přepnutí použije na konverzaci, kterou má webová aplikace otevřenou.

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" }

Obě cesty se řídí stejnými pravidly jako webová aplikace. Model, který nesmíte používat, nebo ten, který nemůže tuto konverzaci převzít, dostane 409 se stejnou chybovou zprávou, jakou ukazuje webová aplikace, a žádný běh neproběhne.

Chyby

Každé tělo chyby je JSON s polem error.

Odmítnutí limitem

429 vždy nese Retry-After, počet sekund, které je třeba počkat, a reason, se kterým může skript pracovat:

Když je najednou dosaženo více limitů nákladů, odpověď uvádí širší okno: měsíc před dnem, takže Retry-After je čas, kdy spuštění skutečně může uspět.

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"}

Spuštění odmítnuté limitem nic nevytvoří: žádnou konverzaci, žádný běh, a nic se nezapočítá do běhů tokenu. Ani spuštění odmítnuté jako conversation_busy, kvůli neznámé konverzaci či modelu nebo proto, že jeho běh nemohl začít, se nepočítá.