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 anidentifier. 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
Setartifact 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.
crew.jsonc:
Let CrewAI name it
Passartifact=True to skip the details. CrewAI fills them in:
identifierandtitlecome 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.kindcomes from the output:htmlif it starts with<!doctype htmlor<html,svgif it starts with<svg,jsonif it is a JSON object or list, andmarkdownfor anything else.
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, setartifact 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:
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, setfile_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}infile_pathare filled from the kickoff inputs, likeoutput_file. In a flow declaration, use${...}expressions, such asoutput/${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’sartifact, so a callback, a later flow step or your own code can send the link on:
${outputs.write_report.artifact.url}.
Let agents save artifacts
Setartifacts=True on a crew to give every agent a save_artifact tool, or on one agent to give only that agent the tool.
identifier, title, kind, and either content (text) or file_path (a file the agent made, such as a chart PNG). It returns JSON:
url, for example to post it to Slack or attach it to an email.
Save from code
Callsave_artifact from any Python code, such as a flow step. No agent is needed.
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
Callload_artifact to read back an artifact the run saved. It returns the bytes of the latest version, or of the version you ask for:
load_artifactreads from the current run, the same one a resumed flow continues.- If no artifact or version matches, it raises
ArtifactNotFoundError.
Identifiers and versions
identifiermust match[a-z0-9][a-z0-9_.-]{0,63}, for exampleq3-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_artifacttool returns the error text to the agent. Task(artifact=...)andkickoff(artifact=...)log a warning, and the run still completes. This includes a missingfile_path.- Calling
save_artifactfrom your own code raises the error, so you decide what to do.
Events
Every save emitsArtifactCreatedEvent on the event bus, with id, identifier, version, title, kind, content_type, size and url.
Custom stores
To send artifacts somewhere else, subclassArtifactStore and register it before kickoff:
artifact_id each time so the receiver can drop duplicates. load is optional: without it, load_artifact raises NotImplementedError.