Advanced Techniques
Patterns for keeping larger workflows fast, cheap, and debuggable
Table of Contents
Performance Optimization
Nodes run one after another, so the total run time and token cost of an agent is the sum of its LLM calls. Most optimization comes down to making fewer, smaller calls.
Token management
- Match the model to the step. Use a lightweight model (for example GPT-5.6 Luna) for extraction and formatting, and reserve flagship models (GPT-6 Astra, Claude Opus 5) for the reasoning-heavy step. The First Workflow tutorial does exactly this.
- Set Max Output Tokens on every LLM node. Unbounded outputs are the most common source of surprise cost.
- Save once, reuse many times. Store an LLM result in a Save Variable node and reference it with
{{variable}}downstream instead of asking a second node to re-derive it. - Attach only what the node needs. Each attached file is sent with every call to that node. Extract the relevant section into a variable early and pass the variable, not the file, to later nodes.
- Keep prompt templates terse. Instructions repeated in every node add up. Put shared guidance in the agent's persona once.
Execution time
- There is no parallel execution. Order nodes so that cheap validation (If/Else) happens before expensive LLM calls, and let early branches end in a Return Response node.
- Use Loop nodes deliberately. A loop over 500 rows is 500 LLM calls. Aggregate rows into a single prompt where the task allows it, or narrow the array with a Transform Variables node first.
- Use Decision Tree nodes for routing, not analysis. They make a short classification call; keep the heavy prompt in the branch that actually needs it.
Complex Workflow Patterns
The twelve node types combine into a small number of recurring shapes. Each pattern below is used by one of the worked examples on the Use Cases & Examples page.
Staged pipeline
LLM → Save Variable → LLM → Save Variable → Return Response. Each stage reads the variables written by the stages before it. This is the shape of the PowerPoint Generator and the RFI/RFP tutorial, and it is the easiest pattern to debug because every intermediate result is visible in the logs.
Classify and route
A Decision Tree node reads the input and sends it down one of several branches, each ending in its own Return Response. Always define a default branch so unexpected inputs produce a useful answer instead of a failed run. The Proposal Evaluation example uses this for its GO / MAYBE / NO-GO decision.
Guard, then act
An If/Else node checks a variable (is it empty, does it contain a keyword) before the workflow spends tokens on it. The false branch returns a short message asking for the missing input.
Iterate over records
Read File → Loop → LLM inside the loop → Transform Variables to assemble the results → Return Response. The CSV Data Query example processes a spreadsheet this way. Keep the per-row prompt small; see the performance notes above.
Build knowledge as you go
Train File or Train Array nodes ingest content into a dataset during the run, and a later LLM node queries that dataset. Use this when an agent must answer questions about documents it was just given rather than about a pre-built dataset.
Enrich with an external API
API Call → Transform Variables (extract_json) → LLM → Return Response. The API Call node fetches JSON from an approved HTTPS service, the transform pulls out the two or three fields that matter, and the LLM reasons only over those fields plus the status code. Keep credentials in the node's headers, never in the prompt.
Reusable agents behind an API
Once a workflow is stable, save it as an agent and call it from code or from another system with /server/execute-agent. Multi-file and multi-step orchestration from outside Ask Sage is covered in API & Integration.
Debugging Strategies
Every run produces a per-node execution log with status, timing, inputs, and outputs. Debugging is mostly a matter of reading it in the right order.
- Find the first failed node. Later nodes fail because an upstream variable is missing; fixing the first failure usually clears the rest. The Activity log lists nodes in execution order.
- Check variable names. The most common error is a template referencing
{{summary}}when the Save Variable node wrotesummary_text. Names are case-sensitive. - Check file variables. The key you type in an LLM node's Attached Files field must match the agent's file variable exactly (the agent key
source_data_1is referenced asinput.source_data_1). - Reproduce with a small input. A two-row CSV or a one-page document runs in seconds and makes log output readable.
- Pin temperature to 0 while debugging so the same input gives the same output between runs. Raise it again once the structure works.
- Export the logs. Use the export icons in the execution log view to save a run as a Word document when you need to share it or compare two runs side by side.