Artifacts

Artifacts are files that agents deliver to users during a conversation. When an agent generates a report, creates a dataset export, builds an image, or produces any other file output, it uses the deliver_file tool to hand that file to you directly in the chat.

The deliver_file Tool

Agents deliver files through the mcp__user-input__deliver_file MCP tool, which is part of the built-in user-input MCP server available to every agent. The tool accepts two parameters:

• filePath -- The path to the file inside the agent's workspace (e.g. /workspace/output/report.pdf).
• description -- An optional description of what the file contains.

File delivery is non-blocking. Unlike tools that request user input (such as request_secret or request_file), deliver_file resolves immediately and the agent continues its work without waiting for acknowledgment. This means an agent can deliver multiple files in sequence without pausing.

How Delivery Appears in the UI

When an agent delivers a file, it shows up in the session's message thread in two forms:

Collapsed View

In the default collapsed state, the tool call appears as a compact row labeled "Deliver File" with a download pill next to it. The pill shows the filename with a file-type icon and a download button. You can click the pill to download the file directly without expanding the message.

Expanded View

Clicking the tool row expands it to show:

• The file description (if provided)
• The filename with its type icon
• A "Download" button
• The tool result (success or error status)

Streaming View

While the agent is still in the process of calling the tool, you see a "Preparing file..." or "Delivering: filename" message, depending on how much of the tool input has been streamed.

Accessing Delivered Files

Delivered files are served from the agent's workspace on the host filesystem. When you click a download link, the browser fetches the file from:

/api/agents/{agentSlug}/files/{relativePath}

The file is served as a download (with Content-Disposition: attachment), so your browser will save it to your downloads folder. Files are path-traversal protected -- the server ensures that the requested path stays within the agent's workspace directory.

Files remain available as long as the agent exists and the file has not been deleted from the workspace. Unlike dashboards, file downloads do not require the agent to be running -- the files are read directly from the host filesystem.

deliver_session

In addition to deliver_file, agents have access to a deliver_session tool (mcp__user-input__deliver_session). This is used in multi-agent workflows where one agent hands off a completed session transcript to another. It accepts:

• session_id -- The ID of the session to deliver.
• agent_slug -- The slug of the agent that owns the session.
• description -- An optional description of the session contents.

This tool is primarily used by the cross-agent orchestration system and appears in the conversation as an inline session reference.

Relationship to Dashboards

While both dashboards and artifacts live in the agent's workspace, they serve different purposes:

• Artifacts are point-in-time file deliveries. The agent creates a file, hands it to you, and moves on. You get a downloadable snapshot.
• Dashboards are live, interactive applications that the agent builds and serves. They update in real time and persist across sessions.

An agent might use both together -- for example, building a live metrics dashboard while also delivering a weekly PDF summary as an artifact. The dashboard provides an interactive view; the artifact provides a portable, shareable document.