Artifact Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The Artifact Protocol is a structured communication system designed to manage and execute complex tasks—such as file creation and shell command execution—generated by an AI assistant. It provides a mechanism to encapsulate these tasks within "Artifacts," which are rendered as interactive UI components in the chat interface. These artifacts act as containers for "Actions," which are the actual units of work executed within the project environment.
By using specific XML-like tags within the LLM's streaming response, the system can identify, parse, and initialize workbench environments in real-time. This allows the user to see a live representation of the AI's progress as it modifies the filesystem or runs terminal commands. Sources: app/lib/runtime/message-parser.ts, app/lib/stores/workbench.ts, README.md
Architecture and Data Flow
The Artifact Protocol follows a streaming-first architecture. As the AI generates text, a StreamingMessageParser scans for specific opening tags (<boltArtifact> and <boltAction>). When these tags are detected, the parser triggers callbacks that update the application state via the WorkbenchStore.
Communication Flow
The following diagram illustrates the flow from the raw LLM stream to the UI execution:
The flow ensures that artifacts are initialized immediately upon detection, while actions are processed as their content becomes fully available in the stream. Sources: app/lib/runtime/message-parser.ts:47-150, app/lib/hooks/useMessageParser.ts:9-36
Core Components
1. Streaming Message Parser
The StreamingMessageParser is responsible for identifying the protocol's syntax within a raw string of text. It maintains a MessageState to handle chunks of data arriving at different times, ensuring that tags split across multiple packets are correctly reconstructed.
- Artifact Tags:
<boltArtifact title="Title" id="unique_id"> - Action Tags:
<boltAction type="file" filePath="path/to/file">or<boltAction type="shell">
Sources: app/lib/runtime/message-parser.ts:10-45, app/lib/runtime/message-parser.spec.ts:46-130
2. Workbench Store
The WorkbenchStore serves as the central state management for all artifacts. It tracks which artifacts are open, their titles, and associates each with an ActionRunner that handles the execution of contained tasks.
| Function | Description |
|---|---|
addArtifact | Initializes a new artifact state and adds it to the artifactIdList. |
updateArtifact | Updates properties like title or closed status. |
addAction | Registers a new action (file or shell) to an existing artifact's runner. |
runAction | Triggers the execution logic for a specific action. |
Sources: app/lib/stores/workbench.ts:213-267
3. Artifact UI Component
The Artifact component renders the visual container in the chat. It provides a summary of the artifact (title) and a collapsible list of actions.
- Status Indicators: Actions display their current state:
pending,running,complete,failed, oraborted. - Interactivity: Clicking the artifact header toggles the Workbench view to show the code or preview.
Sources: app/components/chat/Artifact.tsx:32-100
Action Types
The protocol supports two primary types of actions defined by the type attribute in the <boltAction> tag.
Action Definitions
| Type | Required Attributes | Description |
|---|---|---|
file | filePath | Writes the tag's content to the specified file path in the WebContainer filesystem. |
shell | None | Executes the tag's content as a command in the terminal. |
Sources: app/lib/runtime/message-parser.ts:162-185, app/components/chat/Artifact.tsx:135-165
Integration with Markdown
Artifacts are integrated into the chat through a custom Markdown renderer. When the Markdown component encounters a div with the class __boltArtifact__ (generated by the parser), it intercepts the rendering to mount the React Artifact component instead of standard HTML.
// app/components/chat/Markdown.tsx:28-40
div: ({ className, children, node, ...props }) => {
if (className?.includes('__boltArtifact__')) {
const messageId = node?.properties.dataMessageId as string;
if (!messageId) {
logger.error(`Invalid message id ${messageId}`);
}
return <Artifact messageId={messageId} />;
}
// ... standard div rendering
}
Sources: app/components/chat/Markdown.tsx:28-40, app/lib/runtime/message-parser.ts:192-205
Conclusion
The Artifact Protocol is the backbone of the interactive development experience in the console. By combining real-time streaming state parsing with a robust workbench store, it allows an AI assistant to move beyond simple text responses and actively manage a full-stack development environment. This system ensures that every file change and command execution is tracked, visualized, and executed reliably within the browser-based sandbox.