Skip to main content

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.
In a JSON crew, add it to the task in crew.jsonc:

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.
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:
kickoff_async and akickoff accept it too.

Declarative flows

In a flow declaration, set artifact under with on a call: agent step:
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:
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.
  • 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:
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.
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:
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.
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:
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

Where artifacts are stored

Locally, artifacts go to:
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.
See Event Listeners.

Custom stores

To send artifacts somewhere else, subclass ArtifactStore and register it before kickoff:
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.