Otomatik REST API + OpenAPI + SSE

Elinde zaten bir createGnl yapılandırması (agent'lar + workflow'lar + storage) varsa, bunu dışarıya bir HTTP API olarak açmak için endpoint'leri elle yazman gerekmez. createRestApi config'i okuyup çalıştırma, resume, SSE streaming, run geçmişi ve kullanım (usage) uçlarını otomatik üretir — hepsi runDurable üzerinden aktığı için exactly-once ve durability garantileri bedava gelir.

Tipik senaryo: bir Hono uygulamasına app.route('/api', createRestApi(config, opts)) ile bağlayıp, bir istemciyi (web, CLI, başka bir servis) doğrudan bu uçlara konuşturmak. Auth, çok organizasyonluluk ve bütçe/kota opsiyonel — vermezsen uçlar açık ve tek organizasyonlu çalışır (aşağıda örneklenmiştir).

Paket @gnldev/server; journal/storage için @gnldev/durable ve alt-export'u @gnldev/durable/sqlite kullanılır.

npm install @gnldev/server @gnldev/durable hono

import { Hono } from 'hono';
import { createRestApi } from '@gnldev/server';
import { createGnl } from '@gnldev/durable';
import { SqliteStorage } from '@gnldev/durable/sqlite';

const storage = new SqliteStorage('runs.db');
const config = {
  storage,
  agents: {
    starwars: { model: buildModel(), system: SYSTEM, tools: makeSwapiTools(), maxSteps: 4 },
  },
};

Config hazır olunca createRestApi(config, opts) bir Hono router döner; bunu istediğin bir yola bağlarsın (ör. /api).

const app = new Hono();
app.route('/api', createRestApi(config, { title: 'SWAPI Free', auth }));

// POST /api/agents/starwars/run     {"runId":"demo-1","prompt":"..."}
// POST /api/agents/starwars/stream  -> SSE (text-delta/tool-call/tool-result/interrupt/done)
// GET  /api/usage                   -> token/maliyet raporu

Çalıştırma isteğinde runId zorunludur — bu, exactly-once garantisinin idempotency anahtarıdır; aynı runId ile tekrar POST atarsan tamamlanmış tool çağrıları yeniden çalışmaz.

curl -s -X POST http://localhost:3001/api/agents/starwars/run \
  -H 'content-type: application/json' \
  -d '{"runId":"demo-1","prompt":"Who is Luke Skywalker?"}'

Akış istiyorsan aynı gövdeyle /agents/:name/stream uçuna POST at — yanıt bir SSE akışıdır (text-delta, tool-call, tool-result, interrupt, done event'leri). Bir tool insan onayı için askıya alındıysa (interrupt), aynı runId ile /agents/:name/resume uçuna { runId, approvals } gönderilerek devam ettirilir — girdi (prompt/messages) journal'dan okunur, tekrar vermene gerek yok.

Kullanım/maliyet raporu için GET /usage:

curl -s http://localhost:3001/api/usage
# {"org":null,"usage":{...},"limit":null,"exceeded":false}

Üretilen OpenAPI 3.1 şeması GET /openapi.json üzerinden servis edilir — kayıtlı her agent ve workflow için run/resume/stream yolları otomatik eklenir; bunu Swagger/Redoc gibi araçlara doğrudan verebilirsin.