Make artifacts available

An assistant can publish an artifact when its conversation has a sandbox with artifacts enabled. Such a sandbox mounts /artifacts and adds the publish and render commands. This page covers the four ways a conversation gets one: the built-in Documents tool, a custom AI tool sandbox, an agent, and a direct API call.

When a conversation has a sandbox that can publish, the workspace also attaches the skills that explain each kind (make-artifacts, make-powerpoint-artifacts, make-word-artifacts and make-agentic-ui-artifacts). Nothing else needs to be configured for the assistant to know how to write the files.

The Documents tool

The built-in Documents tool is a sandbox that can publish every kind of artifact: .html, .md, .csv, .json, .jsonl and .a2ui. It appears under Manage → AI → AI Tools like any other tool, and the chat composer offers it switched on, so an ordinary chat can already publish unless the user turns it off.

In a custom assistant

An assistant template lists the tools it carries in ToolUIDs. Add the Documents tool to that list and every conversation with the assistant can publish.

In the admin pages, open the assistant and add Documents under its tools. Through the API, post the template to assistant/add:

curl -s -X POST "$HOST/api/chatai/assistant/add" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "Name": "Report writer",
    "PromptChat": "You write short reports. Publish each one as an artifact.",
    "ToolUIDs": ["ArTifacTs1111111111111"]
  }'

The response carries the new assistant's UID. Starting a chat with it needs no further option:

curl -s -X POST "$HOST/api/chatai/new-chat?assistantUID=$ASSISTANT" \
  -H "Authorization: Bearer $TOKEN"

Creating or editing an assistant is open to every user unless DisableUserCustomAssistants is on, and then it is limited to system administrators.

A tool in ToolUIDs is available only to users who may use it. The Documents tool has the access mode AllUsers.

In a direct chat call

post-message takes the tools, agents and skills for that one turn as ;-separated UID lists. The message text is the request body.

curl -s -X POST \
  "$HOST/api/chatai/post-message?chatUID=$CHAT&useTools=ArTifacTs1111111111111" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: text/plain" \
  --data-binary "Export the open incidents as a CSV"

The call answers with the UID of the message. The assistant's reply streams to the conversation, and a published artifact appears on it as a chip.

A custom AI tool sandbox

A sandbox you write yourself gets /artifacts and publish by declaring the kinds it wants. ISandbox.Artifacts is empty by default, which is the right answer for a sandbox that only answers questions. Declare kinds when the sandbox's answer is a deliverable.

public Mosaik.Schema.ArtifactType[] Artifacts => new[]
{
    Mosaik.Schema.ArtifactType.Markdown,
    Mosaik.Schema.ArtifactType.Csv
};

The available kinds are Html, Markdown, Csv, Json, Jsonl and A2ui. A sandbox can publish only the kinds it declares, so a sandbox that declares only Csv refuses a .html file. Declaring Pdf, the older name for Markdown artifacts, still gives a sandbox Markdown artifacts.

The source stays in the mount, so a later turn can read it and revise it.

Agents

An artifact belongs to a conversation, and an agent that runs inside one has a few limits.

• A sub-agent cannot publish. A run that a conversation delegated to writes its files in a directory of its own. The conversation that called it reads those files and publishes them.
• A call outside a chat cannot publish. publish fails with artifacts can only be published from inside a chat. Scheduled tasks and endpoints that run without a conversation have no place to attach the artifact.
• The conversation's tools decide. Whoever publishes does so through a sandbox in the conversation. Give the conversation the Documents tool and the assistant that is answering can publish.

To get an artifact out of delegated work, have the sub-agent write the content to a file and return its path, and have the parent assistant publish the file.

Interfaces and the conversation's tools

An .a2ui interface can call only the tools its conversation had when it was published. To let an interface run a tool, give the assistant that tool as well as the Documents tool. See Interfaces.

Settings

Related

• Skills