# 아티팩트

아티팩트를 사용하면 기본 워크플로 상태 페이로드를 부풀리지 않고도 워크플로 출력을 영구적으로 저장할 수 있습니다.

초안 문서, 추출한 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()`는 두 번째 인수로 `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
```

콘텐츠와 함께 아티팩트 하나 표시:

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

전체 명령어 참조는 [CLI](https://queuety.inline0.dev/ko/docs/cli)를 참조하세요.

## 내보내기 및 재생

아티팩트는 워크플로 내보내기에 포함되며 재생된 워크플로에도 복사됩니다.

따라서 아티팩트를 사용하는 에이전트 실행은 환경 간에 옮기거나 내보낸 실행 기록에서 다시 만들어도 계속 검토할 수 있습니다.