AI Agent Node: Prompts, Model Selection, Structured Output, and Confidence-Based Routing

What it is

The AI Agent node brings AI-powered intelligence directly into a workflow step. When a workflow instance reaches this node, the AI reads the data and files you specify, follows the instructions in your prompt, and produces a decision or extraction result. The workflow then continues along the path that matches the AI's output.

Common uses include:

• Classifying a submitted document (for example, detecting whether it is an invoice, a contract, or a purchase order).
• Extracting key fields from a document automatically (amounts, dates, names, approval codes).
• Making a first-pass approval recommendation based on rules described in plain language in the prompt.
• Answering a question about your organization's knowledge base mid-process.
• Routing to a human reviewer when the AI is not confident enough to decide on its own.

The node has three configuration tabs: Inputs (what data and files the AI reads), Model & Prompt & Skills (what the AI is told to do and how), and Outputs & Routing (how the result is structured and which path the workflow takes).

Why it's useful / Key benefits

• Handle large volumes of routine decisions automatically. Low-risk, clear-cut requests can be approved, classified, or processed by the AI without any human step — freeing staff for cases that genuinely need judgment.
• Extract structured data from unstructured documents instantly. Instead of manually reading a PDF to find an invoice total, the AI reads it and returns the field as a typed workflow variable available to every downstream step.
• Read your organization's own documents for answers. The AI can query your knowledge base of internal documents at runtime, so decisions are grounded in your actual policies and records — not generic training data.
• Trust but verify — route uncertain cases to humans. When the AI's confidence is below a threshold you set, the workflow automatically diverts to a human review step rather than acting on a shaky decision.
• Process scanned documents, photos, and complex layouts as well as digital text files.
• Reuse expertise across workflows. Skills — reusable instruction packs you write once — can be attached to any AI Agent node to apply consistent reasoning rules without re-typing the same guidance.
• Test the node before going live. A built-in test runner lets you supply sample variable values and see the AI's response immediately, without running a full workflow instance.

Before you start

• The AI Agent node is available to all users — no special role is required to add, configure, or save it. (Only the Python Script and DB Query nodes are restricted to administrators.)
• At least one AI model must be configured in your organization's AI authentication settings. If none is available, contact your administrator.
• For knowledge-base lookups, the relevant documents must already be processed and indexed in the Knowledge knowledge base.
• Open the workflow from the Workflow Management screen and click Edit.

How to use it — step by step

Step 1: Place the node on the canvas

1. In the visual designer, open the Logic tab in the left sidebar.

2. Drag the AI Agent node onto the canvas after the step that collects the data or files the AI will read.

3. Connect the preceding node's output to the AI Agent node's input.

4. Double-click the node (or click its gear icon) to open the AI Agent Node configuration dialog.

5. Fill in the Node Label and Node Description fields at the top — these appear on the canvas and help others understand what this AI step does.

Step 2: Configure Inputs (Tab 1)

The Inputs tab defines what data and files the AI receives.

Input Variables:

6. The variable tree lists all variables available from upstream nodes, grouped by the node that produced them. Each group can be expanded by clicking its header.

7. Tick the checkbox next to each variable the AI should receive. Selected variables appear as purple chips in the "selected" panel at the top of the section.

8. Use the Search variables field to filter the list when there are many variables.

9. Click Auto-add all to select every available variable at once. Use this when you want the AI to have full context.

10. To copy a variable token to paste into your prompt, hover over a variable row and click the copy icon, or click the chip in the selected panel.

Input Files:

11. Click Add File to attach a file the AI should read.

12. In the Add File panel:

    • Choose the Source: Workflow File (a file uploaded via a file picker in the workflow's form) or Documents (a document from the Documents document library).
    • If "Workflow File": select the file picker widget from the dropdown.
    • If "Documents": click Browse Documents documents… and search for the document by name.
    • Under How the AI reads this file, choose:
      • Direct Extract — instantly reads text from digital PDFs and plain text files. Fast, but does not handle scanned or image-based documents.
      • Full Pipeline — processes scanned documents, photos, and complex layouts. Slower but handles any document type.
    • If Full Pipeline, choose a Preset (your organization's configured processing profile) and a Processing Depth:
      • Automatic — the system detects whether the document needs full processing.
      • Standard — parse and chunk only; fastest.
      • Full — includes table summaries and entity extraction; slowest but most thorough.
    • Click Add File to confirm.

13. To reorder files, drag their rows using the grip handle on the left. The order determines how files are passed to the AI.

14. To edit a file's pipeline settings after adding it, click the slider icon on its row.

Step 3: Configure Model & Prompt & Skills (Tab 2)

Click the Model & Prompt & Skills tab.

Model Selection:

15. Choose Default Generator to use the organization's default AI model (recommended for most cases), or Choose Model to select a specific model from the dropdown.

Generation Settings:

16. Adjust the Temperature slider (0.00 to 1.00). Lower values (close to 0) produce more focused, consistent responses. Higher values produce more varied responses. For classification and extraction tasks, use a low value (0.1–0.3). For more open-ended generation, use 0.5–0.8.

17. Set Max Tokens: Auto uses the model's default limit. Choose Custom Value and enter a number to cap the response length.

18. Set the Language: Auto-detect (the AI responds in the language it receives), English, or Arabic.

Prompts:

19. In the System Prompt field, type the standing instructions that shape how the AI behaves throughout this step. This is where you describe the AI's role and rules:

    • Example: You are a document reviewer for a procurement team. Your job is to classify each document and extract the invoice total, vendor name, and invoice date.
    • Click the Copy button to copy the prompt to your clipboard.

20. In the User Prompt Template field, type the specific instruction for each workflow run, using {{variable_name}} tokens to insert dynamic data:

    • Example: Please analyze the attached document and return the classification and key fields. The document was submitted by {{submitter_name}} on {{submission_date}}.
    • The chips below the field (showing your selected input variables) can be clicked to append the corresponding {{variable_name}} token at the cursor position.

Advanced Settings:

21. Click Advanced Settings to expand the panel.

22. Search the internet is on by default. Leave it on to give the model permission to look up current public information when the task needs it; turn it off to keep the node limited to its workflow inputs, files, and configured tools. Enabling it does not force a search on every run.

23. Click a skill chip to toggle it on or off. Active skills inject their instruction packs into the AI's context, shaping how it writes and reasons. Click Manage Skills to create or edit skills in the Skill Manager.

24. Toggle Auto-discover relevant skills to let the AI pick the most applicable skills from your library automatically, based on context.

25. Toggle Allow AI to propose new skills to let the AI suggest creating a new instruction pack when it encounters a situation none of the existing skills covers.

Step 4: Configure Outputs & Routing (Tab 3)

Click the Outputs & Routing tab.

Output Mode:

25. Choose Structured Output (recommended) or Free-form text:
    • Structured Output: the AI returns a JSON object with named fields. Click Add Field to define each field — give it a Name, Type (string, number, boolean, or enum), a Description (used as a hint to the AI), and optionally mark it Required.
    • Free-form text: the AI returns a plain text response. Enter the name for the variable that will hold the text (for example, ai_response).

Routing:

26. Under Routes, you will see at least one route: needs_review (a permanent fallback route that cannot be removed). Add your own routes by clicking Add Route:

    • Enter a Route Name (this becomes the edge label on the canvas, for example approved, rejected, high_value).
    • Enter a Description explaining when this route should be taken.
    • Choose a Color for visual identification on the canvas.
    • Optionally enable Use confidence range to trigger this route only when the AI's confidence score falls within a percentage range (Min % and Max %).

27. Toggle Enable Documents smart tools if you want the AI to be able to look up file locations, folder contents, and document counts from the document library mid-response.

28. Toggle Request confidence score (0-1) from AI to have the AI report how confident it is in its answer. Enabling this unlocks confidence-based routing (each route's confidence range filter becomes active).

Test Node:

29. Click Test Node to open the test dialog. Enter sample values for each of your input variables, then click Run. The test output shows what the AI would produce — without running any real workflow instance and without executing knowledge-base queries.

Step 5: Save and wire the outputs

30. Click Save Configuration.

31. In the designer, connect the AI Agent node's named route output handles to the appropriate next steps. The needs_review route should connect to a human review task.

32. Click Save (or press Ctrl+S).

Options & settings explained

Inputs tab

Model & Prompt & Skills tab

Outputs & Routing tab

Tips & best practices

• Write clear, concrete System Prompts. Specify exactly what the AI should classify, extract, or decide — and list the possible outcomes (which become your route names). Ambiguous prompts produce unreliable routing.
• Match your route names to output values. If the AI is asked to classify a document as "Invoice", "Contract", or "Purchase Order", create routes with those exact names and use a structured output field of type enum with those three values.
• Always wire the needs_review route. The fallback route is the safety net. Connect it to a human review task so no instance is ever silently dropped.
• Use confidence-based routing for high-stakes decisions. Route high-confidence decisions automatically and send lower-confidence ones to a human. A typical split: route A (80%–100%), route B (60%–79%), needs_review (0%–59%).
• Keep prompts short and specific. A 3-paragraph prompt is usually more effective than a 10-paragraph one. Focus on the decision task, not background context.
• Use the Test Node before deploying. Enter realistic sample values and confirm the AI returns the expected structured output and selects the right route before running live instances.
• Attach Skills for consistency. If you have an organizational writing standard or a set of classification rules that apply across many workflows, encode them as a Skill and attach it here rather than repeating the text in each prompt.
• Use Auto-add all sparingly. Giving the AI every variable in the workflow is convenient, but a focused input set produces more reliable results. Select only what is relevant to the AI's task.

Frequently asked questions

Q: I do not see the AI Agent node in the sidebar. Why? The AI Agent node is available to all users in the node palette. If you do not see it, refresh the Flow Builder page and make sure you are working in a workflow you have permission to edit.

Q: What is the difference between Direct Extract and Full Pipeline? Direct Extract reads the text layer of a digital PDF instantly — very fast, but only works for PDFs and text files that have selectable text. Full Pipeline uses image recognition to read scanned documents, photos, tables, and complex layouts. Use Full Pipeline for any document that was physically scanned or photographed.

Q: Can the AI read documents from Documents and use our internal knowledge base at the same time? Yes. Add a specific Documents document as an Input File (for the document the AI reads for this instance), and separately enable knowledge-base queries via the RAG Query Mode in the Input Files section. The AI can draw on both sources in a single step.

Q: What happens if the AI returns a value not in my enum list? The AI is instructed to return only the values in your enum. If it does not comply, route matching uses the configured review behavior. Open the instance from All Instances and use its detail and operational records to diagnose the result.

Q: The test says "Test mode does not execute RAG." What does that mean? Knowledge-base queries (searching your documents) are not run during test mode. The test gives you the AI's response based on the prompt and sample variables only, without fetching real document content. The full knowledge-base lookup happens only in a live workflow instance.

Q: Can multiple AI Agent nodes exist in the same workflow? Yes. Each node is configured independently with its own inputs, prompt, and routing. You can chain them to build multi-step AI analysis pipelines within a single workflow.

Q: How do I know which route the AI chose for a live instance? Open All Instances, find the instance, and select it to open Workflow Detail View. Use the available status and operational records to confirm which route ran and inspect the AI step result.