Artefatti

Gli artefatti consentono di salvare output duraturi dei workflow senza appesantire il payload dello stato principale.

Sono adatti a documenti in bozza, piani JSON estratti, citazioni, manifesti delle fonti, percorsi di file generati o istantanee di prompt e risposte che volete esaminare in seguito. Sono particolarmente utili nei workflow degli agenti, in cui lo stato finale deve restare compatto e leggibile anche se ogni esecuzione può generare grandi quantità di output intermedi.

Perché usare gli artefatti invece dello stato del workflow

Lo stato del workflow è ideale per i piccoli dati pubblici di cui il passaggio successivo ha bisogno immediatamente.

Gli artefatti sono più adatti quando l’output è più grande dei normali valori di stato, serve soprattutto per consultazioni successive, è utile nelle interfacce di revisione o esportazione oppure si presta meglio a essere modellato come output nominato anziché come un unico grande blocco di stato.

Salvare un artefatto per il passaggio del workflow corrente

Quando il codice è già in esecuzione all’interno di un passaggio del workflow, usate Queuety::put_current_artifact():

use Queuety\Queuety;
use Queuety\Step;

final class DraftBriefStep implements Step
{
    public function handle(array $state): array
    {
        $draft = [
            'title' => 'Pricing brief',
            'body' => '...',
        ];

        Queuety::put_current_artifact(
            'draft',
            $draft,
            'json',
            [ 'source' => 'planner' ],
        );

        return [ 'draft_ready' => true ];
    }

    public function config(): array
    {
        return [];
    }
}

Queuety associa automaticamente l’ID del workflow e l’indice del passaggio corrente.

Salvare un artefatto dall’esterno del workflow

Se conoscete già l’ID del workflow, usate Queuety::put_artifact():

Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    "# Research Brief\n\nDone.",
    'markdown',
    metadata: [ 'reviewed_by' => 'editor@example.com' ],
);

Recuperare gli artefatti

$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );

$artifacts = Queuety::workflow_artifacts( $workflow_id );

Ogni record di artefatto include i campi key, kind, content, metadata, step_index, created_at e updated_at. Queuety::workflow_artifacts() non include content, a meno che non passiate true come secondo argomento.

Integrazione con lo stato del workflow

Queuety::workflow_status() ora include un breve riepilogo degli artefatti:

$status = Queuety::workflow_status( $workflow_id );

echo $status->artifact_count; // 2
print_r( $status->artifact_keys ); // ['draft', 'citations']

Così gli artefatti restano visibili senza includerne il contenuto completo nell’output dello stato.

CLI

Elencare gli artefatti di un workflow:

wp queuety workflow artifacts 42

Mostrare un artefatto con il suo contenuto:

wp queuety workflow artifact 42 draft

Per il riferimento completo ai comandi, consultate CLI.

Esportazioni e riproduzione

Gli artefatti sono inclusi nelle esportazioni dei workflow e copiati nei workflow riprodotti.

Questo permette di ispezionare le esecuzioni degli agenti basate su artefatti anche quando le spostate tra ambienti o ricreate un’esecuzione dalla cronologia di esecuzione esportata.