Artifacts

The deliver_file tool

Agents deliver files through the mcp__user-input__deliver_file MCP tool, part of the built-in user-input MCP server available to every agent. It 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.

Delivery is non-blocking. Unlike tools that request user input, such as request_secret or request_file, deliver_file resolves immediately, so an agent can deliver multiple files in sequence without pausing.

How delivery appears in the UI

A delivered file shows up in the session's message thread.

Collapsed view

By default, the tool call appears as a compact row labeled "Deliver File" with a download pill showing the filename, a file-type icon, and a download button. Click the pill to download the file 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)

Streaming view

While the tool call is still streaming in, the row shows "Preparing file..." or "Delivering: filename", depending on how much of the input has arrived.

Accessing delivered files

Delivered files are served from the agent's workspace on the host filesystem. A download link fetches:

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

The file is served as a download (Content-Disposition: attachment), so the browser saves it to the downloads folder. The server is path-traversal protected and only serves paths inside the agent's workspace.

Files remain available as long as the agent exists and the file stays in the workspace. Unlike dashboards, downloads do not require the agent to be running.

deliver_session

Agents also have a deliver_session tool (mcp__user-input__deliver_session) for multi-agent workflows, where one agent hands off a completed session to another. It appears in the conversation as an inline session reference. Parameters:

• 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.

See X-Agent for the orchestration system that uses it.

Relationship to dashboards

Artifacts are point-in-time deliveries: the agent creates a file, hands it over, and moves on. Dashboards are live applications that update in real time and persist across sessions. A single workflow can use both, such as a live metrics dashboard alongside a weekly PDF summary delivered as an artifact.