Tool Sistemi

Tool contract'ı

schema CalcResult {
  result: float
}

tool calculate(
  a: float @range(0, 1000000),
  b: float @range(0, 1000000),
  operation: enum["add", "multiply"] @desc("Yapılacak işlem")
) -> CalcResult {
  side_effects: "none"
  cache: true
}

Tool seçenekleri

Tutarlılık kuralları

Direct tool çağrısı

Direct çağrı garantilidir: modelin kararına bağlı değildir, kaynak koda yazdığın yerde ve sırayla çalışır.

agent Flow {
  tools: [text_stats, calculate]

  fn run(text: string) -> Answer {
    stats = tool text_stats({ text: text })

    if stats.words > 3 {
      bonus = tool calculate({ a: stats.words, b: 2, operation: "multiply" })
    }

    ask "İstatistikler: {stats}, bonus: {bonus}" -> Answer
  }
}

• Tool, agent'ın tools listesinde olmalıdır; değilse Agent 'A' does not allow tool 'x' to be called directly.
• Üst düzeyde de çağrılabilir: result = tool calculate({ a: 2, b: 3, operation: "add" })
• Input ve output ayrı ayrı doğrulanır; hata TOOL_INPUT_INVALID / TOOL_OUTPUT_INVALID kodu taşır.
• İki taraf @severity açısından simetrik değildir: output üzerindeki soft kural değeri şerhleyip koşuyu sürdürür, aynı kural input üzerinde yok sayılır ve sert kalır. Tool yan etkili koddur; sözleşmesini ihlal ettiği bilinen veriyle çağrılması, kuralın engellemek için var olduğu şeydir.

Native tool calling

Agent'ın tools listesi, tool'ları aynı zamanda modele görünür kılar. Model bir tool çağırmaya karar verirse runtime bunu çalıştırır ve sonucu geri gönderir.

agent MultiToolWorker {
  model: GPT54Mini
  tools: [text_stats, calculate]
  tool_rate_limit: 2
  tool_concurrency: 2

  fn run() -> FinalResult {
    ask "Her iki tool'u da tam olarak bir kez çağır. text_stats'i text='Luma DSL' ile, calculate'ı a=20, b=22, operation='add' ile çağır. Tool sonuçlarını aldıktan sonra yalnızca geçerli JSON döndür." -> FinalResult
  }
}

Çok turlu akış

  1. istek   → messages + tools + tool_choice: "auto"  (veya zorunlu tool)
                  response_format gönderilmez
        ↓
  2. yanıt   → assistant mesajı + tool_calls[]
        ↓
  3. runtime → her tool call: policy → input doğrulama → çalıştırma → output doğrulama
                (tool_concurrency kadarı eşzamanlı)
        ↓
  4. mesajlar ← assistant(tool_calls) + her tool sonucu için bir tool mesajı
        ↓
  5. istek   → messages + tools + response_format: json_schema (strict)
        ↓
  6. yanıt   → nihai JSON → yerel schema doğrulaması

fn settle(text: string) -> Answer {
  ask "Hesabı kapat: {text}" -> Answer using tool calculate
}

Provider eşlemesi

Bu dönüşüm adapter katmanında otomatik yapılır; .luma tarafında hiçbir şey değişmez.

Limitler

Implementasyon: tool registry

Bir tool'un .luma tarafında contract'ı, host tarafında handler'ı olmalıdır. Handler yoksa program başlamaz:

Error: 'calculate' is not registered in the tool registry.

Handler imzası

export type ToolHandler = (
  input: any,                      // validated input
  signal?: AbortSignal,            // timeout / iptal sinyali
  needs?: Record<string, any>,     // contract'ta bildirilen bağımlılıklar
) => any | Promise<any>;

// tools.ts
export const calculate = async (input, signal, needs) => {
  if (input.operation === "add")      return { result: input.a + input.b };
  if (input.operation === "multiply") return { result: input.a * input.b };
  throw new Error("Unsupported operation");
};

Typed hata fırlatma

schema ToolError {
  code: string
  message: string
  retryable: bool
  details?: any
}

tool db_write(table: string, value: string) -> DbWriteResult {
  side_effects: "write"
  error: ToolError
  retries: 3
  retry_backoff: "exponential"
  idempotent: true
  idempotency_key: request_id
}

import { LumaToolError } from "./src/tool-registry";

throw new LumaToolError({
  code: "DB_TIMEOUT",
  message: "Database timeout oldu",
  retryable: true,          // → retry döngüsü devam eder
  details: { table: input.table },
});

• retryable: true → retries kadar yeniden denenir.
• retryable: false → hem tool retry'ı hem LLM retry döngüsü anında durur.
• error: schema'sı verilmişse fırlatılan hata o schema'ya göre doğrulanır; uymazsa TOOL_ERROR_INVALID.
• Hata nesnesi try/catch değişkenine olduğu gibi aktarılır.

Tool module yükleme

Varsayılan handler'lar src/tool-registry.ts içindedir. Kendi module'ünü iki yolla ekleyebilirsin:

luma program.luma --tool-module ./tools.ts

{
  "tool_modules": [
    {
      "path": "./tools.ts",
      "version": "1.0.0",
      "integrity": "sha256-<base64-sha256>",
      "dependencies": ["node-fetch"],
      "dependency_root": "./vendor"
    }
  ]
}

Kısa biçim de geçerlidir: "tool_modules": ["./tools.ts"]

Export biçimi

Module şu anahtarlardan birini (sırayla aranır) veya doğrudan kendisini object olarak export etmelidir: lumaTools → tools → default → module'ün kendisi. Her değer bir fonksiyon olmalıdır.

export const lumaTools = {
  calculate: (input) => ({ result: input.a + input.b }),
  text_stats: (input) => ({
    characters: input.text.length,
    words: input.text.trim().split(/\s+/).length,
  }),
};

Registry'de aynı isim iki kez tanımlanamaz: Tool registry conflict: calculate.

datasource / query / command (v0.4.0)

Luma tipli veritabanı contract'ını sahiplenir, sürücüyü değil. Üç bildirim — datasource, query, command — sınırı tarif eder; veritabanıyla asıl konuşan ~20 satırlık köprü ise bir tool modülü meselesidir, bilinen bir ad altında dışa açılır:

export const datasources = {
  Warehouse: async (sql, params, signal) => (await pool.query(sql, params)).rows,
};

Bir DB sürücüsü npm paketidir; onu buranın dışında tutmak transpiler'ın sıfır bağımlılık sözünü koruyan şeydir. Köprü yoksa program hiçbir şey çalıştırmadan durur: datasource 'Warehouse' has no registered bridge.

Bildirimlerin kendisi, alan varsayılanları, satır doğrulama garantisi ve eksik transaction yüzeyinin gerekçesi Veri & Entegrasyon sayfasında.

Sandbox politikası

{
  "tool_module_policy": {
    "sandbox": "strict",
    "allow_builtins": ["crypto"],
    "allow_env": false,
    "allow_network": false,
    "max_memory_mb": 256,
    "max_concurrency": 2
  }
}

export const scan = () => ({ count: Bun.spawnSync(["id", "-u"]).stdout.toString().trim().length });

Strict modda her zaman yasak olanlar

• eval(...) ve Function(...) — dinamik kod
• child_process — process spawn
• Proje dizini dışındaki module'lerin yüklenmesi

Güvenlik politikaları

tool_policy

export LUMA_APPROVED_TOOLS="db_write,send_email"

scope ve credential

tool db_write(table: string, value: string) -> DbResult {
  side_effects: "write"
  scope: "db:write"
  credential: "DB_PASSWORD"
}

agent Writer {
  tools: [db_write]
  tool_scopes: ["db:write"]
  tool_policy: "approval"
}

• credential ile bildirilen env değişkeni yoksa tool hiç çalıştırılmaz: Tool 'db_write' is missing credential: DB_PASSWORD.
• scope tanımlıysa ve agent'ın tool_scopes listesinde yoksa: Tool 'db_write' scope access was denied: db:write.
• tool_scopes hiç verilmezse scope kontrolü yapılmaz.

needs ve tool_contexts

needs, tool'un host tarafından sağlanacak bağımlılıklarını bildirir. Bunlar prompt'a veya modele asla girmez; doğrudan handler'ın üçüncü parametresine geçer.

schema Database {
  user: string
  port: int
}

tool db_write(table: string) -> DbResult {
  needs db: Database
  side_effects: "write"
}

{
  "tool_contexts": {
    "db": {
      "user":     { "env": "DB_USER" },
      "password": { "env": "DB_PASSWORD" },
      "port":     { "env": "DB_PORT", "parse": "integer" }
    }
  }
}

Agent tarafında tool_contexts: ["db"] ile hangi context'lerin kullanılabileceği daraltılır. Liste verilmezse tümü serbesttir; boş liste hiçbirine izin vermez. İzin dışı erişim TOOL_CONTEXT_INVALID üretir.

Not: file tabanlı context provider'ı henüz desteklenmiyor; secret'lar için env kullanılmalıdır.

Retry, idempotency, cache

Retry ve backoff

tool http_get(url: string) -> HttpResult {
  error: ToolError
  retries: 3
  retry_backoff: "exponential"
  retry_delay: 100
  timeout: 3000
}

Yalnızca retryable: true hatalar yeniden denenir. İptal sinyali geldiyse retry durur.

Idempotency

tool db_write(request_id: string, value: string) -> DbResult {
  side_effects: "write"
  idempotent: true
  idempotency_key: request_id
  idempotency_ttl_ms: 300000
  retries: 3
  retry_backoff: "exponential"
}

• idempotency_key yalnızca bir input alan yolu olabilir (request_id veya input.request_id); ifade yazılamaz.
• Aynı anahtar + aynı input → handler bir kez çalışır, ikinci çağrı saklanan sonucu döndürür.
• Aynı anahtar + farklı input → TOOL_IDEMPOTENCY_CONFLICT.
• TTL dolduğunda kayıt düşer ve tool yeniden çalışır.

Kalıcı store

{
  "idempotency_store": {
    "backend": "file",
    "path": ".luma-idempotency.json",
    "encryption": "aes-256-gcm"
  }
}

export LUMA_IDEMPOTENCY_KEY="uzun-ve-guvenli-bir-key"

Varsayılan store process-local'dır ("memory"). File store; exclusive lock, ölü process lock kurtarma, versiyonlu zarf ve atomik rename kullanır. Bozuk dosyalar karantinaya alınıp yenisi oluşturulur. Süresi dolan kayıtlar başlangıçta temizlenir.

Cache ve single-flight

tool calculate(a: float, b: float, operation: enum["add", "multiply"]) -> CalcResult {
  side_effects: "none"
  cache: true
}

• Cache anahtarı tool adı + input JSON'udur; process ömrü boyunca yaşar.
• Aynı anahtar için eşzamanlı çağrılar tek bir çalıştırmayı paylaşır (single-flight); telemetry'de single_flight: true görünür.
• Write tool'ları ve needs kullanan tool'lar cache edilemez.

Circuit breaker

agent Resilient {
  tools: [http_get]
  tool_failure_limit: 3
}

Bir agent method çağrısı içinde tool hataları sayılır. Sayaç tool_failure_limit'e ulaştığında hata TOOL_CIRCUIT_OPEN koduna dönüştürülür ve retryable: false olur — böylece bozuk bir bağımlılığa karşı denemeler durur.

Tool çalıştırma sırası

Her tool çağrısı — direct veya native fark etmez — tam olarak şu boru hattından geçer:

   1  registry araması              TOOL_NOT_FOUND
   2  credential kontrolü           TOOL_PERMISSION_DENIED
   3  scope allowlist'i             TOOL_PERMISSION_DENIED
   4  tool_policy: deny_write       TOOL_PERMISSION_DENIED
   5  tool_policy: approval         TOOL_PERMISSION_DENIED
   6  input doğrulaması             TOOL_INPUT_INVALID
   7  needs çözümleme + tip kontrolü TOOL_CONTEXT_INVALID
   8  cache / single-flight araması
   9  idempotency araması           TOOL_IDEMPOTENCY_CONFLICT
  10  handler çalıştırma  (timeout + AbortSignal)
        └─ hata → retryable ise retry/backoff ile 10'a dön   TOOL_TIMEOUT
  11  output doğrulaması            TOOL_OUTPUT_INVALID
  12  cache/idempotency yazımı + telemetry
        └─ hata olduysa: failure sayacı++ → TOOL_CIRCUIT_OPEN

TypeScript tip üretimi

Tool tipi olarak tagged union

Bir tagged by union tanımlı bir schema'dır, dolayısıyla tool'un parametre tipi ya da dönüş tipi olabilir. Girdi olarak etiketlenmiş hâlde gelir — discriminator'ı handler görmeden önce runtime yazar, yani input.doc.kind üzerinde dallanabilirsin. Çıktı olarak yön tersine döner: tag'i senin yerine kimse yazmaz ve çıplak member alanları döndüren handler reddedilir.

schema Invoice {
  invoice_number: string
}

schema Receipt {
  reference: string
}

schema Document = Invoice | Receipt tagged by kind

tool classify(text: string) -> Document {
  side_effects: "none"
}

Error: [TOOL_OUTPUT_INVALID] classify.output.kind must identify a tagged union member.

Üretilen tipler bu zorunluluğu çalışma anında keşfedilmeye bırakmak yerine taşır — union, TypeScript'te discriminated union olur, yani kind'ı unutan handler derlenmez:

export type Document =
  (Invoice & { kind: "Invoice" }) | (Receipt & { kind: "Receipt" });

luma luma/018_direct_tool.luma \
  --generate-tool-types tools.generated.d.ts

Bu bayrak verildiğinde program çalıştırılmaz; yalnızca tip dosyası üretilir.

// Generated by Luma. Do not edit manually.
export type ToolHandler<I, O, N = Record<string, never>> =
  (input: I, signal?: AbortSignal, needs?: N) => O | Promise<O>;

export interface CalcResult {
  result: number;
}

export interface CalculateInput {
  a: number;
  b: number;
  operation: "add" | "multiply";
}

export interface CalculateNeeds {}

export type CalculateHandler = ToolHandler<CalculateInput, CalcResult, CalculateNeeds>;

export interface GeneratedToolModule {
  calculate: CalculateHandler;
}

import type { GeneratedToolModule } from "./tools.generated";

export const tools: GeneratedToolModule = {
  calculate: async (input, signal, needs) => ({
    result: input.operation === "add" ? input.a + input.b : input.a * input.b,
  }),
};

Üretilen dosya programdaki tüm schema'ları, her tool için <Name>Input / <Name>Needs / <Name>Handler tiplerini ve toplu GeneratedToolModule arayüzünü içerir. @desc açıklamaları JSDoc yorumu olarak taşınır.

export const tools: GeneratedToolModule = {
  calculate: (input) => ({
    result: input.a + input.b,
  }),
};

export const tools = {
  calculate: (input: any) => ({
    // schema değişince derleme kırılmaz
    results: input.a + input.b,
  }),
};