# Aracı Düzenleme

Queuety; kalıcı durum, yeniden denemeler, inceleme ve açık bekleme semantiğinden ödün vermeden uyarlanabilir iş istediğiniz aracı sistemleri için uygundur.

Çoğu ajan akışı için çalışma zamanında düzenlenebilen bir DAG motoruna ihtiyacınız yoktur. Uygulamada çoğu sistem, az sayıda kalıcı orkestrasyon adımıyla modellenebilir. `for_each()` işleri tek bir iş akışı çalıştırmasının içinde genişletir. `start_agents()` ve `wait_for_agents()`, çalışma zamanında keşfedilen işleri bağımsız üst düzey iş akışlarına devreder. `wait_for_decision()` ve `wait_for_input()` insan denetimi için duraklatır. `wait_for_workflow()`, `wait_for_workflows()` ve `wait_for_agent_group()`, bir üst düzey çalıştırmanın başka bir çalıştırmayı veya başlatılmış bir yeter sayıyı beklemesini sağlar.

## Yararlı bir zihinsel model

Ajan orkestrasyonunu katmanlar halinde düşünmek en kolayıdır. Bir planlayıcı hangi işlerin yapılacağını belirler. Queuety bu işleri kalıcı görevlere veya iş akışlarına dönüştürür. Uzman çalıştırmalar sonuç üretir ve yapıtları saklar. Denetleyici bir aşama bu sonuçları bir araya getirir ve sırada ne olacağına karar verir. Herhangi bir noktada, devam etmeden önce bir kişi çalıştırmayı onaylayabilir, reddedebilir veya düzeltebilir.

Önemli ayrım şudur: hangi işin yapılacağına ajan karar verir, ancak bu işin nasıl kalıcı hale getirileceğine, yeniden deneneceğine, sürdürüleceğine ve bir araya getirileceğine yine Queuety karar verir. Orkestrasyon hedefi sınırlı bir çalıştırma yerine uzun ömürlü bir oturumsa, bunu [Durum Makineleri](https://queuety.inline0.dev/tr/docs/state-machines) ile birlikte kullanın.

## Örüntü 1: Bağımsız ajan çalıştırmalarıyla planlayıcı/yürütücü

Planlayıcı adımı çalışma zamanında görevler keşfediyorsa ve her görev kendi üst düzey iş akışına dönüşmeliyse `start_agents()` kullanın.

```php
use Queuety\Enums\WaitMode;
use Queuety\Queuety;

$agent_run = Queuety::workflow( 'agent_run' )
    ->then( FetchSourcesStep::class )
    ->then( DraftFindingStep::class );

Queuety::workflow( 'brief_research' )
    ->version( 'brief-research.v1' )
    ->idempotency_key( 'brief:42:research' )
    ->max_transitions( 20 )
    ->then( PlanResearchTasksStep::class )
    ->start_agents( 'agent_tasks', $agent_run, group_key: 'researchers' )
    ->wait_for_agent_group( 'researchers', WaitMode::Quorum, 2, 'agent_results' )
    ->then( SynthesizeBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );
```

Bu örüntüde `PlanResearchTasksStep`, çalışma zamanında keşfedilen öğeleri `$state['agent_tasks']` içine yazar, `start_agents()` her görev için kalıcı bir iş akışı başlatır ve `wait_for_agent_group()` seçilen tamamlanma koşulu karşılanana kadar üst iş akışını bekletir. Ardından `SynthesizeBriefStep`, tamamlanan alt iş akışı durumlarını `$state['agent_results']` altında alır.

Bu, planlayıcı/yürütücü sistemleri için en iyi başlangıç noktasıdır; çünkü her ajan çalıştırması ayrı ayrı incelenebilir ve yeniden denenebilir.

## Örüntü 2: Çalıştırma devam etmeden önce insan incelemesi

İş akışının gerçek bir evet-hayır kararı için durması gerekiyorsa `wait_for_decision()`, operatörün çalıştırmaya yapılandırılmış geri bildirim göndermesi gerekiyorsa `wait_for_input()` kullanın.

```php
use Queuety\Queuety;

$workflow_id = Queuety::workflow( 'brief_review' )
    ->then( DraftBriefStep::class )
    ->wait_for_decision( result_key: 'review' )
    ->then( HandleReviewDecisionStep::class )
    ->wait_for_input( result_key: 'revision_notes' )
    ->then( ApplyRevisionNotesStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );
```

İnceleyen kişi onaylarsa:

```php
Queuety::approve_workflow(
    $workflow_id,
    [
        'reviewer' => 'editor@example.com',
        'notes' => 'Looks good, publish after legal check',
    ],
    'approved'
);
```

İnceleyen kişi reddederse:

```php
Queuety::reject_workflow(
    $workflow_id,
    [
        'reviewer' => 'editor@example.com',
        'reason' => 'Needs citations and a stronger conclusion',
    ],
    'rejected'
);
```

`wait_for_decision()` sonrasında iş akışı; nihai sonucu, çalıştırmayı sürdüren sinyali ve inceleyenin ilettiği tüm verileri içeren yapılandırılmış bir yük alır. Böylece çalıştırma beklerken PHP sürecini açık tutmadan gerçek bir insan denetimli kontrol noktası elde edersiniz.

## Örüntü 3: Bir üst düzey iş akışının diğerini beklemesi

Bazen en temiz model, tek ve dev bir iş akışı değildir. Bir iş akışı araştırmayı tamamlayabilir; başka bir iş akışı ise sonraki aşamayı başlatmadan önce bunu bekleyebilir.

```php
use Queuety\Enums\WaitMode;
use Queuety\Queuety;

$research_id = Queuety::workflow( 'research_brief' )
    ->then( PlanResearchTasksStep::class )
    ->start_agents( 'agent_tasks', $agent_run )
    ->wait_for_agents( mode: WaitMode::All, result_key: 'agent_results' )
    ->then( SynthesizeBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

Queuety::workflow( 'publish_brief' )
    ->wait_for_workflow( $research_id, 'research' )
    ->wait_for_decision( result_key: 'editor_review' )
    ->then( PublishBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );
```

Bu, araştırma aşaması ile yayın aşaması arasında kalıcı bir sınır oluşturur. Her çalıştırmanın kendi operasyonel yaşam döngüsü vardır, ancak bağımlılık tamamlandığında ikinci iş akışı yine otomatik olarak devam eder.

## Doğru temel yapı taşını seçme

İş tek bir iş akışı çalıştırmasının içinde yer alıyorsa ve dallar aslında ortak bir durum kümesi üzerinde adım düzeyinde paralel yürütmeden ibaretse `for_each()` doğru araçtır.

Keşfedilen her görev kendi kalıcı üst düzey çalıştırması olmalıysa ve bu çalıştırmaları ayrı ayrı incelemek, yeniden denemek veya dışa aktarmak istiyorsanız `start_agents()` daha uygundur.

Bir üst düzey iş akışı başka bir üst düzey iş akışına bağlıysa ve bu orkestrasyon katmanları arasında kalıcı, eşzamansız koordinasyon istiyorsanız `wait_for_workflow()` ve `wait_for_workflows()` uygun seçimdir.

İş akışı, çalışan kapasitesini tüketmeden duraklatılmış halde kalırken bir kişinin çalıştırmayı onaylaması, reddetmesi veya yönlendirmesi gereken noktalarda `wait_for_decision()` ve `wait_for_input()` kullanılır.

## Önerilen durum düzenleri

Durum anahtarları öngörülebilir olduğunda ajan sistemlerinde hata ayıklamak kolaylaşır. Uygulamada `agent_tasks` planlayıcı çıktısı, `agent_workflow_ids` başlatılan üst düzey çalıştırmalar, `agent_results` tamamlanan alt iş akışı durumu, `review` veya `decision` ise onay ya da ret yükleri için işe yarar. Taslaklar, atıflar veya araştırma manifestoları gibi daha büyük çıktılar genellikle ana iş akışı durum kümesi yerine yapıt deposunda tutulmalıdır.

## Ajan çalıştırmaları için önerilen korumalar

Ajan iş akışları, doğaları gereği dinamik olduklarından, neredeyse diğer tüm kullanım alanlarından daha fazla korumadan yararlanır.

```php
Queuety::workflow( 'agent_research' )
    ->version( 'agent-research.v2' )
    ->idempotency_key( 'brief:42:agent-research' )
    ->max_transitions( 20 )
    ->max_for_each_items( 12 )
    ->max_state_bytes( 32768 );
```

Bu denetimler, üretim ortamında önem taşıyan pratik sorulara yanıt verir: Bir çalıştırmayı hangi tanım sürümünün ürettiği, yinelenen harici isteklerin çalıştırmayı iki kez başlatıp başlatamayacağı, bir planlayıcının çok fazla dal oluşturup oluşturamayacağı ve iş akışı durumunun sınırsız büyüyüp büyüyemeyeceği. Çoğu ajan sistemi için çalışan sayılarını veya kuyruk yapısını ayarlamadan önce bu korumalarla başlayın.

## Ayrıca bkz.

- [Örnekler](https://queuety.inline0.dev/tr/docs/examples)
- [Eylem Tetikleyicileri](https://queuety.inline0.dev/tr/docs/features/action-triggers)
- [Dinamik For-Each](https://queuety.inline0.dev/tr/docs/workflows/for-each)
- [Eşzamansız Devirler](https://queuety.inline0.dev/tr/docs/workflows/async-handoffs)
- [İş Akışı Bağımlılıkları](https://queuety.inline0.dev/tr/docs/workflows/dependencies)
- [Yapıtlar](https://queuety.inline0.dev/tr/docs/features/artifacts)
- [İş Akışı Sinyalleri](https://queuety.inline0.dev/tr/docs/workflows/signals)
- [İş Akışı Korumaları](https://queuety.inline0.dev/tr/docs/workflows/guardrails)