> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts

> Save reports, charts, PDFs and other files from a run so people can preview, download and share them.

## Overview

An artifact is a named file that a crew, agent or flow produces: an HTML report, a markdown doc, a chart, a PDF or a CSV. Each artifact has an `identifier`. Saving the same identifier again in the same run creates a new version (v1, v2, ...).

Locally, artifacts are written to disk. On CrewAI AMP, they appear next to the run, where people can preview, download and share them.

Artifacts are opt-in. You can save a task's or agent's output, let agents save files with a tool, or save from your own code.

## Save a task's or agent's output

Set `artifact` on a task. When the task finishes, its final output is saved as the artifact. No tool call and no extra tokens are involved, so the model cannot forget to save it.

```python theme={null}
from crewai import Artifact, Task

report = Task(
    description="Write the Q3 report as HTML",
    expected_output="A full HTML page",
    agent=analyst,
    artifact=Artifact(identifier="q3-report", title="Q3 report", kind="html"),
)
```

In a JSON crew, add it to the task in `crew.jsonc`:

```jsonc theme={null}
"artifact": {"identifier": "q3-report", "title": "Q3 report", "kind": "html"}
```

### Let CrewAI name it

Pass `artifact=True` to skip the details. CrewAI fills them in:

* `identifier` and `title` come from the task name (or its description). Inside a flow, they come from the flow method name. Otherwise, they come from the agent's role.
* `kind` comes from the output: `html` if it starts with `<!doctype html` or `<html`, `svg` if it starts with `<svg`, `json` if it is a JSON object or list, and `markdown` for anything else.

```python theme={null}
report = Task(name="Q3 report", description="...", expected_output="...", artifact=True)
# saved as identifier "q3-report", title "Q3 report"
```

The name stays the same when the same task or flow method runs again, so a rerun creates the next version, not a new artifact.

### Single agents

`Agent.kickoff` takes the same `artifact` argument, as an `Artifact` or `True`:

```python theme={null}
result = analyst.kickoff(
    "Write the Q3 report as HTML",
    artifact=Artifact(identifier="q3-report", title="Q3 report", kind="html"),
)
```

`kickoff_async` and `akickoff` accept it too.

### Declarative flows

In a flow declaration, set `artifact` under `with` on a `call: agent` step:

```yaml theme={null}
methods:
  write_report:
    start: true
    do:
      call: agent
      with:
        role: Analyst
        goal: Write the weekly report as a full HTML page
        backstory: Writes clear reports for executives.
        input: "Weekly report on ${state.topic}"
        artifact: true
```

`artifact: true` names it after the method, here `write-report`. Use an object, such as `{identifier: weekly-report, title: Weekly report, kind: html}`, to set the details yourself.

To give the agent an artifact the run saved earlier, list it under `input_files`. Each entry is a reference, loaded when the step runs:

```yaml theme={null}
revise_report:
  listen: needs_changes
  do:
    call: agent
    with:
      role: Analyst
      goal: Revise the weekly report from the reviewer's feedback
      backstory: Writes clear reports for executives.
      input: Apply the reviewer's feedback to the attached report.
      input_files:
        current_report: {artifact: write-report}
        first_draft: {artifact: write-report, version: 1}
      artifact: true
```

Without `version`, the latest version is used. If the artifact does not exist, the step fails before the agent runs. Input files need `crewai[file-processing]`.

### Save a file the agent writes

For a chart, a PDF or any other file the agent's tools write to disk, set `file_path` to where the file will be. CrewAI saves that file instead of the text output. `image`, `pdf` and `file` kinds need `file_path`.

```python theme={null}
chart = Task(
    description="Draw the {quarter} sales chart and save it to output/{quarter}.png",
    expected_output="A short summary of the chart",
    agent=designer,
    artifact=Artifact(
        identifier="sales-chart",
        title="Sales chart",
        kind="image",
        file_path="output/{quarter}.png",
    ),
)
```

* Tell the agent where to write the file, for example in the task description.
* On a task, `{placeholders}` in `file_path` are filled from the kickoff inputs, like `output_file`. In a flow declaration, use `${...}` expressions, such as `output/${state.quarter}.png`.
* The file must be inside the working directory. Paths outside it are refused, so write charts and PDFs into the project directory.

### Use the saved artifact

The saved version is on the output's `artifact`, so a callback, a later flow step or your own code can send the link on:

```python theme={null}
output = report.execute_sync()
print(output.artifact.url)

result = analyst.kickoff("...", artifact=True)
print(result.artifact.url)
```

In a flow declaration, read it with `${outputs.write_report.artifact.url}`.

## Let agents save artifacts

Set `artifacts=True` on a crew to give every agent a `save_artifact` tool, or on one agent to give only that agent the tool.

```python theme={null}
from crewai import Agent, Crew

crew = Crew(agents=[analyst, writer], tasks=[...], artifacts=True)
# or
analyst = Agent(role="Analyst", goal="...", backstory="...", artifacts=True)
```

The tool takes `identifier`, `title`, `kind`, and either `content` (text) or `file_path` (a file the agent made, such as a chart PNG). It returns JSON:

```json theme={null}
{"id": "0b9e6c1e-...", "identifier": "q3-report", "version": 1, "url": "file:///.../v1.html", "share_url": null}
```

A later task can use the `url`, for example to post it to Slack or attach it to an email.

## Save from code

Call `save_artifact` from any Python code, such as a flow step. No agent is needed.

```python theme={null}
from crewai import Artifact, save_artifact
from crewai.flow import Flow, listen, start

class ReportFlow(Flow):
    @start()
    def write(self):
        return "# Weekly report\n..."

    @listen(write)
    def publish(self, report: str):
        saved = save_artifact(
            Artifact(identifier="weekly-report", title="Weekly report", kind="markdown"),
            content=report,
        )
        return saved.url
```

Pass `content` (a `str` or `bytes`) or `file_path`, not both. It returns a `SavedArtifact` with `id`, `identifier`, `title`, `kind`, `version`, `content_type`, `size`, `url` and `share_url`.

## Read a saved artifact

Call `load_artifact` to read back an artifact the run saved. It returns the bytes of the latest version, or of the version you ask for:

```python theme={null}
from crewai import Artifact, load_artifact, save_artifact

report = Artifact(identifier="board-report", title="Board report", kind="html")
save_artifact(report, content="<h1>Draft</h1>")
save_artifact(report, content="<h1>Revised</h1>")

latest = load_artifact("board-report")              # b"<h1>Revised</h1>"
first = load_artifact("board-report", version=1)    # b"<h1>Draft</h1>"
```

This matters most in a flow that pauses for human feedback. The flow can resume later on another machine, where files written before the pause are gone, but its artifacts are kept. The resumed run reads the report back, revises it and saves the next version.

* `load_artifact` reads from the current run, the same one a resumed flow continues.
* If no artifact or version matches, it raises `ArtifactNotFoundError`.

## Identifiers and versions

* `identifier` must match `[a-z0-9][a-z0-9_.-]{0,63}`, for example `q3-report`.
* An artifact belongs to one run. Crews inside a flow share the flow's run, so all their artifacts are grouped together.
* Saving the same identifier again in the run creates the next version. This fits human-in-the-loop flows that regenerate a report after feedback.

## Kinds

| Kind | Saved as | Notes |
| :- | :- | :- |
| `markdown` | `.md` | |
| `html` | `.html` | Rendered in a sandbox on AMP |
| `svg` | `.svg` | |
| `json` | `.json` | |
| `a2ui` | `.json` | A2UI payload |
| `text` | `.txt` | |
| `csv` | `.csv` | |
| `image` | the file's extension | Needs `file_path`. AMP accepts PNG, JPEG, GIF and WebP |
| `pdf` | `.pdf` | Needs `file_path` on a task or agent |
| `file` | the file's extension | Needs `file_path`. Download only |

## Where artifacts are stored

Locally, artifacts go to:

```
./artifacts/<run id>/<identifier>/v<N>.<ext>
```

`url` is a `file://` URL and `share_url` is empty.

On CrewAI AMP, the platform registers its own store at startup, so the same code uploads artifacts to the run instead. Nothing in your crew changes.

## Failures

Saving an artifact never fails the run:

* The `save_artifact` tool returns the error text to the agent.
* `Task(artifact=...)` and `kickoff(artifact=...)` log a warning, and the run still completes. This includes a missing `file_path`.
* Calling `save_artifact` from your own code raises the error, so you decide what to do.

## Events

Every save emits `ArtifactCreatedEvent` on the event bus, with `id`, `identifier`, `version`, `title`, `kind`, `content_type`, `size` and `url`.

```python theme={null}
from crewai.events import ArtifactCreatedEvent, BaseEventListener

class ArtifactLogger(BaseEventListener):
    def setup_listeners(self, crewai_event_bus):
        @crewai_event_bus.on(ArtifactCreatedEvent)
        def on_artifact(source, event):
            print(f"Saved {event.identifier} v{event.version}: {event.url}")

ArtifactLogger()
```

See [Event Listeners](https://docs.crewai.com/en/concepts/event-listener.md).

## Custom stores

To send artifacts somewhere else, subclass `ArtifactStore` and register it before kickoff:

```python theme={null}
from crewai.artifacts import ArtifactStore, SavedArtifact, set_artifact_store

class S3ArtifactStore(ArtifactStore):
    def save(self, artifact_id, execution_id, artifact, data, extension, content_type):
        key = f"{execution_id}/{artifact.identifier}/{artifact_id}.{extension}"
        url = upload_to_s3(key, data, content_type)  # your code
        return SavedArtifact(
            **artifact.model_dump(),
            id=artifact_id,
            version=next_version(execution_id, artifact.identifier),  # your code
            content_type=content_type,
            size=len(data),
            url=url,
        )

    def load(self, execution_id, identifier, version=None):
        return download_from_s3(execution_id, identifier, version)  # your code

set_artifact_store(S3ArtifactStore())
```

If your store retries uploads, send the same `artifact_id` each time so the receiver can drop duplicates. `load` is optional: without it, `load_artifact` raises `NotImplementedError`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.