# Artefacts

Les artefacts vous permettent de stocker les résultats durables du workflow sans alourdir la charge utile de son état principal.

Ils conviennent aux documents brouillons, aux plans JSON extraits, aux citations, aux manifestes sources, aux chemins de fichiers générés ou aux instantanés de prompts et de réponses que vous souhaitez consulter ultérieurement. C’est particulièrement utile pour les workflows d’agents, où l’état final doit rester compact et lisible, même si chaque exécution peut générer de volumineux résultats intermédiaires.

## Pourquoi utiliser des artefacts plutôt que l’état du workflow

L’état du workflow est idéal pour les petites données publiques dont l’étape suivante a besoin immédiatement.

Les artefacts sont préférables lorsque le résultat est plus volumineux que les valeurs d’état habituelles, sert surtout à une consultation ultérieure, est utile dans les interfaces de révision ou d’exportation, ou se modélise simplement mieux comme un résultat nommé que comme un seul bloc d’état volumineux.

## Stocker un artefact pour l’étape de workflow en cours

Lorsque le code s’exécute déjà dans une étape de workflow, utilisez `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 associe automatiquement l’ID du workflow en cours et l’index de l’étape.

## Stocker un artefact depuis l’extérieur du workflow

Si vous connaissez déjà l’ID du workflow, utilisez `Queuety::put_artifact()` :

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

## Relire les artefacts

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

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

Chaque enregistrement d’artefact comprend les champs `key`, `kind`, `content`, `metadata`, `step_index`, `created_at` et `updated_at`. `Queuety::workflow_artifacts()` omet `content` sauf si vous transmettez `true` comme deuxième argument.

## Intégration à l’état du workflow

`Queuety::workflow_status()` inclut désormais un bref résumé des artefacts :

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

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

Les artefacts restent ainsi visibles sans que leur contenu complet apparaisse dans la sortie d’état.

## CLI

Lister les artefacts d’un workflow :

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

Afficher un artefact avec son contenu :

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

Voir [CLI](https://queuety.inline0.dev/fr/docs/cli) pour la référence complète des commandes.

## Exports et rejeu

Les artefacts sont inclus dans les exports de workflow et copiés dans les workflows rejoués.

Ainsi, les exécutions d’agents reposant sur des artefacts restent consultables lorsque vous les déplacez entre des environnements ou recréez une exécution à partir de son historique d’exécution exporté.