Agent & Orchestration

Agent anatomisi

agent Reporter(rule: string) {          // constructor parameter
  model: Primary                  // model profile
  role: "{rule}"                 // system role (interpolated)
  temperature: 0
  retry: 2
  tools: [calculate]              // tools exposed to the LLM
  contexts: [document]               // reachable contexts
  uses researcher: Researcher("Belgeden iki bulgu çıkar.")

  fn report(topic: string, document: string) -> Report {
    research = researcher.research(topic, document)
    ask "Araştırmayı rapora dönüştür.\n\nARAŞTIRMA:\n{research}" -> Report
  }
}

reporter = Reporter("Tarafsız ve belgeye sadık yaz.")
result   = reporter.report(topic, document)

Instance oluşturma ve çağırma

first  = Chatbot()          // empty parentheses when there is no constructor parameter
second = Analyst("kural")   // the argument count must match exactly

x = first.answer(question)  // method call — a top-level operation

Aynı agent'tan birden fazla instance oluşturabilirsin; memory_scope: "instance" altında her instance kendi geçmişini tutar.

Method türleri

Bir method'un LLM çağırıp çağırmadığı gövdesinden anlaşılır. Üç kalıp vardır:

1 · Deterministik method

agent Calculator {
  fn add(a: float, b: float) -> Result {
    total = a + b
    return { value: total }
  }
}

Hiç ask yoktur, return ile biter. Gateway'e istek gitmez, .env gerekmez. Dönüş değeri yine de schema'ya göre doğrulanır.

2 · LLM method'u (terminal ask)

agent Analyst {
  fn analyze(text: string) -> Analysis {
    ask "Metni analiz et: {text}" -> Analysis
  }
}

Gövde tek bir ask ile biter ve return içermez. ask'in hedef schema'sı method'un dönüş tipiyle birebir aynı olmalıdır (array-lık dahil: -> Analysis[] ise ask … -> Analysis[]).

3 · Karma method

agent Processor {
  tools: [validate]

  fn run(input: string) -> Final {
    draft      = ask "Ham veriyi çıkar: {input}" -> Draft
    normalized = normalize(draft)                    // pure fn
    checked    = tool validate({ value: normalized }) // direct tool
    result     = ask "Doğrulama sonucu: {checked}" -> Final
    return result
  }
}

ask bir değişkene atandığında return ile birlikte kullanılabilir. Bu kalıpta akışın tamamını sen kurgularsın: LLM çağrısı, deterministik dönüşüm, tool çağrısı ve kontrol akışı serbestçe karışabilir.

karma method içinde izin verilen adımlar:

  ask  →  pure fn  →  tool  →  ask  →  return
   │        │           │         │
   │        │           │         └─ ikinci LLM turu
   │        │           └─ garantili tool çalıştırma
   │        └─ deterministik dönüşüm
   └─ typed LLM çıktısı

  ayrıca: if · else · switch · for · while · break · continue
          try/catch · map · filter · reduce · parallel · dependency çağrısı

ask statement'ı

ask "prompt metni {variable}" -> Schema
x = ask "prompt metni" -> Schema
x = ask "prompt metni" -> Schema retry 3

Retry davranışı

Doğrulama başarısız olduğunda prompt'a hata metni eklenerek yeniden denenir:

<orijinal prompt>

The previous response failed schema validation. Fix the error and return
only valid JSON. Error: Analysis.confidence must be at most 1.

• Toplam deneme sayısı retry + 1'dir (retry: 2 → en fazla 3 istek).
• Her denemenin ayrı bir attempt_id'si vardır; logical_run_id aynı kalır.
• Önceki denemenin hataları sonrakine taşınmaz; her yanıt sıfırdan doğrulanır.
• retryable: false olan model/tool hataları döngüyü anında durdurur (örneğin MODEL_REFUSAL, TOOL_PERMISSION_DENIED).

Modele gönderilen system mesajı

Return only valid JSON matching this schema. Include every required field and
do not add or omit fields: {…üretilen JSON Schema…}
Available context source IDs: ["contract","spec"]. If the output has a field
named sources, use only these IDs.
Agent role: {agent'ın role metni}

Bu mesaj otomatik oluşturulur. Senin role metnin sonuna eklenir; prompt'un ise user mesajı olur. Agent'ta memory açıksa geçmiş mesajlar ikisinin arasına girer.

Union dönüş tipi

Bir method'un dönüş tipi hâlâ tektir. Yeni olan şey, bu tipin bir tagged union olabilmesi — tek bir union tipi birden fazla somut schema'yı kapsar, böylece tek method fatura da fiş de çıkarabilir; çağıran tarafın aralarından seçim yapması gereken iki ayrı method'a bölünmeye gerek kalmaz.

schema Invoice {
  invoice_number: string
}

schema Receipt {
  reference: string
}

schema Document = Invoice | Receipt tagged by kind

agent Extractor {
  fn extract(kind: string, text: string) -> Document {
    switch kind {
      case "Invoice" { ask "Extract the invoice fields:\n{text}" -> Invoice }
      case "Receipt" { ask "Extract the receipt fields:\n{text}" -> Receipt }
      default { ask "Extract whatever you can:\n{text}" -> Invoice }
    }
  }
}

• Her dalın ask'i union'ın herhangi bir üyesini hedefleyebilir; dalların birbiriyle uyuşma zorunluluğu yoktur. Union dışından bir schema reddedilir: Ask schema 'Result' is not a member of tagged union 'Document'.
• Bir ask union'ın kendisini de hedefleyebilir — fn extract(...) -> Document ve terminal ask … -> Document. Bu durumda tek üyeye daraltmıyorsun: modele bütün üyeler gösteriliyor ve yanıtın tag'i hangisini ürettiğini seçiyor. Kodun ne istediğini zaten biliyorsa üye formunu, hangi üyenin geçerli olduğuna karar vermek modelin işiyse union formunu kullan.
• Etiketi senin yerine runtime yazar: terminal ask bir üye ürettiğinde, doğrulamadan hemen önce sonuca discriminator (kind: "Invoice") eklenir.
• Etiket ask'te değil, dönüş sınırında doğar. Üye ask'inden atanan bir değer, dal içindeyken hâlâ üye şeklindedir ve ancak method onu döndürürken union şeklini alır. Dolayısıyla dönüşten önce serileştirilen, loglanan ya da bir tool'a verilen değerin henüz etiketi olmaması meşrudur — orada gerekiyorsa kendin yaz ya da işi dönüşten sonraya taşı.
• match dalındaki bir return aynı şekilde damgalanır; switch dalındaki de case değeri bir member adıysa damgalanır — runtime'a dalın hangi member'ı ürettiğini söyleyen şey case "Invoice"'dır.
• Bunun dışındaki her yerde tag'i sen yazarsın ve parser bunu takip eder. switch'in default dalının, case _ wildcard'ının ve if/else'in iki kolunun member'ı okuyacağı bir şey yoktur; oradaki bir return kind: alanını açıkça yazmalıdır. Yazılmazsa program çalışmadan önce durdurulur:

Error: Tagged union method 'classify' branch return must explicitly return discriminator 'kind'.

Alternatif, member'ı dalın döndürdüğü alanlardan tahmin etmek olurdu; bu da tagged union'ın ortadan kaldırmak için var olduğu dene-gör davranışıdır — o yüzden tahmin reddediliyor ve zorunluluk parse zamanında görünür kılınıyor. Bu özellikle önemli, çünkü aşağıdaki bütünlük kuralı sana zaten bir default ya da else yazdırıyor.

Error: Switch in method extract requires a default branch for tagged union 'Document'.
Error: If in method extract requires an else branch for tagged union 'Document'.

Dal içindeki ask, dalı açan satırda da kendi satırında da yazılabilir; ikisi aynı biçimde ayrıştırılır.

Sonucu tüketmek

Değeri alan taraf onu match ile açar; union'ı somut bir üyeye daraltan tek yapı odur:

agent Router {
  fn route(document: Document) -> Result {
    match document {
      case Invoice invoice { return { value: invoice.invoice_number } }
      case Receipt receipt { return { value: receipt.reference } }
    }
  }
}

match'i çalıştıran method aynı union'ı döndürüyorsa, daldaki return'ün discriminator'ı yazılır — dal zaten üyeyi adlandırmıştır.

Atanmış ask, method'un sonucu değildir

Method'un ürettiği şey yalnızca terminal ask'tir — yani bir değişkene atanmamış olan — ve dönüş tipiyle ölçülen de yalnızca odur. Değişkene atanmış ask ara değerdir: kendi schema'sına göre doğrulanır, sonra gövdede kullanılır; bu yüzden union'a ait olsun olmasın herhangi bir schema'yı hedefleyebilir.

agent Router {
  fn route(text: string) -> Document {
    draft = ask "Classify the document: {text}" -> Draft
    switch draft.kind {
      case "Invoice" { ask "Extract the invoice fields:\n{text}" -> Invoice }
      default { ask "Extract the receipt fields:\n{text}" -> Receipt }
    }
  }
}

Draft, Document'ın üyesi değildir ve olması da gerekmez. Kural union olmadan da aynıdır: Result döndüren bir method'ta draft = ask … -> Draft serbesttir, ama Result üretmeyen terminal dal ask'i şu mesajla reddedilir: Every ask in agent method run must use the method return schema 'Result'; ask 1 uses 'Draft'. — mesaj every dese de atanmış ask'ler hiçbir zaman sayılmaz.

Yapılandırma referansı

Model ve istek

Tool'lar

Bellek

Orchestration ve bütçe

Dependency agent'lar

agent Researcher(instruction: string) {
  contexts: [document]
  role: "{instruction}"

  fn research(topic: string, document: string) -> Research {
    ask "{topic} için belgedeki iki bulguyu çıkar.\n\n{document}" -> Research
  }
}

agent Reporter {
  contexts: [document]
  uses researcher: Researcher("Belgeden iki bulgu çıkar; yeni bilgi ekleme.")

  fn report(topic: string, document: string) -> Report {
    research = researcher.research(topic, document)
    ask "Araştırma sonucunu rapora dönüştür.\n\nARAŞTIRMA:\n{research}" -> Report
  }
}

Memory

agent Chatbot {
  role: "Önceki konuşmayı hatırla."
  memory: true
  memory_scope: "session"
  memory_limit: 6
  memory_retention: 60000
  memory_access: "read_write"

  fn answer(question: string) -> Answer {
    ask "Yeni soru: {question}" -> Answer
  }
}

Scope'lar

Davranış

• Geçmiş, user (prompt) ve assistant (JSON'a çevrilmiş sonuç) mesaj çiftleri olarak tutulur.
• Mesajlar system mesajı ile güncel prompt arasına yerleştirilir.
• memory_limit aşıldığında en eski mesajlar atılır.
• memory_retention süresi boyunca dokunulmayan geçmiş tamamen silinir.
• memory_access: "read_only" geçmişi okur ama yenisini yazmaz.
• persistent geçmiş, method'un terminal ask'i tamamlandıktan sonra dosyaya yazılır.

Context erişim kontrolü

context secret = file("docs/secret.md")
context public = file("docs/public.md")

agent Summarizer {
  contexts: [public]       // only "public" can be interpolated

  fn summarize(public: string) -> Summary {
    ask "Özetle:\n{public}" -> Summary
  }
}

contexts verilmezse tüm context'lere erişim serbesttir. Liste verildiğinde, listede olmayan bir context adını prompt'ta interpole etmeye çalışmak çalışma zamanında hata verir:

Error: Agent context access was denied: secret

Aynı liste, schema'daki sources alanının doğrulanacağı kimlik kümesini de belirler.

Method içinde parallel

schema Bundle {
  first: StatsResult
  second: StatsResult
}

agent Pipeline {
  tools: [text_stats]
  parallel_limit: 2

  fn run(text: string) -> Answer {
    bundle = parallel -> Bundle {
      first  = tool text_stats({ text: text })
      second = tool text_stats({ text: text })
    }

    ask "Sonuçlar: {bundle}" -> Answer
  }
}

• Blok içindeki her adım eşzamanlı çalışır; eşzamanlılık parallel_limit ile sınırlanır.
• Sonuç, adım değişken adlarıyla anahtarlanmış bir nesnedir: { first: …, second: … }.
• -> Schema verilirse toplanan nesne o schema'ya göre doğrulanır.
• Blok içinde ask, tool ve dependency çağrıları kullanılabilir.

Üst düzey parallel: fan-out / fan-in

analyses = parallel -> AnalysisBundle {
  technical = technicalAgent.analyze(topic, document)
  risk      = riskAgent.assess(topic, document)
}

report = editor.combine(analyses)

Seçenekler

x = parallel  on_error …  limit …  timeout …  fan_in …  on_conflict …
              fallback inst.method(…)  merge inst.method(…)  -> Schema {

Örnekler

// Swallow the errors, collect the successes
partial = parallel on_error continue limit 1 {
  good = calc1.add(2, 3)
  bad  = calc2.add("yanlis", 3)
}

// Run a backup agent if everything fails
backed = parallel on_error fallback fallback calc3.add(10, 1) {
  bad = calc2.add("yanlis", 3)
}

// Flat merge + a dedicated fan-in agent
result = parallel fan_in flat on_conflict last merge combiner.combine -> CalcResult {
  first  = calc1.add(2, 3)
  second = calc2.add(7, 8)
}

{ "good": { "result": 5 }, "_errors": { "bad": "add.input.a must be a number." } }

parallel over: veri fan-out'u (v0.4.0)

Yukarıdaki parallel biçimleri bildirilen dallar üzerinde fan-out yapar — yazdığın sabit bir küme. Kardeşi parallel over ise veri üzerinde fan-out yapar, eleman başına bir gövde değerlendirir:

classified = parallel over rows as row limit 4 -> Classified[] {
  result = classifier.classify(row)
  return result
}

Gövde method gövdesi kurallarına uyar — ask, tool çağrıları, match, for — ama parallel over'ın kendisi üst düzey bir operation'dır ve bir agent method'unun içinde yer alamaz. Sahibi olan bir agent'ı yoktur; runtime sentetik bir tane kurar — her elemanın bağımlılıklarını kendi instance key'i altında çözmesinin sebebi de budur. Bu, geçmişi yalnızca varsayılan memory_scope: instance altında izole eder — session, shared ve persistent agent adına göre anahtarlanır, yani onlarda her eleman tek bir geçmişi paylaşır ve limit > 1 sırayı yarışa çevirir.

Kuralların tamamı — girdi sırasında sonuçlar, zorunlu limit, sabit seçenek sırası ve limit'in bir datasource'un pool_max'ıyla etkileşimi — Veri & Entegrasyon sayfasında.

Bütçeler ve limitler

agent Controlled {
  model: Primary
  cost_per_1k_tokens: 0.01
  token_budget: 20000
  cost_budget: 0.50
  orchestration_timeout: 120000
  loop_limit: 50
}

LLM yanıtı döndü
   ↓
usage okundu  (prompt_tokens · completion_tokens · total_tokens · reasoning_tokens)
   ↓
maliyet = total_tokens / 1000 × cost_per_1k_tokens
   ↓
agent bütçe durumu güncellendi
   ↓
token_budget veya cost_budget aşıldı mı?
   ├── evet → MODEL_BUDGET_EXCEEDED  (retryable: false → retry döngüsü durur)
   └── hayır → akış devam eder

• Bütçe kontrolü yanıt alındıktan sonra yapılır: limiti aşan istek çalışır, ama sonraki istek engellenir.
• Bütçe durumu tek bir ask boyunca taşınır; o çağrının her retry denemesi aynı havuzdan harcar. Run policy adayları ayrı havuz alır — escalate hariç, orada tüm merdiven tek havuzu paylaşır.
• cost_per_1k_tokens verilmezse maliyet 0 hesaplanır ve cost_budget hiç tetiklenmez.
• orchestration_timeout method'un tamamını kapsar; aşılırsa Agent 'A.f' orchestration timeout occurred (N ms).