# Ενορχήστρωση agent

Το Queuety ταιριάζει σε συστήματα agent όταν θέλετε προσαρμοστική εργασία χωρίς να χάσετε τη μόνιμη κατάσταση, τις επαναλήψεις, την επιθεώρηση και τη ρητή σημασιολογία αναμονής.

Για τις περισσότερες ροές agent δεν χρειάζεστε μηχανή DAG που να μπορεί να επεξεργάζεται κατά τον χρόνο εκτέλεσης. Στην πράξη, τα περισσότερα συστήματα μπορούν να μοντελοποιηθούν με ένα μικρό σύνολο σταθερών κινήσεων ενορχήστρωσης. Το `for_each()` επεκτείνει την εργασία μέσα σε μία εκτέλεση ροής εργασίας. Τα `start_agents()` και `wait_for_agents()` αναθέτουν εργασίες που εντοπίζονται κατά την εκτέλεση σε ανεξάρτητες ροές εργασίας ανώτατου επιπέδου. Τα `wait_for_decision()` και `wait_for_input()` σταματούν για ανθρώπινο έλεγχο. Τα `wait_for_workflow()`, `wait_for_workflows()` και `wait_for_agent_group()` επιτρέπουν σε μία εκτέλεση ανώτατου επιπέδου να περιμένει κάποια άλλη ή να περιμένει να ξεκινήσει μια ομάδα με απαρτία.

## Ένα χρήσιμο νοητικό μοντέλο

Η ενορχήστρωση agent γίνεται πιο κατανοητή όταν εξετάζεται σε επίπεδα. Ένας σχεδιαστής αποφασίζει ποιες εργασίες υπάρχουν. Το Queuety μετατρέπει αυτές τις εργασίες σε μόνιμες εργασίες ή ροές εργασίας. Οι εξειδικευμένες εκτελέσεις παράγουν αποτελέσματα και αποθηκεύουν τεχνουργήματα. Ένα εποπτικό στάδιο συγκεντρώνει αυτά τα αποτελέσματα και αποφασίζει τι θα γίνει στη συνέχεια. Σε οποιοδήποτε σημείο, ένας άνθρωπος μπορεί να εγκρίνει, να απορρίψει ή να διορθώσει την εκτέλεση πριν συνεχιστεί.

Η σημαντική διάκριση είναι ότι ο agent αποφασίζει ποια εργασία θα εκτελέσει, αλλά το Queuety εξακολουθεί να αποφασίζει πώς αυτή η εργασία αποθηκεύεται, επαναλαμβάνεται, συνεχίζεται και συγκεντρώνεται. Όταν ο στόχος της ενορχήστρωσης είναι μια μακρόβια συνεδρία αντί για μια οριοθετημένη εκτέλεση, συνδυάστε το με τις [Μηχανές καταστάσεων](https://queuety.inline0.dev/el/docs/state-machines).

## Μοτίβο 1: Σχεδιαστής/εκτελεστής με ανεξάρτητες εκτελέσεις agent

Χρησιμοποιήστε το `start_agents()` όταν ένα βήμα σχεδιασμού εντοπίζει εργασίες κατά την εκτέλεση και κάθε εργασία πρέπει να γίνει δική της ροή εργασίας ανώτατου επιπέδου.

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

Σε αυτό το μοτίβο, το `PlanResearchTasksStep` γράφει τα στοιχεία που εντοπίστηκαν κατά την εκτέλεση στο `$state['agent_tasks']`, το `start_agents()` αποστέλλει μία μόνιμη ροή εργασίας ανά εργασία και το `wait_for_agent_group()` θέτει σε αναμονή τη γονική ροή μέχρι να ικανοποιηθεί η επιλεγμένη συνθήκη ολοκλήρωσης. Στη συνέχεια, το `SynthesizeBriefStep` λαμβάνει τις καταστάσεις των ολοκληρωμένων θυγατρικών ροών στην `$state['agent_results']`.

Αυτό είναι το καλύτερο σημείο εκκίνησης για συστήματα σχεδιαστή/εκτελεστή, επειδή κάθε εκτέλεση agent παραμένει επιθεωρήσιμη και μπορεί να επαναληφθεί ανεξάρτητα.

## Μοτίβο 2: Ανθρώπινος έλεγχος πριν συνεχιστεί η εκτέλεση

Χρησιμοποιήστε το `wait_for_decision()` όταν η ροή εργασίας πρέπει να σταματήσει για μια πραγματική απόφαση ναι ή όχι, και το `wait_for_input()` όταν ο χειριστής χρειάζεται να στείλει δομημένη ανατροφοδότηση πίσω στην εκτέλεση.

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

Αν ο ελεγκτής εγκρίνει:

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

Αν ο ελεγκτής απορρίψει:

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

Μετά το `wait_for_decision()`, η ροή εργασίας λαμβάνει ένα δομημένο ωφέλιμο φορτίο με το τελικό αποτέλεσμα, το σήμα που συνέχισε την εκτέλεση και τυχόν δεδομένα του ελεγκτή που το συνόδευαν. Έτσι αποκτάτε ένα πραγματικό σημείο ελέγχου με συμμετοχή ανθρώπου, χωρίς να διατηρείτε μια διεργασία PHP ανοιχτή όσο η εκτέλεση περιμένει.

## Μοτίβο 3: Μία ροή εργασίας ανώτατου επιπέδου περιμένει μια άλλη

Μερικές φορές, το καθαρότερο μοντέλο δεν είναι μία τεράστια ροή εργασίας. Μία ροή εργασίας μπορεί να ολοκληρώσει την έρευνα και μια άλλη να την περιμένει πριν ξεκινήσει το επόμενο στάδιο.

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

Έτσι δημιουργείται ένα σταθερό όριο μεταξύ του σταδίου έρευνας και του σταδίου δημοσίευσης. Κάθε εκτέλεση έχει τον δικό της λειτουργικό κύκλο ζωής, αλλά η δεύτερη ροή εργασίας συνεχίζεται αυτόματα μόλις ολοκληρωθεί η εξαρτώμενη εργασία.

## Επιλογή του κατάλληλου βασικού μηχανισμού

Το `for_each()` είναι το κατάλληλο εργαλείο όταν η εργασία ανήκει σε μία εκτέλεση ροής εργασίας και οι διακλαδώσεις είναι απλώς παράλληλη εκτέλεση σε επίπεδο βημάτων πάνω σε μία κοινόχρηστη κατάσταση.

Το `start_agents()` είναι προτιμότερο όταν κάθε εργασία που εντοπίζεται πρέπει να γίνει δική της μόνιμη εκτέλεση ανώτατου επιπέδου και θέλετε να επιθεωρείτε, να επαναλαμβάνετε ή να εξάγετε αυτές τις εκτελέσεις ξεχωριστά.

Τα `wait_for_workflow()` και `wait_for_workflows()` είναι κατάλληλα όταν μία ροή εργασίας ανώτατου επιπέδου εξαρτάται από μια άλλη και θέλετε μόνιμο ασύγχρονο συντονισμό μεταξύ αυτών των επιπέδων ενορχήστρωσης.

Τα `wait_for_decision()` και `wait_for_input()` ταιριάζουν στα σημεία όπου ένας άνθρωπος χρειάζεται να εγκρίνει, να απορρίψει ή να καθοδηγήσει την εκτέλεση, ενώ η ροή εργασίας παραμένει σε παύση χωρίς να καταναλώνει δυναμικότητα εργατών.

## Προτεινόμενες συμβάσεις κατάστασης

Τα συστήματα agent εντοπίζονται ευκολότερα όταν τα κλειδιά κατάστασης είναι προβλέψιμα. Στην πράξη, το `agent_tasks` είναι κατάλληλο για την έξοδο του σχεδιαστή, το `agent_workflow_ids` για εκτελέσεις ανώτατου επιπέδου που έχουν ξεκινήσει, το `agent_results` για την κατάσταση ολοκληρωμένων θυγατρικών ροών εργασίας και τα `review` ή `decision` για τα ωφέλιμα φορτία έγκρισης ή απόρριψης. Μεγαλύτερες έξοδοι, όπως προσχέδια, παραπομπές ή αρχεία καταγραφής έρευνας, συνήθως ανήκουν στο αποθετήριο τεχνουργημάτων αντί για την κύρια κατάσταση της ροής εργασίας.

## Συνιστώμενα μέτρα προστασίας για εκτελέσεις agent

Οι ροές εργασίας agent ωφελούνται από μέτρα προστασίας περισσότερο από σχεδόν κάθε άλλη περίπτωση χρήσης, επειδή είναι δυναμικές από τη φύση τους.

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

Αυτοί οι έλεγχοι απαντούν στα πρακτικά ερωτήματα που έχουν σημασία στην παραγωγή: ποια έκδοση ορισμού δημιούργησε μια εκτέλεση, αν διπλότυπα εξωτερικά αιτήματα μπορούν να την αποστείλουν δύο φορές, αν ένας σχεδιαστής μπορεί να δημιουργήσει υπερβολικά πολλές διακλαδώσεις και αν η κατάσταση της ροής εργασίας μπορεί να μεγαλώνει χωρίς όριο. Για τα περισσότερα συστήματα agent, ξεκινήστε με αυτά τα μέτρα προστασίας πριν ρυθμίσετε τον αριθμό εργατών ή την τοπολογία των ουρών.

## Δείτε επίσης

- [Παραδείγματα](https://queuety.inline0.dev/el/docs/examples)
- [Ενεργοποιητές ενεργειών](https://queuety.inline0.dev/el/docs/features/action-triggers)
- [Δυναμική επανάληψη για κάθε στοιχείο](https://queuety.inline0.dev/el/docs/workflows/for-each)
- [Ασύγχρονες αναθέσεις](https://queuety.inline0.dev/el/docs/workflows/async-handoffs)
- [Εξαρτήσεις ροών εργασίας](https://queuety.inline0.dev/el/docs/workflows/dependencies)
- [Τεχνουργήματα](https://queuety.inline0.dev/el/docs/features/artifacts)
- [Σήματα ροών εργασίας](https://queuety.inline0.dev/el/docs/workflows/signals)
- [Μέτρα προστασίας ροών εργασίας](https://queuety.inline0.dev/el/docs/workflows/guardrails)