Artifacts
Artifacts are structured JSON specifications rendered as interactive HTML in the browser and exportable as PDF. They are the primary deliverable of a workflow -- polished documents like reports, dashboards, briefs, and memos produced by agents during execution.
Enabling Artifacts
Artifacts are controlled per stage assignment. Enable the Can Create Artifacts toggle on a stage assignment to give the agent access to artifact tools during that stage's execution.
| Setting | Location | Effect |
|---|---|---|
| Can Create Artifacts | Stage assignment drawer | Agent gains the ability to create, edit, and list artifacts, plus take visual screenshots of them |
When disabled (the default), the agent cannot create, modify, or preview artifacts regardless of its task directive.
Artifact Spec Format
Every artifact is defined by a single JSON specification. This spec is the source of truth -- the same structure renders both the in-browser HTML preview and the PDF export.
{
"version": "1.0",
"title": "Q3 Performance Report",
"template": "report",
"metadata": {
"subtitle": "Regional Sales Analysis",
"author": "Analytics Team",
"date": "2026-03-31"
},
"sections": [
{
"type": "heading",
"level": 1,
"content": "Executive Summary"
},
{
"type": "markdown",
"content": "Revenue grew **12%** quarter-over-quarter..."
},
{
"type": "kpi_row",
"metrics": [
{ "label": "Revenue", "value": "$2.4M", "change": "+12%", "trend": "up" },
{ "label": "Churn", "value": "3.1%", "change": "-0.5%", "trend": "down" }
]
}
]
}
You do not write this JSON yourself. The agent generates it automatically based on your task directive. The spec format is documented here for reference and troubleshooting.
Section Types
heading
Section heading used to organize the document.
| Property | Type | Required | Description |
|---|---|---|---|
level | integer (1--3) | Yes | Heading level: 1 = major section, 2 = subsection, 3 = minor heading |
content | string | Yes | Heading text |
markdown
Prose content supporting full markdown formatting -- bold, italic, links, lists, code blocks, and more.
| Property | Type | Required | Description |
|---|---|---|---|
content | string | Yes | Markdown-formatted text |
table
Data table with headers and rows.
| Property | Type | Required | Description |
|---|---|---|---|
headers | string[] | Yes | Column header labels |
rows | string[][] | Yes | Array of row arrays, each containing cell values |
caption | string | No | Table caption displayed below the table |
highlight_rows | integer[] | No | Row indices (0-based) to visually highlight |
kpi_row
A row of key metric cards, typically used at the top of dashboards and reports.
| Property | Type | Required | Description |
|---|---|---|---|
metrics | object[] | Yes | Array of metric objects |
Each metric object:
| Property | Type | Required | Description |
|---|---|---|---|
label | string | Yes | Metric name (e.g., "Revenue", "Active Users") |
value | string | Yes | Formatted metric value (e.g., "$2.4M", "1,230") |
change | string | No | Change indicator (e.g., "+12%", "-3.5%") |
trend | string | No | Trend direction: "up", "down", or "flat" |
chart
Data visualization rendered as an interactive chart in the browser and as a static image in PDF.
| Property | Type | Required | Description |
|---|---|---|---|
chart_type | string | Yes | Chart type: "bar", "line", "pie", or "area" |
labels | string[] | Yes | X-axis labels (or slice labels for pie charts) |
datasets | object[] | Yes | Array of dataset objects |
Each dataset object:
| Property | Type | Required | Description |
|---|---|---|---|
label | string | Yes | Dataset label (shown in legend) |
data | number[] | Yes | Data values corresponding to labels |
callout
A highlighted notice box for drawing attention to important information.
| Property | Type | Required | Description |
|---|---|---|---|
style | string | Yes | Callout style: "info", "warning", or "success" |
title | string | No | Callout heading |
content | string | Yes | Callout body text (supports markdown) |
divider
A horizontal rule separating sections. No properties -- the type alone is sufficient.
page_break
Forces a new page in the PDF export. No visual effect in the browser preview. No properties.
image
An image with an optional caption.
| Property | Type | Required | Description |
|---|---|---|---|
s3_key | string | Yes | Storage key for the image file |
caption | string | No | Caption text displayed below the image |
cover
The cover page is auto-generated from the artifact's title, metadata.subtitle, metadata.author, and metadata.date. You do not add a cover section manually -- it is prepended automatically when the artifact is created.
Templates
Templates control the visual formatting and layout of the PDF export. The agent selects a template based on the type of document being produced.
| Template | Description | Best for |
|---|---|---|
report | Multi-page report with cover page, table of contents, and numbered sections. The default template. | Detailed analyses, research findings, project updates |
brief | Compact 1--2 page summary format with tight spacing. | Executive summaries, status updates, quick overviews |
dashboard | KPI and chart-focused grid layout optimized for data visualization. | Performance dashboards, metrics reviews, data snapshots |
memo | Simple text-heavy format with minimal decoration. | Internal communications, meeting notes, recommendations |
Artifact Operations
The artifact capability supports three operations:
Create
Provide title and sections to create a new artifact. If an artifact already exists for this agent in the current run, it is overwritten.
The tool automatically prepends a cover page generated from the title and metadata.
Edit
Provide any combination of replace_sections, remove_sections, and add_sections to modify an existing artifact. Edit operations are applied in this order:
- Replacements -- Replace sections at specific indices with new content
- Removals -- Remove sections at specific indices (adjusted for prior replacements)
- Additions -- Append new sections to the end of the document
List
Provide no parameters to list all current sections with their indices. This is useful before editing -- the agent can see the current document structure and decide which sections to replace, remove, or add.
Agents typically call list before edit to inspect the current artifact state. This is normal tool behavior, not a sign of confusion.
Artifact Preview
When Can Create Artifacts is enabled on an assignment, the agent can also preview its artifact visually. The preview takes a screenshot of the current artifact as it would appear when rendered and returns the image directly to the agent.
| Aspect | Detail |
|---|---|
| Available when | Can Create Artifacts is enabled on the assignment |
| What it shows | The most recent artifact in the current run, rendered as it would appear to a viewer |
| Returns | A screenshot image of the rendered artifact |
The agent can call preview_artifact after creating or editing an artifact to visually verify:
- Chart rendering and data accuracy
- Table layout and alignment
- KPI card formatting
- Image placement and sizing
- Overall document structure
This is especially valuable in multi-stage workflows where a later agent refines the artifact -- it can preview the current state before deciding what to change.
Mention the preview tool in your task directive to encourage agents to self-check: "After building the dashboard, preview it to verify the charts render correctly. Fix any issues."
Cross-Stage Editing
Artifacts persist across stages within a workflow run. An agent in Stage 2 can edit an artifact created in Stage 1, provided:
- The agent in Stage 2 has Can Create Artifacts enabled on its assignment.
- The artifact was created by the same agent (same agent identity across stages) or is the most recent artifact in the run.
The recommended pattern for multi-stage artifact workflows:
- Stage 1 -- Agent creates the initial artifact with core content.
- Stage 2 -- Same or different agent calls list to inspect the artifact, then uses edit operations to refine, extend, or update it.
This avoids recreating the entire document from scratch and produces more consistent results.
Seed Documents
Stages can reference project documents as seed documents. These are loaded into the agent's context when the stage begins, providing structured input data for artifact generation.
Configure seed documents in the assignment drawer by selecting documents from the project's document library. The agent receives the full document content alongside its task directive, stage description, and upstream stage results.
Seed documents are read-only context -- the agent cannot modify the source documents. They serve as input data that the agent analyzes, summarizes, or incorporates into the artifact.
Artifact Persistence and Knowledge Graph
After a run completes, artifacts can be saved to the project's document library. The behavior depends on the project's Long-Term Memory configuration:
| Configuration | Save behavior | Classification |
|---|---|---|
| Long-Term Memory enabled, Open knowledge source | Automatic -- artifact is saved when the run completes | Automatic -- document is classified into the knowledge graph by the Knowledge Curator |
| Long-Term Memory enabled, Curated knowledge source | Manual -- click Save to Documents on the artifact card | On save -- document is classified into the knowledge graph when saved |
| Long-Term Memory disabled | Manual -- click Save to Documents on the artifact card | None -- document is saved but not classified |
Saved artifacts appear as PDF documents in the project's document library and are available as seed documents for future workflow runs.
PDF Export
Click Download PDF on any artifact card to generate and download a PDF. The platform renders the artifact spec through a sidecar service that applies the selected template's formatting:
- Pagination with headers and footers
- Table of contents (for report template)
- Chart rendering as static images
- Consistent typography and spacing
The PDF is streamed directly to the browser -- no intermediate file storage is required.
Publishing (Share Links)
Artifacts can be published to generate a public share link that anyone can access without logging in.
| Action | Button | Effect |
|---|---|---|
| Publish | Click Publish on the artifact card | Generates a unique share URL (e.g., https://your-domain/shared/abc123...) and displays it in a copyable text input |
| Unpublish | Click Unpublish on the artifact card | Revokes the share link immediately -- the URL stops working |
Published artifacts render with the same full formatting as the in-browser preview: charts, tables, KPI cards, images, callouts, and styled headings. The viewer sees a standalone page with no platform chrome -- just the artifact content.
Share link behavior
- Each artifact gets a unique UUID-based URL when published.
- The link requires no authentication -- anyone with the URL can view the artifact.
- Unpublishing destroys the token. If you re-publish, a new URL is generated.
- Published artifacts are read-only for viewers. Only platform users with access to the workflow run can publish or unpublish.
Use cases
- Stakeholder reports -- Share weekly performance dashboards with managers who don't have platform accounts.
- Client deliverables -- Send analysis results directly to clients via the share link.
- Team reviews -- Share a draft artifact for feedback before finalizing.
Stable Document URLs
Images and documents embedded in artifacts use permanent proxy URLs that never expire. The platform serves these files through a stable endpoint (/files/:id/filename) instead of time-limited cloud storage URLs.
This means:
- Artifacts viewed days, weeks, or months after creation still display all images correctly.
- Published share links continue to render embedded images indefinitely.
- PDF exports always include the correct images regardless of when the export is generated.
Previously, presigned storage URLs expired after a short period, which could cause broken images when viewing older artifacts. This is no longer an issue -- all document references in artifacts are permanent.
Viewing Artifacts in the Browser
Artifacts render as interactive HTML on the workflow run page under the Artifacts tab:
- Multiple artifacts appear as tabbed pills -- click each tab to switch.
- Charts are interactive -- hover for tooltips showing exact values.
- Tables render with formatting, alignment, and optional row highlighting.
- KPI cards display metrics with color-coded trend indicators (green for up, red for down).
- Callouts render as styled boxes matching their style (info = blue, warning = yellow, success = green).