# Artefaktit

Artefaktien avulla voit tallentaa työnkulun tulokset pysyvästi kasvattamatta työnkulun tilan päähyötykuormaa.

Ne sopivat luonnosasiakirjoille, poimituille JSON-suunnitelmille, viitteille, lähdeluetteloille, luotujen tiedostojen poluille sekä kehotteiden ja vastausten tilannekuville, joita haluat tarkastella myöhemmin. Tämä on erityisen hyödyllistä agenttityönkuluissa: lopputila pysyy pienenä ja helposti luettavana, vaikka jokainen suoritus voi tuottaa suuria välituloksia.

## Miksi käyttää artefakteja työnkulun tilan sijaan

Työnkulun tila sopii erinomaisesti pienille julkisille tiedoille, joita seuraava vaihe tarvitsee heti.

Artefaktit sopivat paremmin, kun tuloste on tavallisia tilan arvoja suurempi, tarkoitettu pääasiassa myöhempään tarkasteluun, hyödyllinen tarkistus- tai vientinäkymissä tai yksinkertaisesti sopii paremmin nimetyksi tulosteeksi kuin yhdeksi suureksi tilatietueeksi.

## Tallenna artefakti nykyisessä työnkulun vaiheessa

Kun koodi suoritetaan jo työnkulun vaiheen sisällä, käytä kohdetta `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 liittää automaattisesti nykyisen työnkulun tunnisteen ja vaiheen indeksin.

## Tallenna artefakti työnkulun ulkopuolelta

Jos tiedät jo työnkulun tunnisteen, käytä kohdetta `Queuety::put_artifact()`:

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

## Lue artefaktit takaisin

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

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

Jokainen artefaktitietue sisältää kentät `key`, `kind`, `content`, `metadata`, `step_index`, `created_at` ja `updated_at`. `Queuety::workflow_artifacts()` jättää kohteen `content` pois, ellet välitä kohdetta `true` toisena argumenttina.

## Työnkulun tilan integrointi

`Queuety::workflow_status()` sisältää nyt pienen artefaktien yhteenvedon:

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

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

Näin artefaktit pysyvät näkyvissä ilman, että niiden koko sisältö tuodaan tilatulosteeseen.

## CLI

Listaa työnkulun artefaktit:

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

Näytä yhden artefaktin sisältö:

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

Katso [CLI](https://queuety.inline0.dev/fi/docs/cli) täydellinen komentoviite.

## Viennit ja toisto

Artefaktit sisältyvät työnkulkujen vientiin, ja ne kopioidaan uudelleen toistettuihin työnkulkuihin.

Näin artefakteihin perustuvien agenttien suorituksia voi tarkastella myös silloin, kun siirrät ne ympäristöstä toiseen tai luot suorituksen uudelleen viedyn suoritushistorian perusteella.