# Artifacts

Artifacts are files an agent produces, such as PDFs, images, audio, and video. Jazz reports
their paths in terminal and JSON output, and uploads them in supported chat platforms.

## Create a file

Ask for the output format and where you want it saved:

```text
Turn the findings from this conversation into a two-page PDF briefing.
Save it as ./briefing.pdf.
```

The agent needs the relevant tool: `create_pdf` for PDFs, `create_composition` for visual
pages, or a media-capable model for generated images, audio, and video. See
[Compositions](./compositions.md) and [Model companions](./media.md) for setup.

Open the path Jazz reports to review the result. If you want a revision, describe the
change in the same conversation.

## Provenance

`source` is either `rendered` or `model`. The terminal labels model-generated files:
`chart (AI-generated): /path/to.png`. Rendered files have no generation label.

| `source`   | Means                                        | Produced by                             |
| ---------- | -------------------------------------------- | --------------------------------------- |
| `rendered` | built from data or markup the model authored | `create_pdf`, `create_composition`      |
| `model`    | generated by a model (pixels, audio, video)  | a media-capable model, `generate_media` |

## Where the files land

- **PDFs:** the path you request.
- **Compositions:** `$JAZZ_HOME/compositions/<session-id>/<composition-name>.html`.
- **Generated media:** `$JAZZ_HOME/generated/`.

Jazz prints the saved path so you can open or reuse the file.

## How each surface presents them

- **Terminal**: one line per artifact, with the provenance note.
- **`jazz run --json`**: an `artifacts` array beside `answer`, so a script can pick up the path.
- **Chat bridges**: uploaded when the platform supports that medium, otherwise named.

## Retrieve files from a script

`jazz run --json` includes artifact objects like this in its `artifacts` array:

```json
{
  "kind": "image",
  "path": "/Users/you/.jazz/generated/k3Fh2p.png",
  "mediaType": "image/png",
  "tool": "gemini-3-pro-image",
  "source": "model"
}
```

Use their `path` fields to copy, publish, or pass the files to another step.

## Related

- [Compositions](./compositions.md): charts, dashboards, and interactive HTML pages
- [Model companions](./media.md): analysis and generation on specialist models
- [Tools](../tools/index.md): which tools produce files
- [Headless](../surfaces/headless.md): the JSON envelope