Agent Builder User Guide

1. Introduction

The Agent Builder is a visual workflow designer that lets you create AI agents by connecting nodes together. Each node performs a specific function—from calling AI models to processing data to making decisions. By connecting nodes, you define how your agent behaves.

Key Concepts

• Agent Definition: A complete workflow that defines an AI agent's behavior
• Node: A single unit of work (e.g., calling an AI model, processing data)
• Connection: A link between nodes that defines the flow of execution
• Variable: Data that flows between nodes

2. Getting Started

Launching Agent Genesys

1. Open the Application: Launch Agent Genesys
2. Welcome Screen: If you see the welcome screen, click "New Agent Definition" button
3. Agent Builder Opens: You'll see the Agent Builder workspace

Prerequisites

Before building your first agent, make sure you have:

1. AI Provider API Keys: Configure at least one AI provider in Settings
   • OpenAI (recommended for beginners)
   • Anthropic Claude
   • Ollama (local models)
2. Basic Understanding: Familiarity with:
   • Basic programming concepts (variables, conditions)
   • How AI models work (prompts, responses)

3. Understanding the Interface

The Agent Builder interface consists of four main areas:

1. Header (Top Bar)

The header contains global actions:

• Agent Name: Click to edit your agent's name
• Menu Icon (☰): Access actions:
  • Load Agent: Open an existing agent definition
  • Save: Save your current agent
  • Test: Run your agent with test inputs
  • Export: Export your agent as an executable
  • Templates: Browse pre-built agent templates
  • Settings: Configure AI providers and API keys
  • Documentation: Generate documentation for your agent

Status Indicators:

• "Unsaved changes": Red indicator when you have unsaved work
• "Saved [time]": Green indicator showing last save time

2. Node Palette (Left Sidebar)

The Node Palette displays all available node types, organized by category:

• AI: Prompt nodes for calling AI models
• Data: Variable nodes for data manipulation
• Logic: Conditional nodes for branching logic
• File I/O: File read/write nodes
• Output: Output formatting nodes

Using the Node Palette:

• Click a node to add it to the canvas at a random position
• Drag a node to place it at a specific location
• Search using the search box at the top
• Expand/Collapse categories by clicking the category header

3. Canvas (Center Area)

The canvas is where you build your agent workflow:

• Adding Nodes: Click nodes in the palette or toolbar to add them
• Moving Nodes: Click and drag nodes to reposition them
• Connecting Nodes: Drag from an output handle (bottom) to an input handle (top) of another node
• Selecting Nodes: Click a node to select it (properties appear in right panel)
• Deleting: Select a node and press Delete key, or right-click and select "Delete"
• Panning: Click the Hand tool (👋) in the bottom toolbar, then click and drag the canvas
• Zooming: Use mouse wheel or zoom controls

Canvas Modes (Bottom Toolbar):

• Hand (👋): Pan mode - click and drag to move around
• Pointer (👆): Select mode - click to select nodes, drag to move them
• Node Icons: Click to enter "add node" mode, then click canvas to place

4. Properties Panel (Right Sidebar)

The Properties Panel shows configuration options for the selected node:

• Configuration Fields: Edit node-specific settings
• Error Handling: Configure retry policies and fallback behavior
• Validation: See any configuration errors
• Help: Hover over (?) icons for tooltips

Opening/Closing:

• Click the Properties icon in the right sidebar dock
• Automatically opens when you select a node
• Click outside the panel or press Escape to close

4. Creating Your First Agent

Let's build a simple agent that answers questions. This will introduce you to the basic workflow.

Step 1: Name Your Agent

1. Click on the agent name in the header (default: "New Agent Definition")
2. Type: "Simple Q&A Agent"
3. Press Enter or click outside to save

Step 2: Add a Prompt Node

1. In the Node Palette, find the "Prompt" node under AI category
2. Click the Prompt node
3. It appears on the canvas
4. Click the node to select it (the Properties Panel opens)

Step 3: Configure the Prompt Node

In the Properties Panel, configure:

1. Provider: Select openai (or your configured provider)
2. Model: Select gpt-4 or gpt-3.5-turbo
3. Prompt: Enter:

   You are a helpful assistant. Answer the following question clearly and concisely:
   
       {{input}}

   Note: {{input}} is a variable that will be replaced with user input when the agent runs
4. Temperature: Leave at 0.7 (default)
5. Max Tokens: Leave at 1000 (default)

The node is now configured!

Step 4: Add an Output Node

1. In the Node Palette, find the "Output" node under Output category
2. Click it to add to canvas
3. Position it below the Prompt node

Step 5: Connect the Nodes

1. Hover over the bottom handle of the Prompt node
2. Click and drag to the top handle of the Output node
3. Release to create a connection (you'll see a line between them)

Step 6: Configure the Output Node

1. Select the Output node
2. In Properties Panel:
   • Format: Select text
   • The output will display the AI's response as plain text

Step 7: Test Your Agent

1. Click "Test" in the header menu
2. Enter a test question in the input field (e.g., "What is artificial intelligence?")
3. Click "Run"
4. Watch the execution flow through your nodes
5. See the result in the output

Step 8: Save Your Agent

1. Click "Save" in the header menu
2. Your agent is now saved and can be loaded later

5. Node Types

This section details each node type, its purpose, and configuration options.

Prompt Node

Purpose: Calls AI models (OpenAI, Anthropic, Ollama) to generate text responses.

Category: AI

Configuration Options

Variable Syntax in Prompts

You can use variables in your prompts:

• {{input}} - User input to the agent
• {{node_id.output}} - Output from another node
• {{variable_name}} - Custom variable

You are a helpful customer support agent. The customer's question is:

    {{input}}

    Previous context:
    {{previous_messages}}

    Please provide a helpful response.

Output

• content - The AI's response text
• message - Same as content (for compatibility)
• provider - Provider name used
• model - Model name used
• usage - Token usage statistics
• finishReason - Why the response ended

Error Handling

• Retry Policy: Automatically retry failed API calls
• Fallback: Use default response if provider fails
• Timeout: Set maximum wait time for responses

Variable Node

Purpose: Manipulates and transforms data between nodes.

Category: Data

Configuration Options

Operations

1. Set Operation

Assigns a static value to a variable.

Config Fields:

• value: The value to assign (any type)

Operation: set
    Output: greeting
    Config.value: "Hello, welcome to our service!"

2. Transform Operation

Transforms a value using built-in functions.

Config Fields:

• transformFunction: Function to apply:
  • uppercase - Convert to uppercase
  • lowercase - Convert to lowercase
  • trim - Remove whitespace
  • capitalize - Capitalize first letter
  • reverse - Reverse string
  • length - Get length
  • split - Split by separator
  • join - Join array elements

Operation: transform
    Input: {{input}}
    Output: upper_input
    Config.transformFunction: uppercase

3. Extract Operation

Extracts a field from an object or array.

Config Fields:

• extractPath: Path to extract (e.g., user.name, items[0])

Operation: extract
    Input: {{user_data}}
    Output: username
    Config.extractPath: user.name

4. Combine Operation

Combines multiple variables into one.

Config Fields:

• combineVariables: Array of variable names to combine
• combineSeparator: Separator string (default: space)

Operation: combine
    Output: full_name
    Config.combineVariables: ["first_name", "last_name"]
    Config.combineSeparator: " "

5. Format Operation

Converts a value to a specific type.

Config Fields:

• formatType: Target type: json, string, number, boolean

Operation: format
    Input: {{data_object}}
    Output: json_string
    Config.formatType: json

6. Custom Operation

Evaluates a JavaScript expression.

Config Fields:

• customExpression: JavaScript expression

Operation: custom
    Input: {{numbers}}
    Output: sum
    Config.customExpression: input.reduce((a, b) => a + b, 0)

Output: Variable stored with the specified output name, accessible in subsequent nodes via {{output_name}}

Conditional Node

Purpose: Branches workflow execution based on conditions.

Category: Logic

Configuration Options

Condition Structure

Simple condition:

{
    "field": "{{variable_name}}",
    "operator": "equals",
    "value": "expected_value"
    }

Complex condition (AND/OR/NOT):

{
    "type": "and",
    "conditions": [
        { "field": "{{score}}", "operator": "greaterThan", "value": 80 },
        { "field": "{{status}}", "operator": "equals", "value": "active" }
    ]
    }

Operators

Connections

• True Path: Connect to node to execute when condition is true
• False Path: Connect to node to execute when condition is false

Output

• conditionResult - Boolean result
• branch - "true" or "false"
• truePathLabel - Label for true path
• falsePathLabel - Label for false path

Condition:
    Field: {{user_type}}
    Operator: equals
    Value: "premium"

    True Path Label: "Premium User"
    False Path Label: "Standard User"

File Read Node

Purpose: Reads files from the file system.

Category: File I/O

Configuration Options

Supported Formats

• text: Plain text files
• json: JSON files (automatically parsed)
• csv: CSV files (requires additional parsing)
• auto: Detect format from file extension

Variable Support

File path can include variables:

• {{variable}} - Replaced at runtime
• Example: /data/users/{{user_id}}.json

Output

• content - File contents (parsed if JSON)
• metadata.path - File path
• metadata.size - File size in bytes
• metadata.format - Detected/used format
• metadata.encoding - Encoding used

Error Handling

• File not found → Error node result
• Permission denied → Error node result
• Invalid JSON → Error node result

File Path: ./config/settings.json
    Format: json
    Encoding: utf8

File Write Node

Purpose: Writes data to files.

Category: File I/O

Configuration Options

Write Modes

• overwrite: Replace existing file (default)
• append: Add to end of existing file

Variable Support

File path and data can include variables:

• Example: Write to /logs/{{date}}.txt

Output

• filePath - Path to written file
• bytesWritten - Number of bytes written
• success - Boolean indicating success

File Path: ./output/response.txt
    Data: {{ai_response}}
    Format: text
    Encoding: utf8
    Mode: overwrite

Output Node

Purpose: Formats and displays the final output of your agent.

Category: Output

Configuration Options

Formats

1. JSON Format

Returns structured JSON output.

Config Fields:

• fields: Optional array of field names to include (if empty, includes all fields)

Format: json
    Fields: ["response", "confidence", "source"]

2. Text Format

Returns plain text output.

Format: text

3. Custom Format

Returns formatted output using a template.

Config Fields:

• template: Template string with {{variable}} placeholders

Format: custom
    Template: |
    Response: {{response}}
    Confidence: {{confidence}}%
    Generated at: {{timestamp}}

Output: Formatted output based on selected format, displayed in the test runner or returned to caller.

6. Common Agent Patterns

This section shows how to build common agent types using the nodes described above.

7. Best Practices

1. Naming Conventions

• Use descriptive names: "Customer Support Bot" not "Bot1"
• Name nodes meaningfully: "Extract User Email" not "Variable1"
• Use clear variable names: user_email not ue

2. Organizing Your Canvas

• Layout left-to-right: Start with input on left, end with output on right
• Group related nodes: Keep conditional branches near each other
• Leave space: Don't crowd nodes together
• Use alignment: Align nodes for readability

3. Variable Management

• Reuse variables: Store reusable data in variables
• Clear naming: Use descriptive variable names
• Document purpose: Add comments (via node labels) explaining variables

4. Error Handling

• Always configure retries: Set retry policies for API calls
• Set fallbacks: Provide fallback responses for critical nodes
• Test error cases: Test what happens when nodes fail

5. Testing

• Test incrementally: Test as you build, not just at the end
• Use varied inputs: Test with different input types
• Test edge cases: Test with empty inputs, long inputs, special characters
• Verify outputs: Check that outputs match expectations

6. Performance

• Choose appropriate models: Use gpt-3.5-turbo for simple tasks, gpt-4 for complex ones
• Limit token usage: Set reasonable maxTokens values
• Avoid unnecessary nodes: Don't add nodes that don't contribute
• Cache when possible: Reuse computed values instead of recomputing

7. Security

• Don't hardcode API keys: Use Settings to configure keys
• Validate inputs: Use conditional nodes to validate user input
• Sanitize file paths: Be careful with user-provided file paths
• Review prompts: Ensure prompts don't expose sensitive information

8. Documentation

• Add descriptions: Use node labels to explain purpose
• Document complex logic: Add comments for complicated workflows
• Keep it simple: Simple workflows are easier to maintain

Next Steps

Now that you understand the Agent Builder:

1. Explore Templates: Browse pre-built templates in the Templates gallery
2. Build Complex Agents: Combine multiple patterns for sophisticated agents
3. Export Your Agents: Export agents as standalone executables
4. Learn Orchestration: Move on to building multi-agent orchestrations
5. Share Your Agents: Export and share agent definitions with your team

Troubleshooting

Agent doesn't respond

• Check API keys are configured in Settings
• Verify provider and model are correct
• Check network connection
• Review error messages in test output

Variables not working

• Ensure variable names match exactly (case-sensitive)
• Check variable is set before it's used
• Verify variable syntax: {{variable_name}}

Nodes not connecting

• Make sure you drag from output handle (bottom) to input handle (top)
• Some nodes may not have inputs/outputs (check node documentation)
• Verify connection is valid (no circular dependencies)

File operations fail

• Check file paths are correct (absolute or relative)
• Verify file permissions
• Ensure directories exist for file writes
• Check file format matches configuration

Performance issues

• Reduce token limits
• Use faster models (gpt-3.5-turbo vs gpt-4)
• Simplify workflows (fewer nodes)
• Check for unnecessary API calls

Additional Resources

• Templates Gallery: Browse pre-built agent templates
• API Documentation: Detailed API reference
• Community Examples: Share and learn from community
• Support: Get help from the Agent Genesys community

Happy building! 🚀