Actions and Steps
An Action is an AI-powered Action Flow. An Action Flow is composed of ordered steps.
Each step performs one focused operation, such as calling a model, transforming data, or using a tool.
Think of an Action as the full process, and steps as the individual decisions or operations inside that process.
Action Lifecycle
An Action usually goes through these phases:
- Design: define the goal and required inputs.
- Build: add and configure steps.
- Test: run manually with sample data.
- Observe: inspect run details and failures.
- Improve: refine logic, prompts, and integrations.
How Steps Work Together
- Steps run in a flow from one step to the next.
- Output from earlier steps can be used in later steps.
- You can branch logic and handle errors with dedicated step types.
If one step fails or returns unexpected output, that usually affects downstream steps. This is why clear step boundaries and validation are important.
Example Flow
A common invoice-processing Action might look like this:
- Read document input.
- Extract key fields with an LLM step.
- Validate totals and required fields.
- Route based on confidence or validation result.
- Send final output to a tool or downstream system.
Why This Matters
Breaking an Action Flow into steps helps you:
- keep logic readable,
- test smaller units,
- troubleshoot failures quickly,
- and evolve Action Flows safely over time.
It also makes ownership easier: teams can update one part of an Action Flow without rewriting everything.
Exporting and Importing Actions
You can move an Action between tenants — for example from a UAT tenant to Production — or back it up by exporting it to JSON.
- Export: open the Action and select Export in the header. The Export Action dialog shows the full configuration (trigger, every step, prompts, model references, input and tool assignments, switch branches, and any bundled Skills) as JSON. Select Copy to Clipboard.
- Export a stored version: open the Action's Version History and select the Export icon on any version row. The dialog shows that version exactly as it was saved, in the same format as a regular export. This is a safety net: if a rollback cannot be applied, import the exported version as a new Action instead.
- Import: on the Actions list, select Import, paste the JSON, and select Import New Action. Studio validates the Action first. When models, Apps, Tools, Inputs, or the trigger cannot be matched by name in the target tenant, an import wizard lets you map them before the Action is created.
Exports reference Apps, Tools, Inputs, and models by name, not by internal ID, which makes them portable. Credentials and secrets are never exported — reconnect those in the target tenant. Imported Actions start disabled so you can verify them before they run.
When the Action uses your own Apps (for example OpenAPI, Azure Storage, or Microsoft Exchange Apps), the export dialog lists them under Include Apps so they can be created in the target tenant. Dooap Apps are never listed or exported: they already exist on Dooap-based tenants and are managed outside Studio, so the imported Action uses the target tenant's existing Dooap App (matched by name, or mapped in the import wizard).
The Company & Vendor Filters of an Action with a Dooap trigger are matched to the target environment's Dooap during import: companies by company code and vendors by account number, because Dooap's internal company and vendor IDs differ between environments. A company or vendor that cannot be found there is reported in a warning after the import, and the filter keeps matching it by its company code or vendor account number.
Two gateway bindings travel with an Action as well:
- API Endpoints: when the Action uses the API Request trigger, the export bundles the API Endpoints attached to it (name, slug, method, request/query/response schemas, timeout, and authentication mode — never the secret). On import, endpoints are matched by slug, the way Tools and Inputs are matched by name. A new slug is created in Gateways > API Endpoints and attached to the new Action. An existing endpoint with the same slug is reused and re-attached to the imported Action; the wizard shows which settings differ (for example the request or response schema) and lets you update the endpoint from the import, or create a new endpoint with a numeric suffix instead. This is what makes re-importing a newer version of an Action into the same tenant keep its public URL. Secret-based endpoints get a new secret, shown once, when they are created or switched to a secret-based mode.
- Mailboxes: an Action with the Email Received trigger stores which Gateway Mailboxes it listens to. Mailbox ids are specific to a tenant, so the import wizard shows the target tenant's mailboxes and lets you pick the ones the Action should listen to. Without a selection the Action receives email from every mailbox in the tenant.
For a complete walkthrough, see Promoting from UAT to Production.
Copying a Single Step
You can also move just one step — for example a carefully tuned OCR or Agent step — into another Action without exporting the whole Action:
- Copy: select the step and choose Copy in the step editor header. Studio copies the step as JSON to your clipboard, including its prompts, configuration, input and tool assignments, and — for Switch and Loop Over steps — all nested child steps.
- Paste: in the target Action, select + where the step should go, then choose Paste step from JSON in the Select Step Type dialog and paste the copied JSON. The step is inserted at that position — this also works inside Switch cases and Loop Over bodies.
Like full Action exports, copied steps reference Tools, Inputs, and models by name, so a step can be pasted in another tenant or environment. Anything that cannot be matched by name is skipped and reported in a warning after the paste, and if the target Action already has a step with the same name, the pasted step is renamed with a "(copy)" suffix.
Editing a Step as JSON
This is an advanced option for users who are comfortable editing raw configuration. To open it, select the code icon (JSON view (advanced)) in the small icon toggle next to Copy in the step editor header; the layout icon next to it (Form view) takes you back. The JSON view replaces the forms (name, description, Inputs, Step Configuration, and Tools) with one JSON editor that shows the whole step:
stepType(read-only),name, anddescriptionaiModelIdandpromptfor steps that use them (Agent steps; OCR steps have a model only)config: the step type's settings, shown as a JSON objectinputAssignmentsandtoolAssignments, including their configuration
Unlike a copied step, the JSON view uses the ids of models, Inputs, Tools, Apps, and Actions, because it edits the step in place. The editor shows the name next to each id it recognizes, and completion offers the ids available in the tenant.
Changes in the JSON view work like changes in the forms: select Save Step (or press Ctrl+S) to save them, and the usual checks run before and during the save. Every save is recorded in the audit log as usual. While the JSON is not valid (for example a syntax error, an unknown property, an id that does not exist, or a changed stepType), the problems are listed under the editor, and saving, partial runs, and the enabled toggle are blocked until you fix them. For Switch steps, changing a case value in place renames the case, and its steps move with it, just as in the form.
Every step opens in the Form view. The JSON view stays open while you work on the same step, and opening another step or Action switches back to the Form view. Read-Only members can open the JSON view but not change it.
Files move through an Action Flow in a few different ways, and each path has its own size limit:
- Manual run uploads: 100 MB total per run. When you override runtime-loaded inputs in the Run Action Manually dialog, all uploaded files together may total up to 100 MB. The dialog checks the size before anything is sent and shows per-file upload progress while large files transfer, so you never wait on a run that was going to be rejected.
- Human Task files: 25 MB per file. The limit applies both to files an Action attaches when it creates a Human Task and to files a user uploads on the task page.
- Evaluation test cases: 10 MB per file. Test datasets are meant for representative samples, so they use a smaller cap.
- Runtime-loaded inputs (for example an OpenAPI input that downloads a document during the run) are not limited by Studio itself. The service that consumes the file sets the practical ceiling — for example, the Azure Content Understanding OCR model accepts documents up to 200 MB and 300 pages.
If an upload exceeds a limit, Studio tells you which file is too large before the run starts, so you can remove or replace it.
Good Practice
- Keep each step focused on one responsibility.
- Name steps clearly so run logs are easy to read.
- Reuse tools and input types instead of duplicating logic.
- Prefer explicit outputs over ambiguous free-form text when possible.
- Add branching only when there is a clear business rule behind it.
Common Pitfalls
- Creating very large steps that do too many things.
- Depending on implicit assumptions between steps.
- Skipping run review after step changes.
Small, clear steps are easier to trust, debug, and maintain.
Running part of an Action Flow
Select a Step in the editor to test a smaller part of your Action Flow:
- Run previous steps executes the steps before the selected Step, stopping before it.
- Run this step executes only the selected Step. Press N as the keyboard shortcut when you are not typing in an input.
A context run is an earlier Run of the same Action. Its input parameters, files, and outputs from preceding Steps provide context for a single-step test. Choose a previous Run in Studio to use it as context. If the Action has never run, the Step starts with empty inputs and no earlier outputs; Studio shows a warning. An incomplete context Run may also lack outputs that your Step needs.
While the tested Step stays selected, the Action Flow diagram shows the partial Run's progress: executed Steps are marked completed or failed, and Steps outside the Run are shown as skipped. Selecting another Step, or deselecting the Step, returns the diagram to its normal editing view. Toggling the Step's enabled state does the same, so the diagram shows whether the Step is enabled or disabled; the result card stays in the step panel.
The result card's Context Files shows files available to the test. Use the Previous Run tabs to inspect earlier results. Reused Steps are marked Reused; their outputs were copied from the context Run, so those Steps did not execute again.
Partial runs never trigger error handling Actions. They are intended for debugging: after the Step works, run the full Action to verify the complete flow.