ArtifactRef

An ArtifactRef represents a file generated by an agent execution (CSV data, JSON data, or HTML chart). Artifacts are stored in the Artifact Store and fetched on demand — nothing is downloaded until you ask for it.

result = client.query("Top products")

artifact = result.artifacts[0]
print(artifact.name)       # "top_products.csv"
print(artifact.read_text())  # fetch content from the Artifact Store
artifact.download("./output/")  # save to a local directory

---

Properties

Property	Type	Description
id	str	Unique artifact identifier
name	str	Filename (e.g. top_products.csv, chart.html)
type	str \| None	Artifact type: "data", "result", or "chart"
path	str \| None	Local file path (set after calling download())
url	str \| None	Remote path in the Artifact Store

---

Methods

read_text()

Fetch the artifact content as a UTF-8 string. The result is cached in memory so subsequent calls are free.

read_text(encoding: str = "utf-8") -> str

csv_content = artifact.read_text()
print(csv_content)
# product_name,total_revenue
# Widget Pro,45230.00
# Gadget X,38100.00

read_bytes()

Fetch the artifact content as raw bytes. Checks (in order): local file, memory cache, remote URL.

read_bytes() -> bytes

raw = artifact.read_bytes()

Note

Raises FileNotFoundError if the artifact is not available locally and no download URL is set.

download()

Download the artifact to a local file.

download(dest: str | Path = None) -> Path

Parameter	Type	Default	Description
dest	str \| Path	None	Destination file or directory. Defaults to <cwd>/<artifact_name>

# Save to a directory (uses the artifact name as the filename)
path = artifact.download("./output/")
# → ./output/top_products.csv

# Save with a custom filename
path = artifact.download("./my_data.csv")
# → ./my_data.csv

After calling download(), the path property is set to the local file path.

---

Artifact Types

Type	Generated By	Typical Files
data	Data Agent (query)	.csv, .json
result	Python Agent (analyze)	.csv, .json
chart	Chart Agent (chart)	.html

---

How It Works

Artifacts are stored in the Artifact Store (a Docker container). When you call read_text(), read_bytes(), or download(), the SDK fetches the content from the store via HTTP. The content is cached in memory so repeated reads don't trigger new network requests.

ArtifactRef.read_text()
  └── read_bytes()
        ├── 1. Local file? (path exists) → read from disk
        ├── 2. Memory cache? → return cached bytes
        └── 3. Fetch from Artifact Store via HTTP → cache + return

---

Working with Artifacts

Read as pandas DataFrame

import pandas as pd
import io

result = client.query("All orders this month")
csv_text = result.artifacts[0].read_text()
df = pd.read_csv(io.StringIO(csv_text))

Read JSON data

import json

result = client.query("Revenue by category")
json_artifact = [a for a in result.artifacts if a.name.endswith(".json")][0]
data = json.loads(json_artifact.read_text())

Download and open chart in browser

import webbrowser

chart = client.chart("Bar chart of sales", data_from=data)
path = chart.artifacts[0].download("./output/")
webbrowser.open(f"file://{path.resolve()}")

Download all artifacts

result = client.query("Monthly revenue")
for art in result.artifacts:
    local_path = art.download("./output/")
    print(f"Saved: {local_path}")