Artifacts

Working with files and outputs from your crew runs

Overview

Artifacts are files produced by your crew during a run. Crewship automatically:

• Collects files from a standard directory
• Stores them durably
• Makes them accessible via API and Console

Producing Artifacts

Standard Directory

Write files to /app/artifacts/ in your crew:

# In your agent or task
with open("/app/artifacts/report.md", "w") as f:
    f.write(generated_content)

CrewAI Output Files

Use the output_file parameter in tasks:

tasks.yaml

writing_task:
  description: Write a comprehensive report about {topic}
  expected_output: A detailed markdown report
  agent: writer
  output_file: /app/artifacts/report.md

Multiple Artifacts

Produce as many files as needed:

# Reports
with open("/app/artifacts/summary.md", "w") as f:
    f.write(summary)

# Data
with open("/app/artifacts/data.json", "w") as f:
    json.dump(data, f)

# Images
with open("/app/artifacts/chart.png", "wb") as f:
    f.write(image_bytes)

Accessing Artifacts

Via CLI

# List artifacts for a run
crewship runs artifacts run_xyz789

Output:

Artifacts for run_xyz789:

  report.md        3.2 KB   text/markdown
  data.json        1.1 KB   application/json
  chart.png       45.6 KB   image/png

3 artifacts, 49.9 KB total

Download artifacts:

# Download single artifact
crewship runs download run_xyz789 report.md

# Download all artifacts
crewship runs download run_xyz789 --all

# Download to specific directory
crewship runs download run_xyz789 report.md --output ./downloads/

Via API

# List artifacts
curl https://api.crewship.dev/v1/runs/run_xyz789/artifacts \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "artifacts": [
    {
      "name": "report.md",
      "size": 3276,
      "content_type": "text/markdown",
      "created_at": "2024-01-15T10:30:46Z"
    },
    {
      "name": "data.json",
      "size": 1124,
      "content_type": "application/json",
      "created_at": "2024-01-15T10:30:46Z"
    }
  ]
}

Download an artifact:

curl https://api.crewship.dev/v1/runs/run_xyz789/artifacts/report.md \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.md

Via Console

1. Open the Console
2. Navigate to your run
3. Click the Artifacts tab
4. Click any artifact to preview or download

Artifact Events

When an artifact is produced, an event is emitted:

{
  "type": "artifact",
  "payload": {
    "name": "report.md",
    "size": 3276,
    "content_type": "text/markdown",
    "sha256": "abc123..."
  }
}

Use this for real-time notifications in streaming:

crewship invoke --input '{"topic": "AI"}' --stream
# ...
├─ [10:30:46] Artifact: report.md (3.2 KB)

Supported File Types

Any file type is supported. Common types include:

Type	Extensions	Use Case
Text	.md, .txt, .csv	Reports, logs, data
JSON	.json	Structured data
Documents	.pdf, .docx	Formatted output
Images	.png, .jpg, .svg	Charts, screenshots
Archives	.zip, .tar.gz	Bundled outputs

Size Limits

Limit	Value
Single artifact	100 MB
Total per run	500 MB
Retention	30 days

Need larger limits? Contact us for enterprise plans.

Organizing Artifacts

Use subdirectories for organization:

# Subdirectories are flattened but paths are preserved
with open("/app/artifacts/reports/summary.md", "w") as f:
    f.write(summary)

with open("/app/artifacts/data/output.json", "w") as f:
    json.dump(data, f)

Artifacts are listed with their relative paths:

reports/summary.md    2.1 KB
data/output.json      1.5 KB

Best Practices

Use descriptive names

Name files clearly: quarterly_report_2024Q1.md not output.md

Include metadata

Add timestamps or run info to filenames when helpful:

filename = f"report_{run_id}_{timestamp}.md"

Use appropriate formats

• Markdown for human-readable reports
• JSON for structured data
• CSV for tabular data
• PDF for formatted documents

Compress large outputs

For many files, create a zip archive:

import zipfile

with zipfile.ZipFile("/app/artifacts/bundle.zip", "w") as zf:
    for file in files:
        zf.write(file)

Artifact Lifecycle

Crew writes file to /app/artifacts/
              │
              ▼
     Run completes
              │
              ▼
   Crewship collects files
              │
              ▼
    Uploads to durable storage
              │
              ▼
   Available via API & Console
              │
              ▼
    Retained for 30 days

Related

Your First Crew

Build a crew that produces artifacts

Streaming

Get notified when artifacts are produced