Artifacts

An artifact is a file an assistant writes during a conversation for the reader to open and keep, instead of putting it in the transcript. It opens in a pane beside the chat and downloads as a file. A report, a page with a chart, a PowerPoint deck, an export of rows, or a small interface the reader uses are all artifacts.

This section is for people who build on Curiosity Studio. It covers what each kind of artifact is, how an assistant makes one, and how to give an assistant, an agent or an API client the ability to make them.

How an artifact is made

A sandbox that has artifacts enabled carries a folder, /artifacts, and a command, publish. The assistant makes an artifact in two steps:

cat > /artifacts/q3-availability.md <<'EOF'
# Q3 Availability

Uptime held at 99.94% against a 99.9% target.

| Date   | Duration | Cause              |
|--------|----------|--------------------|
| Jul 14 | 22 min   | Certificate expiry |
EOF

publish q3-availability.md

Writing the file creates the artifact but changes nothing the reader sees, so an assistant can edit it as often as it likes. publish renders it and attaches it to the message as a chip the reader clicks. Writing the same file name again and publishing again replaces the document in place and keeps one chip, not two. publish with no file name lists the artifacts of the conversation and says which are published.

The file extension decides the kind. There is nothing else to pass.

A file with any other extension is refused. The write fails with the message '<name>' is not a kind of artifact - write a .html, .md, .csv, .json, .jsonl or .a2ui file.

Limits and checks

• Size. The source of one artifact is at most 1,000,000 characters. A longer write is refused, not truncated.
• Parsing. publish refuses a .json file that does not parse and a .jsonl file with a line that does not, and prints the line and the reason, so the assistant can fix it and publish again.
• Title. The title comes from the document: the first # heading of a Markdown file, the <title> or first <h1> of a page. A data file has no title of its own and is listed by its file name.
• Conversation. An artifact belongs to a conversation. publish outside a chat fails with artifacts can only be published from inside a chat.
• Sub-agents. A run that a conversation delegated to cannot publish. It writes its files in a directory of its own, and the conversation that called it publishes. See Make artifacts available.

Where artifacts live

An artifact is an _Artifact node linked to its conversation, holding the source the assistant wrote. Publishing renders it into an ordinary _FileEntry owned by the reader, so the published file downloads, audits and deletes like any other file in the workspace. Publishing the same artifact twice replaces that file. Deleting the conversation deletes its artifacts.

Ownership, the Artifacts space and sharing

The user who publishes an artifact is its owner. The owner is written once and never changes. Each user has an Artifacts space that lists the artifacts they own and the ones shared with them.

An owner can share a published artifact with named users. A shared artifact is a view: the people it is shared with open it from their own Artifacts space and cannot change it, share it again or delete it. They can remove it from their own space. Only the owner can delete it, and deleting it removes it for everyone. An artifact has to be published before it can be shared.

An interface that a person opens from a share runs its tools as that person, not as its author. See Interfaces.

Look at it before publishing

The render command draws pages of a document as pictures and attaches them to the call result, so the assistant can check what it made:

render q3-availability.md                # pages 1-3, the default
render q3-availability.md --pages 2      # one page; 2,5-6 and 4- also work
render quarterly-deck.html --pages 1-2   # the .pptx or .docx a page builds
render people.a2ui                       # a published interface, with its data loaded
render /work/deck.pptx --pages 1-2       # a Word, PowerPoint, Excel or PDF file in the sandbox

render draws at most 12 pages per call and reports a page the document does not have. An .html artifact and an .a2ui interface are drawn by the workspace browser, which an administrator switches on under Manage → AI → Browser. When the browser is off, render says so, and the artifact still publishes. An .a2ui interface has to be published before render accepts it, because publishing records the tools it may call.

Settings that affect artifacts