For the complete documentation index, see llms.txt. This page is also available as Markdown.

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/me endpoint

  • Comprehensive 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 - EventEncoder for 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.action is absent - return the initial screen.

  • When the user clicks a button, action.name identifies which button, and action.context contains 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. catalogId is required by the A2UI protocol and is always the same value. theme and sendDataModel are Studio extensions.

  • updateComponents - the component tree.

  • updateDataModel - initial form data.

Component rules

  1. The first component must have id: "root" and component: "Column".

  2. Every component needs a unique string id.

  3. Components reference children by ID - the list is flat, not nested.

  4. Button requires a separate Text child for its label.

  5. 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:

  1. Ensure your endpoint is publicly accessible.

  2. Submit your workflow name and endpoint URL to your Monterosa account manager.

  3. 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") with replace: true so each UI snapshot replaces the previous one.

  • Persist with state, not databases - use STATE_SNAPSHOT to 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.state being undefined (e.g. if the user refreshes).

Event Reference

Event
Purpose

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