Skip to main content
Browse all guides
All guides

Inputs and Tools

Inputs and tools make Actions useful in real business flows.

Together, they define what data an Action can receive and what external capabilities it can use.

Inputs

Inputs are data provided when an Action runs. These can come from API calls or other external sources.

Examples:

  • files,
  • invoice details,
  • invoice image,
  • metadata values,
  • user-provided JSON.

Define input types carefully so Action Flows can validate required data before a run.

Input Design Principles

  • Keep input names descriptive and stable.
  • Use explicit required/optional semantics.
  • Prefer predictable structures over free-form payloads.
  • Test with realistic sample data, not idealized examples.

Well-defined inputs reduce runtime errors and make Actions easier to reuse.

Tools

Tools let steps call external capabilities, such as APIs or custom logic.

Use tools when an Action Flow needs information or operations outside the model itself.

Typical tool scenarios include:

  • looking up reference data,
  • sending or updating records in external systems,
  • calling internal APIs,
  • and enriching step outputs with trusted system data.

Runtime Files and File References

Every file that enters an Action run becomes a runtime file in the run context: files uploaded to a manual run or sent with the trigger, email attachments, files uploaded through a Human Task, files fetched by inputs such as Read_Context_File, Read_Data_File or Download_Sftp_File, files downloaded by API inputs and tools (see Files downloaded from APIs), and files produced by tools such as Extract_PDF_Pages, Extract_Embedded_Files, Render_Document_To_PDF or Convert_To_PDF. The text or JSON result of every other input, such as a Skill loaded with Load_Skill or a Dooap lookup, is kept as a small JSON runtime file as well. Runtime files stay in the run for its whole duration, so any later step can use them without downloading or re-uploading anything.

Each runtime file carries metadata that you can both read and select by:

FieldMeaning
fileIdUnique id of the file within the run.
fileNameOriginal or generated file name.
contentTypeMIME type, for example application/pdf.
sizeBytesFile size.
inputTypeNameName of the input that loaded the file, for example Read_Gateway_Email_Attachment.
sourceStepNameStep that loaded or produced the file.
sourceToolNameTool that produced the file, for example Extract_PDF_Pages.

You can see these values in two places. Each step's input includes a files list with the metadata of the files visible to that step. The list is also available as {{inputs.files...}}:

  • in templates in Agent prompts, Tool Call parameters and Filter values, for example {{inputs.files.[].fileName || sep=", "}},
  • in Filter, Switch and Loop Over field paths, for example inputs.files.0.fileName. Inputs and tools that add a file to the run return the same metadata in their output under file for reading, together with a ready-to-use reference under runtimeFile for passing the file on.

Files downloaded from APIs

When an API input or tool (an OpenAPI App or Dooap operation) returns a file, the file is added to the run as a runtime file instead of being placed in the step input as text. This happens for PDFs, images, audio and video, Word, Excel and PowerPoint documents, OpenDocument files, archives such as ZIP, and application/octet-stream. JSON, XML, CSV, HTML and plain-text responses are still returned as data.

The file name comes from the response's Content-Disposition header. If the API sends none, the last part of the request path is used when it looks like a file name (for example invoice.xlsx from /attachments/invoice.xlsx), and otherwise a name such as response_20261023_101500.xlsx is generated from the content type. A tool that downloads a file returns fileName, contentType, sizeBytes, file and runtimeFile, so an agent or a later step can pass the file on, for example to Read_Context_File, Read_Excel_Sheet or Convert_To_PDF. The model does not see the file's content through the download alone; see Files in Agent Steps for how an agent reads a file it downloaded. An error response from a tool never becomes a file; its body is returned as text in the error message.

Where file references are accepted

Any parameter that expects a file takes a file reference instead of file content. The most common places are:

  • the file parameter of the Read_Context_File input,
  • the runtimeFile parameter of Read_Excel_Sheet and of the built-in file tools, including Extract_PDF_Pages, Extract_Embedded_Files, Convert_To_PDF, Convert_Excel_To_CSV, Write_Blob, Write_File_Share_File, Upload_Sftp_File and the Data Files Write_File tool. These also accept the parameter under the aliases contentFile and file,
  • the htmlRuntimeFile and markdownRuntimeFile parameters of Render_Document_To_PDF,
  • entries in the attachments array of Send_Gateway_Email, optionally with a fileName or contentType override for the outgoing attachment,
  • file (binary) form fields of your own OpenAPI tools that post multipart/form-data.

Reference forms

All forms below resolve to a single file. When several files match, the most recently added one wins.

latest picks the newest file in the run, whatever its type. It is the easiest form and the right one when the run holds exactly one relevant file. It is also the trap to watch for: the results of every input that returns text or JSON (a Skill loaded with Load_Skill, a Dooap lookup), files produced by tools and other intermediate files are runtime files too, so in a longer Action Flow the newest file is often not the PDF you meant. After an Agent step that loads a Skill, for example, latest is the Skill text rather than the invoice PDF read two steps earlier. A tool that receives the wrong file typically fails on the receiving end with a confusing error, for example an HTTP 415 from an API that expected a PDF.

A file id points to one exact file. Use runtimeFile:<id> or file:<id>; a bare id works as well. The id comes from the files list of the step input or from the file.id value in the output of the input or tool that created the file. This is the form to prefer inside Agent steps: the agent sees the ids of the files available to it, so ask it in the prompt to pass the id of the specific file rather than latest whenever more than one file is present.

A selector object narrows the choice with metadata filters. Any combination of the fields above can be used, all given filters must match, comparisons ignore case, and the newest matching file is returned:

{ "fileId": "latest", "contentType": "application/pdf" }

selects the newest PDF regardless of what else has been added since, and

{ "sourceToolName": "Extract_PDF_Pages" }

selects the file the Extract_PDF_Pages tool produced. Other useful filters are fileName, inputTypeName (the newest file loaded by a given input, for example { "inputTypeName": "Read_Data_File" }) and sourceStepName. A selector object may also carry runtimeFile or fileId with an exact id. An object that contains only these selector fields is always treated as a file reference, while an object with any other fields is treated as literal content, so a payload that happens to have a fileName property is never mistaken for a reference.

The runtimeFile object of an earlier output is the most robust form when one step produces a file and a later step consumes it. Inputs and tools that add a file return a runtimeFile object that already contains the file id, so passing it through a template resolves to exactly that file. A Tool Call step exposes the tool result under data, so a later tool parameter can reference the file produced by an earlier Tool Call step named "Extract invoice pages" as:

{ "runtimeFile": "{{steps.Extract invoice pages.data.runtimeFile}}" }

The same works for the runtimeFile object returned by download tools such as Download_Sftp_File and Get_Gateway_Email_Attachment. Pass the runtimeFile object, not the file metadata object: file is for reading names and sizes and is not accepted as a reference.

Behavior notes

  • Matching is case-insensitive for ids, names, content types and step or tool names.
  • A reference that does not match any file fails the step or tool with an error that lists the files currently in the run, so an incorrect reference never silently sends the literal reference text as file content.
  • In a Loop Over, the files loaded by a step's own inputs are refreshed on every round, so latest and per-input references follow the current round's file rather than the first round's.
  • The OCR step does not take a reference. It reads the file loaded by its own inputs first, then files tagged with one of its input types, and finally untagged run files such as manual uploads. Load the intended document through an input such as Read_Context_File when the run contains more than one candidate.

Practical guidance

  • Use latest for short flows with a single document.
  • Add a contentType or sourceToolName filter as soon as a flow produces more than one file, or pass the producing step's runtimeFile object through a template.
  • In Agent steps, instruct the agent to reference files by id and to inspect the files list before choosing.
  • When a downstream API rejects a file with an unexpected format error, check which runtime file the reference resolved to before debugging the API.

Built-in File Tools

Studio ships standard tools every tenant can use without configuration. Some of them work on the run's context files:

  • Extract_PDF_Pages creates a smaller PDF from selected pages of a PDF already in the run context. Page selection uses the same syntax as the OCR step — 1-10, 1,2,3, or 1,4-8 — and the last keyword selects the document's last page wherever a page number fits, so 1-3,last extracts the first three pages together with the final page (where totals often appear) without scanning everything in between. Pages beyond the end of the document are simply skipped, so extracting 1-10 from a 7-page document yields a 7-page PDF without an error. A common pattern: a Tool Call step fetches a large PDF and extracts just the pages you need, and the following OCR step reads the trimmed file through a Read_Context_File input with file latest or a selector such as { "sourceToolName": "Extract_PDF_Pages" } (see Runtime Files and File References). This keeps large documents fast and inexpensive to process.
  • Render_Document_To_PDF renders HTML or Markdown produced by earlier steps into a PDF file.
  • Convert_To_PDF turns a file already in the run context into a PDF file, whatever its type. It detects the file type from the extension, the content type or the file's own signature and picks the conversion for you, so it works for email attachments and uploads whose type you do not know in advance. A file that is already a PDF is passed through unchanged. Word documents (.docx) and Excel workbooks (.xlsx) are converted with full fidelity, including headers, footers, images and the workbook's own print setup, in environments with the LibreOffice conversion service; elsewhere Studio's built-in layout engine takes over, where headings, text formatting, lists, tables, embedded PNG, JPEG and BMP images and page breaks come through while headers, footers, charts, other image formats and complex floating layout are simplified or left out, and workbooks render as one table per worksheet (the sheets, showSheetNames, maxRowsPerSheet and culture parameters control that rendering). HTML, Markdown and plain-text files are rendered like Render_Document_To_PDF, and PNG or JPEG images are placed on a page scaled to fit. Every other format that LibreOffice can open, such as PowerPoint, legacy .doc/.xls, OpenDocument, RTF, CSV, EPUB, Visio, TIFF or SVG, is converted through the LibreOffice conversion service; where the service is not available the tool explains that instead of producing a broken PDF. Files it cannot convert at all, such as ZIP archives or JSON, are rejected with a clear message; take the files out of a ZIP archive with Extract_Embedded_Files first. The result reports the detected sourceFormat, the conversion that was applied and the engine used (the engine parameter lets you force one), and the resulting PDF can be written to storage, attached to a Send_Gateway_Email, or read by the next step through a Read_Context_File input with file latest or a { "contentType": "application/pdf" } selector.
  • Extract_Embedded_Files takes the files out of a PDF, an XML e-invoice or a ZIP archive and adds them to the run as runtime files. See E-invoices and other files with embedded files.
  • Read_Context_File returns the content of a file already in the run context to the model: the rows of an Excel sheet, the text of a Word document, the Markdown of a PDF with a text layer, the visible text of an HTML page, or the text of CSV, JSON, XML, Markdown and plain-text files. It is the tool counterpart of the Read_Context_File input and the way an Agent Step reads a file it downloaded with one of its own tools. See Files in Agent Steps.
  • Convert_Excel_To_CSV, Read_Excel_Sheet, and Write_Excel_Sheet move data between Excel workbooks and Action Flow steps.

E-invoices and other files with embedded files

Many European e-invoices travel as one file that carries another:

  • A ZUGFeRD / Factur-X PDF is an ordinary, readable invoice PDF with the structured invoice XML (factur-x.xml, zugferd-invoice.xml or xrechnung.xml) embedded inside it, often together with supporting documents such as a timesheet.
  • An XRechnung or Peppol XML invoice is the structured invoice itself, and it often carries the readable invoice PDF and other documents as base64 text inside the XML.

Extract_Embedded_Files opens such a file and adds the files inside it to the run. It recognises the source from its content rather than its name, so it works the same for email attachments, Blob and SFTP downloads, manual-run uploads and API inputs. It also extracts the files of a ZIP archive.

The result names the parts of an e-invoice the same way whichever kind arrived, so the steps after it do not need to know:

FieldZUGFeRD / Factur-X PDFXRechnung / Peppol XML
invoiceDatathe embedded invoice XMLthe XML itself
invoiceImagethe PDF itselfthe embedded invoice PDF
attachmentsthe other embedded filesthe other embedded files

Each part has fileName, contentType, sizeBytes and a runtimeFile reference. isSourceFile tells whether the part is the file you passed in, and selection tells how it was chosen. In a PDF, the invoice XML is identified by the PDF's own Factur-X markers. An XML invoice has no marker for "this attachment is the invoice image", so the tool picks the PDF whose name, description or document id contains the invoice number, and otherwise the first PDF (selection is then invoiceNumber or firstPdf).

The result also contains:

  • isEInvoice: true when invoice data was found. A file without embedded files, or a file of another type, is not an error: isEInvoice is false and the parts are empty, so a Filter or Switch step can send e-invoices to a mapping branch and other documents to OCR.
  • eInvoice: the standard (XRechnung, Factur-X/ZUGFeRD, Peppol BIS Billing or EN 16931), the syntax (UBL or CII), invoiceNumber, typeCode (380 for an invoice, 381 for a credit note), customizationId and, for Factur-X PDFs, the conformanceLevel profile.
  • invoiceDataWithoutAttachments: when the invoice XML carries base64 attachments, a copy of it in which the encoded content is replaced by a short comment that names the extracted file. An XRechnung XML can be almost entirely base64, so give this copy, not the original, to an Agent step that maps the invoice, and keep the original for archiving or as an attachment.
  • files: every extracted file with its origin, nestedIn, relationship (in PDFs, for example Alternative for the invoice XML and Supplement for supporting documents), description and, for ZIP entries, path.
  • skipped and warnings: files that were found but not extracted, for example because they are too large, password-protected or not valid, and the reason.

Set maxDepth to 2 or 3 to also open the files found inside, for example a ZUGFeRD PDF inside a ZIP archive. The e-invoice parts always describe the file you passed in.

Because the extracted files are added to the run, latest points at the last extracted file afterwards. Pass the returned references to later steps instead, for example:

{ "runtimeFile": "{{steps.Extract embedded files.data.invoiceImage.runtimeFile}}" }

The tool treats every file as untrusted. It never loads resources an XML file refers to, rejects XML that contains a DTD, and stops at 100 files and 100 MB per call and 25 MB per file. Folders and operating-system files (__MACOSX, .DS_Store, Thumbs.db) in ZIP archives are ignored.

Mapping Inputs to Tools

Most production Action Flows map input values into tool requests. Keep this mapping explicit.

Example pattern:

  1. Validate input values in early steps.
  2. Transform values into the expected API format.
  3. Call a tool with only required fields.
  4. Handle tool failures with clear fallback or error behavior.

Output Filters (JSONPath-like)

Input and Tool responses are often larger than what an LLM step actually needs.

To reduce prompt size and noise, each Step Input assignment and Step Tool assignment supports an optional outputFilter field.

When set, the filter is applied to JSON responses before the data is added to step context/output.

In Action Studio, outputFilter is shown as a separate field, while being stored as part of the step assignment configuration JSON.

Why use output filters

  • Reduce token usage by keeping only relevant fields.
  • Improve model focus by removing unrelated response data.
  • Make step outputs easier to inspect in logs.

Supported syntax

The filter uses a JSONPath-like subset (not full JSONPath):

  • $.field
  • $.field.nested
  • $.arrayField.0
  • $.arrayField[*]
  • $.arrayField[*].{fieldA,fieldB} (projection extension)
  • field.nested (without $)
  • $ (keep full JSON as-is)
  • $.a.x, $.b.y (several expressions, see below)

Examples:

  • $.data.items -> returns the items node under data
  • $.data.items.0.id -> returns the first item id
  • $.phoneNumbers[*].{number,country} -> returns each phone number with only number and country
  • result.total -> returns total under result

Projection example:

{
  "userId": "user789",
  "name": "Bob K.",
  "phoneNumbers": [
    { "type": "home", "number": "555-0201", "country": "+358" },
    { "type": "mobile", "number": "555-0202", "country": "+358" }
  ]
}

Filter:

$.phoneNumbers[*].{number,country}

Result:

[
  { "number": "555-0201", "country": "+358" },
  { "number": "555-0202", "country": "+358" }
]

Another projection example:

Multiple expressions

One expression can only keep values under a single parent. To keep fields from different branches of the response, list several expressions separated by commas or spaces:

$.invoice.num, $.audit_log.created

With several expressions the result is the original JSON pruned down to the selected values, so each value keeps its place in the structure:

{
  "invoice": { "num": "123", "date": "2026-09-09", "sum": 123.12 },
  "audit_log": { "created": "2026-09-09T23:23:23Z" }
}

becomes

{
  "invoice": { "num": "123" },
  "audit_log": { "created": "2026-09-09T23:23:23Z" }
}

Notes:

  • Projections can be combined with other expressions: $.items[*].{id,name}, $.total. Commas inside {...} are part of the projection, not separators.
  • When one expression keeps a whole value (for example $.invoice) and another keeps part of it, the whole value wins.
  • Partially selected arrays keep only the selected elements, in their original order.
  • Expressions that match nothing are skipped. If none match, the result is null.
  • A single expression still returns the selected value itself (for example $.invoice.num returns "123"), which keeps existing filters working unchanged.

Output Filter Wizard

Instead of typing the expression, use the Wizard button next to the Output Filter field. It shows a sample of the response (from a previous run, the example output, or JSON you paste) as a tree of checkboxes:

  • Tick or untick fields to keep or drop them. Everything is kept until you untick something.
  • Use Open to pick fields inside an object or list. Fields inside a list are projected with [*].
  • Selections are remembered while you navigate between branches. A parent with only some of its fields kept is shown as partially selected.
  • The preview shows the filter expression and the resulting JSON live. Several branches produce several expressions, combined with commas.

Behavior notes

  • Filtering is applied only to JSON-like response payloads.
  • Binary responses (for example PDFs/images) are not filtered.
  • If outputFilter is empty, full response data is kept.
  • If path does not match, the filtered result is null.
  • If response is plain text/non-JSON, filtering is skipped and original data is kept.
  • Date-like strings are kept exactly as they appear in the response.

Practical guidance

  • Start with the smallest field that still gives the next step enough context.
  • Prefer stable paths that do not depend on optional branches.
  • Avoid filtering out fields needed by downstream prompt templates or tools.
  • Validate filters using realistic response examples before production rollout.

Best Practices

  • Keep input contracts stable and descriptive.
  • Mark required inputs clearly.
  • Use least-privilege credentials for tool connections.
  • Handle tool errors gracefully and expose useful logs.

Common Pitfalls

  • Passing large raw payloads between many steps without normalization.
  • Making tool calls with ambiguous or unvalidated identifiers.
  • Treating model output as trusted input for external writes without checks.