# Orkestrasi Agen

Queuety cocok untuk sistem agen ketika Anda menginginkan pekerjaan adaptif tanpa mengorbankan status persisten, percobaan ulang, inspeksi, dan semantik penantian yang eksplisit.

Anda tidak memerlukan mesin DAG yang dapat diedit saat runtime untuk sebagian besar alur agen. Dalam praktiknya, sebagian besar sistem dapat dimodelkan dengan sejumlah kecil mekanisme orkestrasi persisten. `for_each()` mengembangkan pekerjaan di dalam satu proses alur kerja. `start_agents()` dan `wait_for_agents()` menyerahkan pekerjaan yang ditemukan saat runtime ke alur kerja tingkat atas yang independen. `wait_for_decision()` dan `wait_for_input()` menjeda proses untuk kendali manusia. `wait_for_workflow()`, `wait_for_workflows()`, dan `wait_for_agent_group()` memungkinkan satu proses tingkat atas menunggu proses lain atau kuorum yang telah dimulai.

## Model mental yang berguna

Orkestrasi agen paling mudah dipahami jika dibagi menjadi beberapa lapisan. Perencana menentukan pekerjaan yang ada. Queuety mengubah pekerjaan itu menjadi job atau alur kerja persisten. Proses spesialis menghasilkan hasil dan menyimpan artefak. Tahap pengawasan menggabungkan hasil tersebut dan menentukan langkah berikutnya. Kapan pun, manusia dapat menyetujui, menolak, atau mengoreksi proses sebelum dilanjutkan.

Perbedaan pentingnya adalah agen menentukan pekerjaan yang harus dilakukan, tetapi Queuety tetap menentukan cara pekerjaan itu disimpan, dicoba ulang, dilanjutkan, dan digabungkan. Jika sasaran orkestrasi adalah sesi berumur panjang, bukan proses terbatas, padukan ini dengan [Mesin Status](https://queuety.inline0.dev/id/docs/state-machines).

## Pola 1: Perencana/pelaksana dengan proses agen independen

Gunakan `start_agents()` ketika langkah perencana menemukan tugas saat runtime dan setiap tugas harus menjadi alur kerja tingkat atas tersendiri.

```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 ] );
```

Dalam pola ini, `PlanResearchTasksStep` menulis item yang ditemukan saat runtime ke `$state['agent_tasks']`, `start_agents()` men-dispatch satu alur kerja persisten untuk setiap tugas, dan `wait_for_agent_group()` menahan proses induk hingga kondisi penyelesaian yang dipilih terpenuhi. `SynthesizeBriefStep` kemudian menerima status anak yang telah selesai di bawah `$state['agent_results']`.

Ini adalah titik awal paling sederhana untuk sistem perencana/pelaksana karena setiap proses agen tetap dapat diperiksa dan dicoba ulang secara mandiri.

## Pola 2: Peninjauan manusia sebelum proses dilanjutkan

Gunakan `wait_for_decision()` ketika alur kerja harus berhenti untuk keputusan ya atau tidak yang nyata, dan `wait_for_input()` ketika operator perlu mengirim masukan terstruktur kembali ke proses.

```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 ] );
```

Jika peninjau menyetujui:

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

Jika peninjau menolak:

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

Setelah `wait_for_decision()`, alur kerja menerima payload terstruktur berisi hasil akhir, sinyal yang melanjutkan proses, serta data peninjau apa pun yang menyertainya. Ini memberi Anda titik pemeriksaan dengan keterlibatan manusia yang sesungguhnya tanpa membiarkan proses PHP tetap terbuka saat alur kerja menunggu.

## Pola 3: Satu alur kerja tingkat atas menunggu alur kerja lain

Terkadang model paling sederhana bukan satu alur kerja raksasa. Satu alur kerja dapat menyelesaikan riset, lalu alur kerja lain dapat menunggunya sebelum memulai tahap berikutnya.

```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 ] );
```

Dengan begitu, ada batas persisten antara tahap riset dan tahap publikasi. Setiap proses memiliki siklus operasionalnya sendiri, tetapi alur kerja kedua tetap dilanjutkan secara otomatis saat dependensinya selesai.

## Memilih primitif yang tepat

`for_each()` adalah alat yang tepat ketika pekerjaan berada di dalam satu proses alur kerja dan cabangnya sebenarnya hanya eksekusi paralel pada tingkat langkah dengan satu wadah status bersama.

`start_agents()` lebih tepat ketika setiap tugas yang ditemukan harus menjadi proses tingkat atas persisten tersendiri dan Anda ingin memeriksa, mencoba ulang, atau mengekspor proses tersebut secara terpisah.

`wait_for_workflow()` dan `wait_for_workflows()` cocok ketika satu alur kerja tingkat atas bergantung pada alur kerja tingkat atas lainnya dan Anda menginginkan koordinasi asinkron yang persisten di antara lapisan orkestrasi tersebut.

`wait_for_decision()` dan `wait_for_input()` tepat digunakan ketika manusia perlu menyetujui, menolak, atau mengarahkan proses sementara alur kerja tetap dijeda tanpa memakai kapasitas worker.

## Konvensi status yang disarankan

Sistem agen lebih mudah di-debug jika kunci status dapat diprediksi. Dalam praktiknya, `agent_tasks` cocok untuk keluaran perencana, `agent_workflow_ids` untuk proses tingkat atas yang dimulai, `agent_results` untuk status alur kerja anak yang telah selesai, dan `review` atau `decision` untuk payload persetujuan atau penolakan. Keluaran yang lebih besar seperti draf, sitasi, atau manifes riset biasanya lebih tepat disimpan di penyimpanan artefak daripada di wadah status utama alur kerja.

## Panduan pengaman yang disarankan untuk proses agen

Alur kerja agen membutuhkan panduan pengaman lebih dari hampir semua kasus penggunaan lainnya karena sifatnya dinamis.

```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 );
```

Kontrol tersebut menjawab pertanyaan praktis yang penting dalam produksi: versi definisi mana yang menghasilkan suatu proses, apakah permintaan eksternal duplikat dapat men-dispatch proses dua kali, apakah perencana dapat membuat terlalu banyak cabang, dan apakah status alur kerja dapat tumbuh tanpa batas. Untuk sebagian besar sistem agen, mulailah dengan panduan pengaman tersebut sebelum menyesuaikan jumlah worker atau topologi antrean.

## Lihat juga

- [Contoh](https://queuety.inline0.dev/id/docs/examples)
- [Pemicu Tindakan](https://queuety.inline0.dev/id/docs/features/action-triggers)
- [For-Each Dinamis](https://queuety.inline0.dev/id/docs/workflows/for-each)
- [Serah Terima Asinkron](https://queuety.inline0.dev/id/docs/workflows/async-handoffs)
- [Dependensi Alur Kerja](https://queuety.inline0.dev/id/docs/workflows/dependencies)
- [Artefak](https://queuety.inline0.dev/id/docs/features/artifacts)
- [Sinyal Alur Kerja](https://queuety.inline0.dev/id/docs/workflows/signals)
- [Panduan Pengaman Alur Kerja](https://queuety.inline0.dev/id/docs/workflows/guardrails)