How should a Miiwa Builder design inputs for a Miiwa Agent?
A Miiwa Agent input contract is the set of guided fields, stable keys and validation choices that turn a user submission into named variables for a published workflow.
The first interface decision in a Miiwa Agent is not how polished the form looks. It is which facts the workflow needs, how those facts are named and what a user must understand before submitting them. Miiwa carries that contract from the User Input block into the native runtime.
Why is input part of the workflow graph?
A User Input block makes the human boundary explicit. It can collect fields when a run begins or pause an active workflow until a person supplies more information. The submitted payload then joins the runtime variables used by downstream blocks.
Because the input request is a block, a Builder can see where the workflow depends on a person, which path follows the answer and whether the same design is compatible with unattended triggers.
What should each input field define?
| Field property | Purpose in Miiwa |
|---|---|
| Key | The stable machine name used in the input payload and workflow variables. |
| Label | The human-readable question or name shown to the user. |
| Type | The control and value shape, such as text, number, choice or file-oriented input. |
| Required | Whether the user may continue without a value. |
| Help text and placeholder | Context that helps the user provide the right kind of answer without exposing the workflow internals. |
| Options | The allowed choices for fields that should not accept arbitrary text. |
| Allow multiple | Whether the field may submit more than one selected or uploaded value. |
How does Miiwa assemble the guided form?
A User Input block can reference dedicated User Input Field blocks by ID or carry inline field definitions. The published-agent reader normalizes either form into the same runnable field model: ID, key, label, type, required state, help text, placeholder, options and multiplicity.
When referenced field IDs are present, their order controls the delivered form. This lets a Builder keep reusable field blocks in the graph while still designing the sequence the user experiences.
What does Miiwa require before publish?
A publishable User Input block needs at least one inline field or referenced field ID. If the Builder chooses a custom interface, Miiwa also requires valid canvas sections in Canvas mode or custom interface markup in source mode. A visually empty input step cannot pass publish readiness.
How do submitted values reach later blocks?
The assigned-run API accepts the submitted input payload after authentication, trusted-origin and assignment checks. At execution, Miiwa builds the initial variable set from configured global and user variables, any persisted variables from a resumed run, integration context and the effective input payload. Downstream blocks read the named values from that runtime state.
What changes when input is requested mid-run?
When a User Input block pauses, Miiwa stores the current block and the workflow variables in the run session. A later submission claims that same paused session, merges the new input and resumes from the next valid block instead of starting the earlier work again.
A Builder checklist for better inputs
- Start from the downstream decision and list only the values it truly needs.
- Give every value a stable, descriptive key before writing prompts that reference it.
- Use constrained options when the workflow expects one of a known set of values.
- Mark a field required only when the graph cannot produce a valid outcome without it.
- Explain business meaning in labels and help text; keep block and variable terminology out of the user experience.
- Test empty, malformed, long and resumed submissions before publishing.
- Test automated triggers separately and remove any accidental dependency on human input.
A good Miiwa Agent input is a workflow contract: a small set of understandable fields with stable keys that the runtime can bind predictably into the graph.
Common questions
- Does every Miiwa Agent need a User Input block?
- No. Webhook, email, schedule, browser-extension or MCP-triggered workflows can receive their context through the trigger. Use User Input when a person must supply or confirm information as part of the run.
- Can a Builder create a custom interface for agent input?
- Yes. A User Input block can use the native form or a custom interface. Before publish, custom Canvas mode needs a valid canvas with sections, while custom source mode needs interface markup.
- What happens to variables when a user resumes a paused Miiwa Agent?
- Miiwa reloads the persisted variables from the paused run, merges the new submission into the effective input and continues the same session from the resolved next block.