GNL
Dokümanlar menüsü
Core · Ücretsiz@gnldev/durable

Agent kayıt defteri (createGnl)

Agent'ları, araçları ve workflow'ları tek yapılandırmada tanımlayıp durable çalıştıran merkezi giriş; sunucu ve Studio hep bu registry'yi tüketir.

Ne işe yarar / ne zaman kullanılır#

createGnl, bir uygulamadaki tüm agent'ları, ortak araçları ve workflow'ları tek bir yapılandırma nesnesinde toplar ve isimle çağrılabilen durable bir çalıştırıcıya dönüştürür. Storage (journal) bu yapılandırmaya bağlıdır; dönen gnl nesnesi hem doğrudan kod içinden (gnl.run(...)) hem de createRestApi ve createStudioApp üzerinden aynı şekilde kullanılır.

Somut senaryo: bir Star Wars ansiklopedisi ajanı kurmak istiyorsunuz — model, sistem promptu ve araçlarıyla birlikte tek yerde tanımlanır; hem REST API hem Studio bu tanımı okuyarak aynı agent'ı çalıştırır, sonuçları aynı journal'a yazar.

Kurulum / import#

Ana export @gnldev/durable paketinden gelir. Depolama için alt-export gerekir (kök pakette değil) — SQLite kullanacaksanız @gnldev/durable/sqlite'tan SqliteStorage'ı içe aktarın.

import
import { SqliteStorage } from '@gnldev/durable/sqlite';
import { createGnl, toJournal } from '@gnldev/durable';
import type { CreateGnlConfig } from '@gnldev/durable';

Adım adım kullanım#

1) Storage'ı kurun, 2) agent'ları agents altında tanımlayın (model, system, tools, maxSteps), 3) createGnl(config) ile registry'yi oluşturun, 4) gnl.run(ad, opts) ile bir runId altında çalıştırın.

swapi-free/src/index.ts (gerçek kullanım)
const storage = new SqliteStorage(process.env.DB_PATH ?? 'swapi-free.db');
const config: CreateGnlConfig = {
  storage,
  agents: {
    starwars: { model: buildModel(), system: SYSTEM, tools: makeSwapiTools(), maxSteps: 4 },
  },
};

const gnl = createGnl(config);
await gnl.run('starwars', { runId: 'demo-1', prompt: 'Who is Luke Skywalker?' });

Aynı config nesnesi REST API ve Studio'ya da verilir — üçü aynı journal ve aynı agent tanımını paylaşır:

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

app.route('/studio', createStudioApp({
  reader: toJournal(storage.runs),
  apiBase: '/studio',
  gnl: createStudioRunner(gnl, config, { toJsonSchema: aiToolSchema }),
  auth,
}));

gnl.run'a verilen runId aynı zamanda exactly-once ve resume garantisinin anahtarıdır: aynı runId ile tekrar çağrılırsa run kaldığı yerden devam eder (bkz. deterministik replay).

API referansı#

fncreateGnl

Yapılandırmadan { agent, run, stream, listWorkflows, runWorkflow } döner — bir uygulamanın tüm agent/workflow yüzeyi.

typeCreateGnlConfig

storage veya journal, agents (Record<isim, AgentConfig>), tools, memory/memoryFactory, processors, workflows alanları.

typeAgentConfig

model, tools, system, guard, maxSteps, processors, agents (alt-agent adları), scorers — hepsi DynamicArg olabilir.

typeRunOptions

gnl.run/gnl.stream parametreleri: runId, prompt|messages, threadId, resourceId, approvals, context, model/temperature/topP/system override.

typeRequestContext

İstek bağlamı (org/rol/kullanıcı) — DynamicArg fonksiyonlarına geçilir.

typeDynamicArg<T>

Sabit değer VEYA RequestContext alan bir fonksiyon — model/system/tools için kullanılır.

typeWorkflowLike

config.workflows altında kayıtlı workflow'ların yapısal arayüzü (build/run/runResumable).

fncreateAgentTool

AgentConfig.agents ile listelenen alt-agent'ları agent_<ad> tool'una çeviren dahili yardımcı (agent-as-tool).

Sub-agent ağı
Bir agent'ın agents alanına başka kayıtlı agent isimleri verirseniz, her biri otomatik olarak agent_&lt;ad&gt; adlı bir araç olarak sunulur (handoff); bu, iki seviyeli journal ile exactly-once çalışır.
Varsayılan
maxSteps verilmezse 12 adım kullanılır (stepCountIs). model tek bir değer yerine bir dizi olarak verilirse, otomatik olarak deterministik model fallback zincirine döner (bkz. Model yönlendirme & yedekleme).

İlgili konular#