# 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()`:

```php
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()`:

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

## Recuperare gli artefatti

```php
$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:

```php
$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:

```bash
wp queuety workflow artifacts 42
```

Mostrare un artefatto con il suo contenuto:

```bash
wp queuety workflow artifact 42 draft
```

Per il riferimento completo ai comandi, consultate [CLI](https://queuety.inline0.dev/it/docs/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.