Basic Patterns
Simple Agent Loop with Auto-Approve
The standard agent pattern: call LLM, execute tools, repeat while there’s work.whilecondition checks for non-empty tool_calls to continue looping- No approval step means tools execute automatically
Manual Approval Mode
Add an approval gate before tool execution.- Approval blocks until user responds or timeout
- Check
nodes.approval.status == 'approved'before proceeding
Plan Mode (Read-Only Tools)
Restrict agent to read-only tools for planning without modifications.- Use
tools_config.preloaded_toolsto choose which tools the model starts with tag:coding:planincludes read-only tools plus planning tools (create_plan, add_task, etc.)- Pair with a planning-specific system prompt
Conditional Logic
Branch Based on Exit Code
Route workflow based on command success/failure.runnodes exposeexit_code,stdout,stderr- Use conditions to branch on exit_code
Branch Based on Tool Calls Present
Check if LLM made tool calls to decide next step.- Always check both
!= nullandsize() > 0 - Every case needs a
condition;default:is where the edge goes when none matches
Loop While Condition Met
Retry while tests fail (up to iteration limit). Usesfork with memo: false so each iteration starts fresh from the original request, with targeted error feedback injected after failures.
whilecondition evaluated after each iteration withoutputs.*containing resultsthread: mode: forkwithmemo: falsegives each iteration a fresh start from the original requestinject.conditionadds error feedback only after the first iteration fails- In loop body,
iter.iterationis 0-indexed; inwhilecheck, it reflects completed iterations
Multi-Agent
Two Agents Taking Turns on Same Thread
Agents alternate on shared context (e.g., proposer/critic debate).- Both agents use
thread: mode: inheritto share context - Each agent sees what the other wrote
- Use
injectto add turn-specific instructions
Parallel Agents with Join
Launch multiple agents simultaneously, wait for all to complete.- See Threads for thread mode documentation (
fork,new,inherit) - Use unique
keyvalues for each parallel branch - A
type: joinnode waits for all incoming edges
Groups for Different Model Configs
Configure different settings for each agent type.- A group is an input with
type: group; its owninputs:nest inside it - Groups appear as collapsible sections in the UI
- Set
presets: { tag: agent }on a group to give it a preset picker - Reference group inputs as
inputs.GroupName.field
Context Management
Filter Large Tool Results with CallLLM
Reduce context bloat by summarizing large outputs.- Check
total_result_charsto decide filtering - An empty
preloaded_toolslist keeps the filtering call from using tools - Save the filtered text as a message so later turns see the short version
Compact When Tokens Exceed Threshold
Trigger context compaction after tool execution.thread_token_countavailable after ExecuteTools or SaveMessage- Compact saves its summary message internally with the new context sequence
- No
save_messageblock needed for Compact nodes
Conditional Message Saving
Save messages only under certain conditions.save_message.conditioncontrols whether message is saved- Useful for feedback loops (only inject on failure)
- Message content can reference node outputs via
output.*
Approvals and Oversight
Approval with a Timeout
Ask a person before a step runs, and decide what happens if nobody answers.statusisapproved,deniedortimeout- With no edge for
denied, the branch simply ends there, as the built-in agent’s does when you deny a tool call - The approval appears in the chat and in the Inbox. In an unattended run (an automation) nobody can answer, so it resolves at once with status
unattended: neither granted nor denied. Gate onstatus == 'approved'and that case takes the not-approved branch
Audit Check Before Tool Execution
Run an auditor agent before allowing tool execution.- Use
response_toolto ask for structured output, described by a JSONschema - A
choiceenum plus avalueexplanation is a convenient shape for a decision - Access response data via
nodes.<execute_tools_node>.response_data.<tool_name>.choiceor.value, or directly on the Call LLM node asnodes.audit_check.response_data.choice - Auditor can use cheaper/faster model
Response Tools for Structured Feedback
Ask the LLM for a structured response through a “response tool”: a tool only the model can call, whose input is the answer, shaped by a JSONschema.
response_toolis a synthetic tool only the LLM can call- The Call LLM node parses the call into
response_data; anexecute_toolsnode that runs the call also has it, keyed by tool name - The tool is offered, not forced: guard reads with
has(), or usebuiltin://structured-agentto keep the model working until it answers through the tool
Worktrees
Create Worktree for Isolated Work
Give an agent its own working directory.- Include
workflow.idin name for uniqueness force: trueoverwrites existing worktree with same name- Reference worktree path via
nodes.create_worktree.path
Copy Env Files to Worktree
Include configuration files in new worktree.copy_filesare exact paths from the project root; nothing is searched for (.envis only the root.env— listfrontend/.envseparately)- Each path lands in the same place in the new worktree; a directory is copied whole and a missing path is skipped
- Files are copied from the project root, not the current worktree
Multiple Parallel Worktrees
Create isolated environments for competing implementations.- Create worktrees in parallel for faster setup
- Use
thread: mode: newso implementations don’t share context - Each parallel edge needs its own
- from:block
Complete Workflow Examples
Full workflow definitions showing how patterns combine into real-world solutions.Code Review Pipeline
Automatically review PRs with multiple specialized agents.- Parallel agents for different review focuses
- Fork threads to isolate each reviewer’s context
- Join to wait for all reviews before summarizing
Test-Driven Bug Fix
Implement a fix using a test-first approach with retry loop.- Test-first approach ensures fix is verified
- Loop with iteration limit prevents infinite retries
- Conditional message injection adds context on failures
Documentation Generator
Generate documentation for a codebase with structure analysis.- Sequential pipeline: analyze → generate → review
- Thread inheritance maintains context across stages
- Specialized prompts for each role
Parallel Implementation Competition
Have multiple agents implement the same feature, then pick the best.- Worktrees provide isolated Git environments
thread: mode: newkeeps implementations separate- Join synchronizes parallel work
- Final comparison sees both implementations’ context