# Артефакти

Артефакти дають змогу зберігати результати надійних робочих процесів, не збільшуючи обсяг даних основного стану.

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

## Чому артефакти, а не стан робочого процесу

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

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

## Збереження артефакту для поточного кроку робочого процесу

Якщо код уже виконується в межах кроку робочого процесу, використовуйте `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 автоматично додає поточний ID робочого процесу та індекс кроку.

## Збереження артефакту поза робочим процесом

Якщо вам уже відомий ID робочого процесу, використовуйте `Queuety::put_artifact()`:

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

## Читання артефактів

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

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

Кожен запис артефакту містить поля `key`, `kind`, `content`, `metadata`, `step_index`, `created_at` і `updated_at`. `Queuety::workflow_artifacts()` не включає `content`, якщо не передати `true` другим аргументом.

## Інтеграція зі статусом робочого процесу

`Queuety::workflow_status()` тепер містить стислий опис артефактів:

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

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

Так артефакти залишаються видимими, а їхній повний вміст не потрапляє до виводу статусу.

## CLI

Список артефактів робочого процесу:

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

Показати артефакт із вмістом:

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

Повний довідник команд дивіться в [CLI](https://queuety.inline0.dev/uk/docs/cli).

## Експорт і відтворення

Артефакти включаються до експорту робочого процесу й копіюються у відтворені робочі процеси.

Завдяки цьому запуски агентів, що використовують артефакти, можна перевірити, навіть якщо перенести їх між середовищами або відтворити запуск з експортованої історії виконання.