> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts

> Turn Agent and plugin output into durable, versioned, previewable, downloadable, and shareable results.

# Artifacts

Artifacts turn the work produced by Xpert Agents and plugins into durable results that people can open, revisit, download, and share.

An Artifact is a persistent product object with a stable identity. Its content is stored as immutable versions in Workspace Files, while access is provided through separately managed Artifact Links. A report can therefore gain a new version without changing its identity, and a shared link can either follow the latest version or remain pinned to one version.

<Tip>
  An Artifact is more than a file link. The Artifact owns the result's identity and lifecycle; an Artifact Version owns one immutable content snapshot; an Artifact Link controls who can open which version.
</Tip>

## When to use an Artifact

Use an Artifact when chat text is not the best medium for the result, or when the result needs to live beyond one Agent run. Typical examples include:

* interactive HTML reports and dashboards;
* presentations generated by Presentation Studio;
* static site snapshots produced by Sites;
* PDF reports, PPTX decks, images, CSV files, and other downloadable outputs;
* visual comparisons, annotated reviews, timelines, and checklists;
* a result that a plugin will update by publishing additional versions.

For example, a Presentation Studio deck can remain editable in its Workbench while each HTML export becomes an Artifact Version. A user can then publish a link that always opens the newest HTML export, or pin a link to the exact version used for a review.

## What an Artifact is not

An Artifact is a published result, not a full hosted application runtime.

* It does not expose a plugin's backend or credentials to viewers.
* It is not a replacement for a database-backed, multi-route application.
* It does not make the shared content collaboratively editable.
* Interactive HTML can run client-side interactions allowed by its security profile, but it should not depend on external services or platform APIs at view time.
* Version updates are durable, but an already open viewer currently needs to refresh to resolve a newer `latest` version.

Use an Agentic App or Sites deployment when the experience needs authenticated backend operations, durable form submissions, multiple routes, or real-time collaboration.

## Core model

| Object                  | Purpose                                                                                                                                | Mutability                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Artifact**            | Stable container for a generated result, including its source, kind, scope, title, description, and current version.                   | Metadata and lifecycle can change.                                  |
| **Artifact Version**    | One content snapshot stored through a portable Workspace Files reference, with MIME type, checksum, size, and source version metadata. | Immutable after creation.                                           |
| **Artifact Link**       | An access entry point with a short slug, audience policy, expiry, download policy, and `latest` or fixed-version behavior.             | Access and presentation policy can change; the link can be revoked. |
| **Artifact Access Log** | Audit record for access, download, denial, expiry, revocation, archive, and deletion events.                                           | Append-only audit data.                                             |

Content bytes remain in Workspace Files. The Artifacts service stores portable file references and product metadata, rather than local filesystem paths or copied credentials.

## Create an Artifact

Artifacts are normally created by an Xpert Agentic App or plugin after it has produced a useful result. The product flow is:

1. Generate or export the content.
2. Write the content to Workspace Files.
3. Create or locate the stable Artifact container using the plugin's business resource identity.
4. Add an immutable Artifact Version that references the Workspace Files object.
5. Optionally create a preview or sharing link.

Creating an Artifact does not make it public. Until a link is created, it remains a private platform object within its tenant and organization scope.

## Update an Artifact

Publishing updated content creates a new Artifact Version. Existing versions are not overwritten.

Each Artifact has a `currentVersionId`. A new version becomes current by default, although a plugin can create a version without changing the current pointer. This supports review and staged publication workflows.

Artifact Links have two version modes:

| Mode      | Behavior                                                                                                               |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `latest`  | Resolves the Artifact's current version whenever the link is opened. Use this for an “always share latest” experience. |
| `version` | Resolves one immutable `artifactVersionId`. Use this for approvals, audit evidence, and reproducible handoffs.         |

Changing content never silently rewrites an old version. To show updated content through a fixed-version link, explicitly retarget the link or create a new link.

## Preview an Artifact

Use a signed preview link for temporary review before publishing. Signed previews:

* use the `signed_preview` access mode;
* include an opaque token in the `xpert_artifact_preview` query parameter;
* expire after 15 minutes by default;
* can be given a shorter or longer TTL within the platform limit;
* must not be persisted as a durable public URL.

The preview token is returned only when the link is created. The platform stores its hash, not the token itself.

## Share an Artifact

Sharing is an explicit access decision applied to an Artifact Link. The underlying chat, Agent run, plugin state, tenant identifiers, and Workspace Files location are not included in the public URL.

The canonical public route is:

```text theme={null}
https://<xpert-public-base>/artifacts/share/<artifact-link-slug>
```

Downloads use:

```text theme={null}
https://<xpert-public-base>/artifacts/share/<artifact-link-slug>/download
```

The slug is a compact, random 12-character identifier. It is the Artifact Link's public handle, not an Artifact ID or database UUID. Plugins must copy the `publicUrl` returned by the platform and must not construct a URL from the browser's current location.

### Access modes

| Access mode         | Who can open it                                                     | Typical use           |
| ------------------- | ------------------------------------------------------------------- | --------------------- |
| `owner_only`        | The Artifact owner.                                                 | Private review.       |
| `workspace_all`     | Authorized members in the scoped workspace context.                 | Project-team handoff. |
| `organization_all`  | Authorized members of the organization.                             | Internal publishing.  |
| `custom_principals` | Explicitly selected principals in the same tenant and organization. | Limited review group. |
| `public_link`       | Anyone on the web who has the link.                                 | External sharing.     |
| `signed_preview`    | Anyone holding the unexpired preview token.                         | Short-lived preview.  |

<Warning>
  Creating a `public_link` requires explicit user confirmation. Agents and plugins must not publish a result to the public web silently. Public sharing exposes only the Artifact content; the conversation and plugin workspace remain private.
</Warning>

The link also controls whether content opens inline or as an attachment and whether the dedicated download route is enabled.

## Revoke, archive, and delete

* **Revoke a link** when the Artifact should remain available internally but a particular access path must stop working. Revocation takes effect immediately.
* **Archive an Artifact** when it should no longer be active but should remain in platform history and audit records.
* **Delete an Artifact** to mark the Artifact as deleted and revoke all of its links. Plugins that own the underlying Workspace Files object should separately apply their file-retention or deletion policy.

Revoked, expired, archived, and deleted content returns an explicit access error instead of falling back to another version or file.

## Supported content

Artifacts describe the product kind independently from the MIME type. Supported kinds include `html`, `markdown`, `pdf`, `pptx`, `image`, `file`, `site`, and `presentation`.

Expected presentation behavior:

| Content                                       | Recommended behavior                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------- |
| Self-contained HTML, sites, and presentations | Open inline using the selected HTML safety profile.                             |
| PDF and supported images                      | Open inline when the browser supports the MIME type; optionally allow download. |
| Markdown, text, JSON, and CSV                 | Serve as text or download according to the product surface.                     |
| PPTX, ZIP, and generic files                  | Prefer download.                                                                |

The platform validates the declared MIME type and the referenced Workspace Files object. A supplied size or SHA-256 value must match the stored content.

## HTML security profiles

HTML Artifacts are served with `nosniff`, `no-referrer`, `no-store`, a safe content disposition, and a Content Security Policy. Forms cannot submit, the document cannot set a base URL, and the Artifact cannot be embedded by another page.

| Profile       | Use it for                                                                | Behavior                                                                                                     |
| ------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `strict`      | Reports, documents, and static presentations that do not need JavaScript. | Scripts and network access are disabled; inline styles and embedded data/blob media are allowed.             |
| `interactive` | Self-contained charts, controls, and presentation playback.               | Inline client-side scripts and embedded data/blob resources are allowed; arbitrary external origins are not. |

Artifacts must not contain platform tokens, tenant or organization identifiers, Workspace Files paths, signed URLs, or other credentials. User-controlled HTML, SVG, URLs, and media should be validated by the producing plugin before publication.

## Use Artifacts from a plugin

Plugins use the `platform.artifacts` runtime capability from `@xpert-ai/plugin-sdk`. Workspace Files remains the content storage capability; Artifacts manages identity, versions, access, safety policy, and audit.

```ts theme={null}
import {
  ArtifactsRuntimeCapability,
  WorkspaceFilesRuntimeCapability
} from '@xpert-ai/plugin-sdk'

const files = runtimeCapabilities.require(WorkspaceFilesRuntimeCapability)
const artifacts = runtimeCapabilities.require(ArtifactsRuntimeCapability)

const file = await files.writeRuntimeBuffer({
  tenantId,
  userId,
  catalog: 'xperts',
  scopeId: xpertId,
  xpertId,
  folder: 'reports',
  fileName: 'quarterly-report.html',
  originalName: 'quarterly-report.html',
  mimeType: 'text/html',
  buffer: Buffer.from(html, 'utf8')
})

const artifact = await artifacts.createArtifact({
  source: {
    pluginName: '@xpert-ai/plugin-example',
    resourceType: 'quarterly_report',
    resourceId: reportId
  },
  kind: 'html',
  title: 'Quarterly report'
})

const version = await artifacts.createArtifactVersion({
  artifactId: artifact.id,
  workspaceFileRef: file.reference,
  mimeType: 'text/html',
  fileName: 'quarterly-report.html'
})

const link = await artifacts.createArtifactLink({
  artifactId: artifact.id,
  artifactVersionId: version.id,
  versionMode: 'version',
  access: {
    mode: 'public_link',
    userConfirmedPublicLink: true
  },
  presentation: {
    disposition: 'inline',
    allowDownload: true,
    safeHtmlProfile: 'strict'
  }
})

console.log(link.publicUrl)
```

The capability provides operations to create, version, get, list, archive, and delete Artifacts, as well as create signed previews, create or update links, and revoke links.

### Plugin responsibilities

* Use a stable `pluginName + resourceType + resourceId` for the Artifact container.
* Store bytes through Workspace Files and persist only portable references.
* Create a new version instead of replacing published bytes.
* Ask for explicit confirmation before creating a public link.
* Return and copy the platform-provided `publicUrl`.
* Revoke links before deleting plugin-owned exported files.
* Keep large file bodies, HTML, tokens, and private identifiers out of tool results and logs.

## Current release boundaries

The current platform capability provides the Artifact data model, immutable versions, Workspace Files-backed content, scoped and public links, signed previews, access counters, and audit records. Product surfaces such as a platform-wide Artifact gallery, automatic in-page live updates, organization retention controls, and a compliance administration UI can be added on top of the same model; do not assume those surfaces are available unless your Xpert deployment exposes them.

## Related resources

* [Plugin development](../../plugin/index)
* [Remote components and Agentic Apps](../../plugin/remote-component)
* [Claude Code Artifacts](https://code.claude.com/docs/en/artifacts), the product concept used as a reference for this Xpert capability