Agent DocsDeveloper documentation
Builder Guide

Running a Workflow (Studio)

Start and watch runs from Studio; the input model becomes the start form

Running a workflow (Studio)

Audience: Customer developers and admins. Once your workflow is synced, you start and watch runs from the Studio → Processes page — no code required to trigger one.

You develop a workflow in your repo (see The dev loop), and it appears in Studio as a workflow definition you can start with a form. The form is built automatically from the workflow's declared input model — so a business user can run it without touching Python.

Where: Studio → Processes

Open /studio/processes on your instance. The page has two tabs:

  • Instances — running and finished workflow runs (status, timing, the current step, any pending human review).
  • Deployed workflows — the workflow definitions available to you. Click this tab (the toggle at the top of the page) to see and start them.

Each definition shows its name, version, owner, last-updated time, status, and whether it takes input, plus a badge:

  • released — a team-wide workflow, available to everyone in your tenant.
  • draft — your synced workflow from the dev loop (your overlay), visible and runnable only by you while your dev shell is running.

The list refreshes on its own (polls every few seconds), so a workflow you just synced from ./dev.sh shows up without a reload.

The start form is your input model

When you click a definition, Studio opens a Start form. That form is generated from the workflow's input_model — the Pydantic model you declared in WorkflowRequirements (see Building a workflow). Its fields become the form fields:

  • str → text input · bool → toggle · int/float → number input · a base64/binary field → file upload.
  • Required fields are enforced before you can submit.
  • A workflow with no input_model shows just a Start button.
# workflow/workflow.py — the declared input model...
class ReviewInput(BaseModel):
    """The Studio start form renders these fields."""
    request: str
    case_id: str = "ref-1"

# ...declared in registration.py so Studio can render the form:
WORKFLOW_REQUIREMENTS = {
    "ReferenceReviewWorkflow": WorkflowRequirements(
        workflow_id="ReferenceReviewWorkflow",
        input_model=ReviewInput,   # <- this is the start form's schema
        invokes=["agent-finance-compliance"],
    ),
}

Change ReviewInput, commit, and the form updates on the next sync — the form is always in step with your code.

Starting a run

  1. Go to /studio/processes → Deployed workflows.
  2. Click your workflow.
  3. Fill the form (its fields are your input_model) and press Start.
  4. The run appears under Instances, where you can follow its progress — including any human-in-the-loop review it pauses for.
Scroll to zoom · Drag to pan · 100%

Draft runs need a live dev session. A draft workflow runs on your personal remote worker, which only exists while your dev shell (./dev.sh) is running. If you try to start a draft with no live session, Studio tells you to start your dev shell first. Released workflows have no such requirement.

Related