Agentflow V2

Agentflow V2 is the primary workflow builder in Lyntaris.

• List page: /agents
• Builder route: /v2/agentcanvas

Quick Start: /agents -> /v2/agentcanvas

1. Open Agents (/agents).
2. Keep the view on Turn Agents (V2).
3. Click Add New.
4. You will be redirected to /v2/agentcanvas with a default Start node.
5. Build your flow, save, then run it from chat/API.

Add Nodes palette (V2)

In /v2/agentcanvas, the Add Nodes panel shows:

• Agent Flows – Start, Agent, Condition, Condition Agent, Iteration, Loop, Execute Flow, Human Input, Direct Reply, Tool, Retriever, HTTP, Custom Function, Wait, Sticky Note, etc.
• Document Loaders (allowlisted) – only these nodes appear in the palette:
  • Playwright Web Scraper (playwrightWebScraper)
  • Puppeteer Web Scraper (puppeteerWebScraper)
  • Spider (spiderDocumentLoaders)
  • GitBook (gitbook)
  • FireCrawl (fireCrawl)
  • Figma (figma)
  • Airtable (airtable)
  • SearchApi For Web Search (searchApi)
• Tools (allowlisted) – SearchApi (searchAPI).

Other categories (e.g. full Tools list, Memory, Chains) are not shown in V2. You can still attach any tool to the Agent node via its Tools dropdown; the allowlist only controls which nodes are draggable onto the canvas.

How V2 Execution Works

At runtime, Agentflow V2 executes as a directed graph with a node queue:

1. Execution starts from Start.
2. Node inputs are resolved from variables, flow state, and previous node outputs.
3. Nodes run when dependencies are satisfied.
4. Branch nodes choose route(s) (Condition, Condition Agent, Human Input).
5. Execution ends with one of these statuses:
   • FINISHED
   • STOPPED (waiting for human decision)
   • ERROR
   • TERMINATED

Notes from current runtime behavior:

• Only one Start node is allowed.
• Loop has a max loop count and optional fallback message.
• Iteration executes child subflow recursively for each array item.

Understanding Flow State

Flow state is shared runtime state ($flow.state) across nodes.

Use it like this:

1. Initialize keys in Start (Flow State input).
2. Update keys in nodes that support Update Flow State.
3. Read values anywhere with {{ $flow.state.yourKey }}.

Additional start behavior:

• Persist State (startPersistState): carry state across runs in same session.
• Ephemeral Memory (startEphemeralMemory): start without past chat history.

Common variable references:

• {{ question }}
• {{ $form.fieldName }}
• {{ $flow.state.key }}
• {{ $vars.globalKey }}
• {{ $iteration }} / {{ $iteration.someField }}
• {{ nodeId.output.content }}
• {{ loop_count }}
• {{ current_date_time }}

Runtime variables (Chat Context)

These variables are available in prompts and in the Condition node (Value 1 / Value 2). They are resolved when the node runs.

Condition node: In Value 1 (or Value 2) you pass one variable or literal, e.g. {{ chat_history }}. You do not write expressions like {{ chat_history }} + Not Empty. To check “has history”, set Value 1 = {{ chat_history }}, Operation = Not Empty, and leave Value 2 unused.

Human In The Loop (HITL)

V2 supports two HITL patterns:

1. Human Input node
   • Pauses flow and emits Proceed / Reject action.
   • Can use fixed description or model-generated description.
2. Agent tool approval
   • In Agent -> Tools, each tool can be marked Require Human Input.
   • Agent pauses before sensitive tool execution.

To resume a stopped flow, send humanInput in prediction request:

{
  "humanInput": {
    "type": "proceed",
    "feedback": "Approved"
  }
}

type can be proceed or reject.

Execute Flow (Call Another Flow)

Use Execute Flow to call another V2 flow.

Key behavior:

• Select target flow (AGENTFLOW type).
• Pass input as question or form payload (auto-detected from target Start config).
• Optional API credential for protected/external base URL.
• Cannot call the same flow ID (self-call is blocked).

Iteration and Loop

Iteration

• Iteration expects an array input.
• Nodes inside the iteration container run once per item.
• Use {{ $iteration }} or {{ $iteration.field }} inside child nodes.

Current UI/runtime constraints:

• Nested Iteration is not supported.
• Human Input inside Iteration is not supported.

Loop

• Loop jumps back to a previous node.
• Configure:
  • Loop Back To
  • Max Loop Count
  • optional Fallback Message
• Use {{ loop_count }} in prompts/conditions for loop-aware logic.

Guardrails and Policies in V2

V2 guardrails are implemented by composition of nodes and settings:

1. Prompt policy in Agent/LLM system instructions.
2. Tool allowlist via explicit tool selection in Agent or deterministic Tool node.
3. Approval gates via Require Human Input or Human Input node.
4. Deterministic routing with Condition and Condition Agent.
5. Moderation nodes (where needed) before risky actions.
6. Execution safety with Loop max count, Wait, and explicit fallback branches.

Agentflow V2 Node Reference

1. Start Node

Purpose: entry point and initial runtime setup.

Main config:

• Input Type: chatInput or formInput
• form metadata (Form Title, Form Description, Form Input Types)
• Ephemeral Memory
• Flow State
• Persist State

2. LLM Node

Purpose: direct model call (no tool planning loop).

Main config:

• model + messages
• optional thread memory
• optional structured JSON output schema
• return response role
• update flow state

3. Agent Node

Purpose: model-driven reasoning with tool and knowledge use.

Main config:

• model + messages
• built-in provider tools (OpenAI/Gemini/Anthropic where applicable)
• tool list with optional Require Human Input
• knowledge from document stores or vector embeddings
• optional thread memory
• update flow state

4. Tool Node

Purpose: deterministic execution of one selected tool.

Main config:

• tool selection
• mapped input arguments
• update flow state

5. Retriever Node

Purpose: retrieve context from document/vector stores.

Main config:

• document stores or custom vector store + embeddings mode
• query text
• output format (text or textWithMetadata)
• update flow state

6. HTTP Node

Purpose: call external HTTP APIs.

Main config:

• method, URL
• headers and query params
• body type (json, raw, formData, xWwwFormUrlencoded)
• response type (json, text, arraybuffer, base64)
• optional HTTP credential

7. Condition Node

Purpose: deterministic branching by rules.

Main config:

• Type: string, number, or boolean (how Value 1 and Value 2 are compared).
• Value 1: One variable (e.g. {{ chat_history }}, {{ runtime_messages_length }}) or literal. No expressions or “calculations”; use Operation for the logic.
• Operation: e.g. equal, notEqual, contains, isEmpty, notEmpty, larger, smaller, etc.
• Value 2: Second operand (ignored for isEmpty / notEmpty).
• Outputs: one route per matched condition, plus an Else route if no condition matches.

Examples:

• First message vs follow-up (by chat history):
  
  Value 1 = {{ chat_history }}, Type = String, Operation = Not Empty, Value 2 = (empty).
  
  “Not Empty” → follow-up; add another row with Operation Is Empty for first message and connect the two outputs to different branches.

• By number of runtime messages (current run only):
  
  Value 1 = {{ runtime_messages_length }}, Type = Number, Operation = Equal, Value 2 = 0.
  
  Note: runtime_messages_length is the count of LLM/agent messages in this execution; it is 0 right after Start and does not count previous user questions in the session.

• By flow state:
  
  Value 1 = {{ $flow.state.next }}, Operation = Equal, Value 2 = SOFTWARE (see Supervisor and Workers tutorial).

8. Condition Agent Node

Purpose: model-based branching by scenario classification.

Main config:

• model
• instructions + input
• scenario list
• optional system prompt override

9. Iteration Node

Purpose: run child subflow for each item in array input.

Main config:

• Array Input (must resolve to array)

10. Loop Node

Purpose: jump back to a previous node for retry/controlled cycles.

Main config:

• target node
• max loop count
• optional fallback message
• update flow state

11. Human Input Node

Purpose: pause and wait for human decision (Proceed/Reject).

Main config:

• fixed or dynamic description
• dynamic model + prompt (optional)
• enable feedback

12. Direct Reply Node

Purpose: send a final reply immediately.

Main config:

• reply message (supports variables)

13. Execute Flow Node

Purpose: call another flow and continue with returned output.

Main config:

• selected flow
• input payload
• override config
• optional base URL/credential
• return role
• update flow state

14. Custom Function Node

Purpose: run custom JavaScript logic in flow context.

Main config:

• input variables
• JavaScript function body
• update flow state

15. Wait Node

Purpose: pause until duration elapses or specific date/time.

Main config:

• duration mode (milliseconds/seconds/minutes/hours/days)
• or continue-after mode (datetime or variable expression)

16. Sticky Note Node

Purpose: design-time annotation only (no runtime execution effect).