Agent workflow patterns

MIOSA workflows scale from a single prompt to a fleet of long-running agents. The same primitives apply at every level:

prompt -> agent runtime -> assigned device -> event stream -> durable output

Use this page to choose the right workflow for your product.

Pattern 1: one-shot run

Use this for quick checks, small scripts, inspections, summaries, and health tests.

miosa run "check if the preview server is healthy" --device sandbox:<id>

Expected behavior:

1. CLI sends the prompt to MIOSA.
2. MIOSA chooses or validates the device.
3. Runtime executes a short task.
4. CLI prints the answer and any structured output.
5. Credits are charged for model usage and device time.

Use this when the user does not need a long-lived session.

Pattern 2: prompt into a sandbox

Use this when the agent should code, generate artifacts, run tests, or start a preview.

miosa sandbox prompt <sandbox-id> 
  --runtime codex 
  --cwd /workspace 
  -- "Build a Next.js landing page, run it on port 3000, and fix any errors."

The agent should work inside /workspace:

• write files
• install dependencies
• run tests
• start dev server
• inspect errors
• save artifacts
• snapshot checkpoints
• publish when approved

Pattern 3: prompt into a computer

Use this when the task requires a real browser, GUI, login flow, or visual QA.

miosa computer prompt <computer-id> 
  --runtime claude-code 
  -- "Open the app preview, test signup, capture screenshots, and report issues."

The computer device can:

• open URLs
• click buttons
• type into forms
• scroll
• log in to dashboards
• inspect UI states
• take screenshots
• use terminal or desktop apps

Use a computer after a sandbox creates a preview, or as the primary runtime for browser-heavy automation products.

Pattern 4: detached agent session

Use this for tasks that continue after the first command returns.

miosa agent start 
  --device sandbox:<id> 
  --runtime osa 
  --prompt-file task.md 
  --detach 
  --json

Then inspect and continue the session:

miosa agent events <session-id> --follow
miosa agent task <session-id> "Now add authentication and update the README."
miosa agent artifacts <session-id>
miosa agent stop <session-id>

Detached sessions should not require a terminal UI to keep running. A TUI is a view, not the execution model.

Session requirements:

• session id returned immediately
• events available over API and CLI
• reconnectable stream
• durable transcript
• artifacts linked to session
• clean stop/cancel
• typed failure state
• clear credit usage

Pattern 5: app-builder loop

Use this for Lovable, Replit, v0, or ClinicIQ-style app generation.

User prompt
  -> create/resume sandbox
  -> agent edits files in /workspace
  -> run install/build/test
  -> start preview
  -> stream files and preview URL to UI
  -> user asks for edits
  -> agent patches same sandbox
  -> snapshot stable state
  -> publish to deployment

Recommended UI:

• chat
• file tree
• command log
• preview frame
• artifacts panel
• deployment status
• version history
• credit usage

Recommended backend records:

projects
  current_sandbox_id
  current_deployment_id
  latest_snapshot_id

agent_runs
  project_id
  sandbox_id
  prompt
  status
  idempotency_key

Pattern 6: artifact workspace

Use this for Claude Desktop-style work where the agent creates documents, images, diagrams, or data files.

Examples:

• proposals
• DOCX files
• PDFs
• pitch decks
• diagrams
• brand assets
• CSV reports
• HTML previews
• ZIP bundles

Flow:

prompt -> sandbox -> generate file -> render/validate -> artifact -> version

The UI should show:

• live text/code generation
• generated file cards
• preview pane
• download button
• revision history
• “make changes” prompt attached to the artifact

Pattern 7: browser operator

Use this for Nebula-style browser work or RPA-like workflows.

prompt -> computer -> browser session -> screenshots/events -> report/action

Examples:

• fill onboarding forms
• verify checkout
• inspect admin dashboards
• scrape authenticated data
• test browser UI
• run visual QA on previews

Human approval should be required before:

• submitting external forms
• sending messages
• spending money
• deleting data
• changing account settings
• using admin credentials

Pattern 8: orchestrated agent team

Use this for Cofounder (cofounder.co), Polsia, Agentfounder, or internal operator products.

The orchestrator should:

• break the prompt into tasks
• assign devices and runtimes
• enforce budget and approvals
• stream each child run
• merge artifacts
• ask for human approval on risky actions
• produce one final status

Use child devices only when they create real leverage. Not every task needs a new sandbox.

Pattern 9: agent fleet

Use this when the product launches tens, hundreds, or thousands of workers.

Examples:

• large test matrices
• lead enrichment
• website audits
• browser QA sweeps
• benchmark runs
• research crawls
• parallel code migrations

Fleet requirements:

Choosing the pattern

See also