# 成果物

成果物を使うと、ワークフロー状態のペイロードを肥大化させずに、耐久性のあるワークフロー出力を保存できます。

下書き文書、抽出した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()`は、2番目の引数として`true`を渡さない限り、`content`を除外します。

## ワークフロー状態との連携

`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
```

内容を含めて1つのアーティファクトを表示します:

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

コマンドの全リファレンスは[CLI](https://queuety.inline0.dev/ja/docs/cli)を参照してください。

## エクスポートと再生

アーティファクトはワークフローのエクスポートに含まれ、再生されたワークフローにもコピーされます。

つまり、アーティファクトを利用するエージェントの実行は、環境間で移動した場合や、エクスポートした実行履歴から実行を再作成した場合も、引き続き検査できます。