Skip to main content

Artifacts

Artifacts are BotDojo’s first-class record for agent outputs that need to be rendered, referenced, and optionally executed later.

What an artifact is​

An artifact is a project-scoped record that points at exactly one render source in v1:

  • a document_id for BotDojo-managed files such as markdown, PDF, DOCX, or PPTX
  • a url for URL-backed content such as hosted MCP app HTML

Artifacts also carry the metadata needed to place that output back into the product:

  • type such as markdown, pdf, docx, pptx, or mcp_app
  • optional origin fields like flow_id, flow_request_id, workspace_id, or work_queue_item_id
  • optional persisted state and actionResults history for interactive MCP app artifacts
  • optional config.action for the artifact's first-class configured action
  • optional config.action.mcr_uri when the artifact needs one linked external tool surface

Rendering​

BotDojo renders artifacts through a single in-app renderer:

  • Markdown uses the same markdown pipeline already used in chat and reports.
  • PDF uses a signed document URL and embedded viewer flow.
  • DOCX and PPTX reuse the office preview renderer.
  • mcp_app mounts HTML in-app, pushes host context into the MCP app bridge, intercepts tool calls, and routes them through the Artifacts store.
  • Inside an mcp_app, tools/call can use the built-in artifact tool call_tool to invoke an arbitrary mcp_uri + tool_name + parameters payload through the server-side ResourceFactory path.

For document-backed files, the renderer asks the server for a fresh signed URL when the artifact is opened.

Work queues​

Work queues do not get a separate artifact property type in v1. They reuse the existing resource_reference pattern and store artifact URIs such as:

botdojo://project/core/artifacts/<artifactId>

That keeps artifact references compatible with the existing resource rendering flow while allowing inline previews and dedicated tabs in the work queue item UI.

MCP tools​

Artifacts expose two BotDojo MCP surfaces:

botdojo://project/core/artifacts/TOOLS.md
botdojo://project/core/artifacts/<artifactId>

Collection tools:

  • artifact_create
  • artifact_create_document creates a BotDojo document under /artifacts/ and returns its document_id
  • artifact_create_from_workspace copies a workspace text file into a new document-backed artifact
  • artifact_load
  • artifact_list_in_workspace
  • artifact_list_in_session
  • artifact_view shows an artifact in chat by artifact_id without opening the artifact-scoped MCP first
  • artifact_query

Artifact-scoped tools:

  • artifact_update
  • artifact_update_file
  • artifact_update_file_from_workspace
  • artifact_view also works on artifact-scoped MCPs and defaults to the current artifact
  • artifact_update_state
  • artifact_execute_tool
  • artifact_export
  • artifact_sync

The Artifacts store is the canonical execution API. The MCP tools resource wraps those store methods.

artifact_execute_tool supports the artifact built-ins (view, update_state, update, call_tool) as well as linked-MCR passthrough when the artifact is configured with config.action.mcr_uri.

For text-backed artifacts, the file helpers let you bootstrap or replace the backing render source without manually creating a DocumentRecord first. artifact_update_file will create a backing /artifacts/ document automatically when the artifact does not already have one.

Current limits​

The current implementation keeps scope intentionally narrow:

  • artifact access is authenticated and in-app only
  • existing report storage stays on its current document_id + artifactType model
  • work queue references are URI-first
  • mcp_app supports one linked external MCR surface through config.action.mcr_uri
  • artifact actions run with the current user’s permissions