Ga naar de inhoud

Agentorkestratie

Bekijken als Markdown Bewerken op GitHub Documentatie op 2cc7b2b

Queuety is geschikt voor agentsystemen wanneer u adaptief werk wilt zonder duurzame status, opnieuw proberen, inspectie en expliciete wachtsemantiek op te geven.

Voor de meeste agentflows hebt u geen tijdens runtime bewerkbare DAG-engine nodig. In de praktijk kunnen de meeste systemen worden gemodelleerd met een kleine set duurzame orkestratiestappen. for_each() breidt werk binnen één workflowuitvoering uit. start_agents() en wait_for_agents() dragen tijdens runtime ontdekt werk over aan onafhankelijke workflows op topniveau. wait_for_decision() en wait_for_input() pauzeren voor menselijke controle. wait_for_workflow(), wait_for_workflows() en wait_for_agent_group() laten één uitvoering op topniveau wachten op een andere uitvoering of op een gestart quorum.

Een bruikbaar denkmodel

Agentorkestratie is het eenvoudigst te begrijpen in lagen. Een planner bepaalt welk werk er is. Queuety zet dat werk om in duurzame taken of workflows. Specialistische uitvoeringen leveren resultaten op en slaan artefacten op. Een toezichthoudende fase verzamelt die resultaten en bepaalt wat er daarna gebeurt. Op elk moment kan een mens de uitvoering goedkeuren, afwijzen of corrigeren voordat deze verdergaat.

Het belangrijke onderscheid is dat de agent bepaalt welk werk er moet worden gedaan, maar dat Queuety nog steeds bepaalt hoe dat werk wordt opgeslagen, opnieuw geprobeerd, hervat en samengevoegd. Wanneer het orkestratiedoel een langlopende sessie is in plaats van een afgebakende uitvoering, combineert u dit met Toestandsmachines.

Patroon 1: Planner/uitvoerder met onafhankelijke agentuitvoeringen

Gebruik start_agents() wanneer een plannerstap tijdens runtime taken ontdekt en elke taak een eigen workflow op topniveau moet worden.

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

In dit patroon schrijft PlanResearchTasksStep tijdens runtime ontdekte items naar $state['agent_tasks'], dispatcht start_agents() één duurzame workflow per taak en laat wait_for_agent_group() de bovenliggende workflow wachten totdat aan de gekozen voltooiingsvoorwaarde is voldaan. SynthesizeBriefStep ontvangt vervolgens de voltooide onderliggende toestanden onder $state['agent_results'].

Dit is het duidelijkste startpunt voor planner-/uitvoeringssystemen, omdat elke agentuitvoering afzonderlijk inzichtelijk is en opnieuw kan worden geprobeerd.

Patroon 2: Menselijke beoordeling voordat de uitvoering verdergaat

Gebruik wait_for_decision() wanneer de workflow moet stoppen voor een echte ja-of-neebeslissing, en wait_for_input() wanneer de operator gestructureerde feedback naar de uitvoering moet terugsturen.

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

Als de beoordelaar goedkeurt:

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

Als de beoordelaar afwijst:

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

Na wait_for_decision() ontvangt de workflow een gestructureerde payload met de uiteindelijke uitkomst, het signaal dat de uitvoering heeft hervat en eventuele gegevens van de beoordelaar. Zo krijgt u een echt controlepunt met een mens in de lus, zonder dat een PHP-proces open hoeft te blijven terwijl de uitvoering wacht.

Patroon 3: De ene workflow wacht op de andere

Soms is één enorme workflow niet het duidelijkste model. De ene workflow kan het onderzoek afronden, terwijl een andere workflow daarop wacht voordat de volgende fase begint.

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

Zo ontstaat een duurzame grens tussen de onderzoeksfase en de publicatiefase. Elke uitvoering heeft een eigen operationele levenscyclus, maar de tweede workflow wordt automatisch hervat zodra de afhankelijkheid is voltooid.

De juiste bouwsteen kiezen

for_each() is het juiste hulpmiddel wanneer het werk binnen één workflowuitvoering hoort en de vertakkingen in feite alleen parallelle uitvoering van stappen zijn op basis van één gedeelde statusverzameling.

start_agents() is geschikter wanneer elke ontdekte taak een eigen duurzame uitvoering op topniveau moet krijgen en u die uitvoeringen afzonderlijk wilt inspecteren, opnieuw proberen of exporteren.

wait_for_workflow() en wait_for_workflows() passen wanneer één workflow op topniveau afhankelijk is van een andere workflow op topniveau en u duurzame asynchrone coördinatie tussen die orkestratielagen wilt.

wait_for_decision() en wait_for_input() horen thuis op de punten waar een mens de uitvoering moet goedkeuren, afwijzen of bijsturen, terwijl de workflow gepauzeerd blijft zonder workercapaciteit te verbruiken.

Aanbevolen afspraken voor statussen

Agentsystemen zijn eenvoudiger te debuggen wanneer de statussleutels voorspelbaar zijn. In de praktijk werkt agent_tasks goed voor planneruitvoer, agent_workflow_ids voor gestarte uitvoeringen op topniveau, agent_results voor voltooide status van onderliggende workflows en review of decision voor goedkeurings- of afwijzingspayloads. Grotere uitvoer, zoals concepten, citaten of onderzoeksmanifesten, hoort meestal in de artefactopslag in plaats van in de hoofdstatusverzameling van de workflow.

Agentworkflows hebben meer baat bij waarborgen dan bijna elk ander gebruiksscenario, omdat ze van nature dynamisch zijn.

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

Deze controles beantwoorden de praktische vragen die er in productie toe doen: welke definitieversie een uitvoering heeft opgeleverd, of dubbele externe verzoeken deze twee keer kunnen dispatchen, of een planner te veel vertakkingen kan maken en of de workflowstatus onbeperkt kan groeien. Begin voor de meeste agentsystemen met deze waarborgen voordat u workeraantallen of wachtrijtopologie gaat afstellen.

Zie ook