Skip to content

feat: save files as versioned, shareable artifacts - #9551

Open
Gabe Milani (gabemilani) wants to merge 4 commits into
mainfrom
feat/artifacts
Open

Gabe Milani (gabemilani) wants to merge 4 commits into
mainfrom
feat/artifacts

Conversation

@gabemilani

Copy link
Copy Markdown
Member

Summary

A run can only return plain text today. Reports, charts and files a crew makes never reach the people who use the automation. This adds artifacts: named, versioned files a run saves for people to preview, download and share.

Ways to save one:

  • Task(artifact=Artifact(identifier="q3-report", title="Q3 report", kind="html")) saves the task's output with no tool call, so the model can't forget. agent.kickoff(..., artifact=...) does the same for single agents, and artifact: under call: agent does it in declarative flows.
  • artifact=True fills in the details: the name comes from the task, the flow method or the agent role, and the kind is detected from the output.
  • Artifact(..., file_path="output/{quarter}.png") saves a file the agent's tools write (charts, PDFs) instead of the text. {placeholders} and ${...} get the same path checks as output_file.
  • Crew(artifacts=True) / Agent(artifacts=True) give agents a save_artifact tool that returns the link. It works in crews, in standalone task runs and in kickoff.
  • save_artifact(...) from code, such as a flow step, with text or bytes. Image bytes are detected as PNG, JPEG, GIF or WebP.

Saving the same identifier again in a run creates the next version. The saved version is on TaskOutput.artifact and LiteAgentOutput.artifact, so callbacks and later steps can send the link on. Each save gets a UUID id before upload, so a retrying store can be deduped. Every save emits ArtifactCreatedEvent with the agent and task that saved it. It reaches AMP traces and becomes a save artifact OpenTelemetry span.

Locally, files go to ./artifacts/<run id>/<identifier>/v<N>.<ext>. Each version is claimed with an exclusive create, so concurrent saves never overwrite each other. The store is swappable (set_artifact_store), so it's possible to upload to different places. On async paths the save runs off the event loop. A2A agents keep working: when an agent delegates, the artifact is saved once on the final result.

A failed save never fails the run; it is logged as a warning. File paths must stay inside the working directory or the temp dir, and image, pdf and file kinds can't be filled from text.

Also: a docs page concepts/artifacts (en, pt-BR, ko, ar), a commented example in the JSON crew task template, and a line in the scaffolded AGENTS.md.

Verification

  • Tests added or updated for the changed behavior
  • Relevant tests and quality checks pass locally

Additional context

  • Behavior change: a task now writes output_file before its callbacks run (it used to be after), so an artifact can point at that file and callbacks see the saved artifact.
  • TaskOutput and LiteAgentOutput now serialize an artifact key (null when unused).

Crews, agents and flows can now save reports, charts, PDFs and other
files as artifacts. Set Task(artifact=...) to save a task's output,
artifacts=True to give agents a save_artifact tool, or call
save_artifact() from a flow step. Saving the same identifier again
creates a new version. Files go to ./artifacts/ locally
@mintlify

mintlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
crewai 🟢 Ready View Preview Nov 18, 2026, 6:55 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@strix-security

strix-security Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Strix Security Review

Warning

This pull request has 3 commits after the last Strix review (b9051b8). Strix has not reviewed these changes.
Automatic review on push is off for this repository. To review the latest changes, tag @strix-security in a comment, or turn on re-review on push.

To fix before merging (1)

PR summary: This PR adds artifacts to CrewAI: named, versioned files a task, agent, flow, or the new `save_artifact` tool saves (from text, bytes, or a file the agent wrote) into a swappable store, defaulting to `./artifacts/<run>/<identifier>/v<N>.<ext>`, with the saved version exposed on `TaskOutput`/`LiteAgentOutput` and announced through a new `ArtifactCreatedEvent` that reaches traces and an OpenTelemetry span. It also reorders `output_file` writing ahead of task callbacks and refactors the file-path validation into shared helpers.

Review summary

The artifact feature's file handling holds up well: the output_file validation was lifted into _interpolate_path/validate_interpolated_path with its checks intact (no .., no leading ~/$, no shell metacharacters, no absolute promotion after interpolation), artifact.file_path gets the same treatment at task construction, after interpolation and in declarative flows, and _check_readable resolves symlinks and confines reads to the working directory or temp dir before any bytes are read. The identifier pattern is enforced on every path into the local store, extensions cannot carry separators, and the exclusive-create version claim cannot be raced. Telemetry and checkpoint payloads carry only artifact metadata, not bytes or live agent/task objects. One weakness was confirmed: "save_artifact publishes any file under the working directory or the shared temp dir" — the new model-facing tool accepts any existing file under the whole working directory or the system temp dir, so an agent working from untrusted content can copy .env, project credentials or another process's temp files into the artifact store and get a URL back; the containment check stops traversal and absolute escapes but not in-tree secrets.

Ruled out (6)
  • Can a model-supplied `file_path` escape the working directory via traversal, absolute paths or symlinks to read arbitrary system files?
    `_check_readable` resolves the path before a containment check, so `/etc/passwd`, `../../etc/passwd` and a cwd symlink pointing outside were all refused in live testing — the weakness is what the allow-set includes, not how paths are resolved.
  • Does moving `output_file` validation into `_interpolate_path`/`validate_interpolated_path` weaken the existing traversal protection?
    The helper is the pre-refactor block verbatim, still rejects `..`, leading `~`/`$`, shell metacharacters, residual braces and a raised path anchor, and still assigns the path only after every check passes, with the existing tests exercising the same semantics.
  • Can `identifier`, `execution_id` or `extension` push a local artifact write outside `./artifacts/<execution>/<identifier>/`?
    The identifier regex is enforced on every construction path, the extension can only come from fixed tables or a `Path.suffix`, `execution_id` is a locally minted UUID in OSS, and the `open("xb")` claim makes the version race safe.
  • Does `ArtifactCreatedEvent` ship agent/task objects or artifact content to the trace collector and span attributes?
    `BaseEvent` nulls `from_agent`/`from_task` right after construction and only scalar metadata (identifier, version, kind, size, url, role, task name) goes out — the same class of data existing skill and task events already send, with no bytes.
  • Can an unbounded artifact save exhaust a worker other users share?
    The read is bounded by an existing regular local file (`is_file()` excludes `/dev/zero`, stdin and FIFOs), failures are caught in both the tool and the task, the feature is opt-in, and nothing in the repo shares a server-side store across users.
  • Does the trusted `save_artifact` tool name let a colliding user or MCP tool shadow the framework tool, or the framework tool replace a user tool, to escalate p…
    Both merge directions only occur inside an operator's own tool configuration with `artifacts=True` already enabled, and neither grants a capability the operator did not opt into, so no trust boundary is crossed.

Fixed the findings? re-run the review, or tag @strix-security in a PR comment to run a fresh review.

Review 1 on this PR · b9051b8 · requested Nov 18 14:22 UTC when the PR was opened


Reviewed by Strix
Re-run review · Configure security review settings · Try a deeper review with @strix-security /deep

@gabemilani Gabe Milani (gabemilani) changed the title feat(artifacts): save files as versioned, shareable artifacts feat: save files as versioned, shareable artifacts Nov 18, 2026
Comment thread lib/crewai/tests/test_artifacts.py Fixed

@strix-security strix-security Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strix flagged a new security finding below. See the pinned summary comment for the full PR status.

Comment thread lib/crewai/src/crewai/artifacts.py Resolved
Comment thread lib/crewai/src/crewai/artifacts.py Resolved
Comment thread docs/edge/en/concepts/artifacts.mdx Resolved
Comment on lines +10 to +13
class ArtifactCreatedEvent(BaseEvent):
"""Emitted when a run saves a new artifact version."""

type: Literal["artifact_created"] = "artifact_created"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The type here is a bit redundant, isnt?
How about have one event for each type? that way we could easily identify them in the traces, no need to expand the event to get its type

A run can now read back an artifact it saved, so a flow that pauses for
human feedback can revise its report after resuming on another worker.
Call load_artifact() for the latest or a given version, or list
{artifact: <identifier>} under input_files on a declarative agent step.
Custom stores add an optional load(). Docs cover it in all four languages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

2 active deployments
staging - docs — 9c158c6d Deployed Nov 18, 2026 by mintlify[bot]
agents-md-eval — 9c158c6d Deployed Nov 18, 2026 by gabemilani via AGENTS.md eval (claude:claude-sonnet-5-5) #32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants