Перейти до вмісту

Оркестрація агентів

Переглянути як Markdown Редагувати на GitHub Документація для 2cc7b2b

Queuety добре підходить для систем агентів, яким потрібна адаптивна робота зі збереженням надійного стану, повторних спроб, можливості перегляду й чіткої семантики очікування.

Для більшості потоків роботи агентів не потрібен механізм DAG, який можна змінювати під час виконання. На практиці більшість систем можна змоделювати за допомогою кількох надійних механізмів оркестрації. for_each() розгортає роботу в межах одного запуску робочого процесу. start_agents() та wait_for_agents() передають виявлену під час виконання роботу окремим робочим процесам верхнього рівня. wait_for_decision() та wait_for_input() призупиняють виконання, щоб передати керування людині. wait_for_workflow(), wait_for_workflows() і wait_for_agent_group() дають одному запуску верхнього рівня змогу чекати на інший запуск або на запуск необхідної кількості процесів.

Зручна ментальна модель

Оркестрацію агентів найпростіше розуміти пошарово. Планувальник визначає, яку роботу потрібно виконати. Queuety перетворює її на надійні завдання або робочі процеси. Спеціалізовані запуски створюють результати й зберігають артефакти. Контролювальний етап об’єднує результати й визначає подальші дії. На будь-якому етапі людина може погодити, відхилити або виправити виконання, перш ніж воно продовжиться.

Важлива відмінність у тому, що агент вирішує, яку роботу виконати, але Queuety і далі визначає, як цю роботу зберігати, повторювати, відновлювати й об’єднувати. Якщо оркеструється довготривалий сеанс, а не обмежений запуск, поєднайте це з Машинами станів.

Шаблон 1: планувальник і виконавець з окремими запусками агентів

Використовуйте 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'].

Це найпростіший варіант для початку роботи з системами планування й виконання, адже кожен запуск агента можна окремо переглянути й повторити.

Шаблон 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_tasks добре підходить для результатів планування, agent_workflow_ids — для запущених процесів верхнього рівня, agent_results — для стану завершених дочірніх процесів, а review або decision — для даних погодження чи відхилення. Великі результати, як-от чернетки, цитати або маніфести досліджень, зазвичай варто зберігати в сховищі артефактів, а не в основному наборі стану робочого процесу.

Системам агентів обмеження потрібні чи не більше, ніж будь-якому іншому типу завдань, адже за своєю природою вони динамічні.

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

Ці засоби контролю допомагають відповісти на важливі для робочого середовища запитання: версія якого визначення створила запуск, чи можуть повторні зовнішні запити запустити його двічі, чи не створить планувальник забагато гілок і чи не зростатиме стан робочого процесу без обмежень. Для більшості систем агентів спершу налаштуйте ці обмеження, а вже потім — кількість робочих процесів або структуру черг.

Див. також