How to Build a Mica Workflow
How to leverage Mica (Monterosa Interaction Cloud Assistant) to build your own AI powered automations
This guide walks you through building a Mica Workflow - a backend web service that powers interactive experiences inside Studio's sidebar. We'll build the "Spot the Ball" workflow as a running example, though the same principles apply to any interactive workflow.
About the Spot the Ball Demo
"Spot the Ball" is an AI-powered workflow that automates the creation of interactive trivia content. This process leverages AI to:
Remove the ball from a sports photograph
Generate multiple choice answer options
Create an engaging trivia question format
This automation saves valuable content creation time by eliminating the need for manual photo editing and question generation. What traditionally might take 30 minutes per image can now be accomplished in seconds.
Example showing original image with ball → AI processing → image without ball + multiple choice overlay
Prerequisites
Familiarity with HTTP servers and JavaScript/TypeScript
Understanding of server-sent events (SSE)
Access to deploy a web service (AWS Lambda, Docker, etc.)
Overview
A Mica Workflow is an HTTP endpoint that receives POST requests from Studio and responds with a stream of events. Events tell Studio what UI to show, what state to persist, and when the interaction is complete.
Key concepts:
Streaming transport - responses use server-sent events (SSE), not classic JSON request-response.
Component-based UI - you describe what to show as a tree of components (text fields, buttons, cards, etc.) and Studio renders them.
Automatic state management - the framework stores workflow state between interactions and includes it in subsequent requests.
Action-driven flow - user interactions (button clicks) trigger new requests with resolved form data.
Starter Kit
The fastest way to start is from the Mica Workflow Starter Kit. Contact your Monterosa account manager for access.
The starter kit provides:
Multi-step workflow architecture - clean state management with automatic persistence between steps
Production-ready authentication - secure user verification using Studio's
/api/v2/meendpointComprehensive UI components - examples of text blocks, input fields, cards, and dynamic actions
TypeScript implementation - fully typed with proper interfaces
AWS Lambda deployment - ready-to-deploy configuration
Extensible foundation - easy to customise and extend for your specific needs
Step 1: Set Up the HTTP Endpoint
A workflow can be any HTTP server. The examples below use Hono, but Express, Fastify, or a raw Lambda handler all work.
Install the required dependencies:
@ag-ui/core- event type definitions (EventType,RunAgentInput,BaseEvent)@ag-ui/encoder-EventEncoderfor formatting the SSE stream
Create a POST endpoint that returns an SSE stream:
Every response must start with RUN_STARTED and end with either RUN_FINISHED or RUN_ERROR.
Set CORS headers to allow Studio to communicate with your endpoint (Access-Control-Allow-Origin: *).
Step 2: Implement Authentication
Every workflow must verify that the request comes from an authenticated Studio user. The Authorization header contains a bearer token, and forwardedProps.baseURL tells you which Studio instance to verify against.
On failure, emit RUN_ERROR - do not return a JSON error:
For role-based authorisation, use the /api/v2/{resource}/{id}/my_role endpoints.
Step 3: Handle the Request
Request format
Every interaction is a POST with a JSON body:
When the user first opens the workflow,
forwardedProps.actionis absent - return the initial screen.When the user clicks a button,
action.nameidentifies which button, andaction.contextcontains the resolved form values.
Action routing
Extract the action and route it with a switch:
Step 4: Build the UI
The UI is defined as a flat list of components sent inside an ACTIVITY_SNAPSHOT event. Components reference each other by ID.
Emitting UI
Wrap UI emission in a helper. Use a stable messageId and replace: true so each snapshot replaces the previous one:
The content.messages array always contains three parts:
createSurface- initialises the rendering surface.catalogIdis required by the A2UI protocol and is always the same value.themeandsendDataModelare Studio extensions.updateComponents- the component tree.updateDataModel- initial form data.
Component rules
The first component must have
id: "root"andcomponent: "Column".Every component needs a unique string
id.Components reference children by ID - the list is flat, not nested.
Buttonrequires a separateTextchild for its label.Input components bind to the data model with
{ path: "/form/..." }.
Example: the Spot the Ball form screen
When the user fills in the form and clicks "Generate", the server receives:
The { path: "..." } references are resolved against the current form data by the framework before sending.
Step 5: Manage State Across Interactions
Since each request is independent, use STATE_SNAPSHOT events to persist data between interactions. The framework stores the state and includes it as input.state in the next request.
This is how the Spot the Ball workflow maintains data between the generate and create steps without a database - generation stores the processed image URLs, and the create step reads them back to assemble the final experience.
Step 6: Show Progress
Use STEP_STARTED / STEP_FINISHED events to indicate processing stages. These appear as loading indicators in the UI.
For visual progress during long-running operations such as image processing, emit updated ACTIVITY_SNAPSHOT events as work progresses:
Step 7: Handle Errors
Emit RUN_ERROR for any error. The run ends after this event - do not emit RUN_FINISHED.
You can also show user-friendly error screens using emitUI with a retry button, then emit RUN_FINISHED normally - this keeps the workflow session alive so the user can try again.
Step 8: Submit for Review
Once your workflow is complete:
Ensure your endpoint is publicly accessible.
Submit your workflow name and endpoint URL to your Monterosa account manager.
The workflow will be reviewed using the verification and approval checklist.
Key Implementation Tips
Always authenticate first - verify the user before processing any actions.
Use a stable messageId - always use the same
messageId(e.g."a2ui-main") withreplace: trueso each UI snapshot replaces the previous one.Persist with state, not databases - use
STATE_SNAPSHOTto carry data between interactions. This keeps workflows stateless and simple.Keep responses lightweight - only include necessary data in components.
Handle missing state - always guard against
input.statebeing undefined (e.g. if the user refreshes).
Event Reference
RUN_STARTED
Emitted first. Signals the start of a run.
RUN_FINISHED
Emitted last. Signals successful completion.
RUN_ERROR
Signals an error. The run ends after this.
ACTIVITY_SNAPSHOT
Sends a full UI snapshot. The main way to render and update the interface.
STEP_STARTED
A named step has begun. Shown as a loading indicator.
STEP_FINISHED
A named step completed. Clears the loading indicator.
STATE_SNAPSHOT
Full state replacement. Persists data for the next interaction.
The protocol also supports incremental updates (ACTIVITY_DELTA, STATE_DELTA) and AI text streaming events, covered in the full API reference.
Beyond the Example
While this guide uses Spot the Ball as the example, the same patterns apply to any interactive workflow:
Content summarisation
Data analysis and visualisation
Multi-step form wizards
Approval workflows
Integration with external APIs
If you've followed the steps above, you should be ready to build and deploy your own workflow.
Last updated

