Circuitry Logo
Circuitry
Open Circuitry

Your First Workflow

Let's build your first AI-powered workflow step by step. We'll create a simple translation workflow that demonstrates the core concepts of Circuitry.

Understanding the Canvas

Every workflow in Circuitry starts with a Start node - this is automatically created for you and represents the entry point of your workflow. The Start node is where data enters your workflow, either from manual input during testing or from external triggers.

What We'll Build

A workflow that:

  1. Takes text input from the Start node
  2. Translates it using AI
  3. Shows the results visually

Step-by-Step Guide

Step 1: Adding Nodes to Your Workflow

There are two ways to add nodes to your canvas:

Method 1: Drag and Drop

  1. Find the node in the left sidebar under "Nodes"
  2. Click and drag the node type you want
  3. Drop it onto the canvas where you want it positioned

Method 2: Connection Menu (Quick Add)

  1. Click and drag from any edge of a node — connection points appear on all four sides when you hover
  2. Release on empty canvas space
  3. A node selection menu appears at your cursor
  4. Click the node type you want to add - it's automatically connected!

💡 Pro Tip: The connection menu method is faster when building linear workflows since it creates and connects nodes in one action.

Step 2: Add an AI Agent Node

Using either method above:

  1. Add an Agent Node below your Start node (flows read top-to-bottom by default)
  2. If using drag-and-drop, you'll need to connect them:
    • Click and drag from any edge of the Start node
    • Drop on any edge of the Agent node
    • A line appears showing the connection — it routes to the nearest sensible side automatically

Step 3: Connect the Nodes (if needed)

If you used the connection menu, your nodes are already connected! Otherwise:

  1. Create the Connection
    • Hover over the Start node — connection points appear on its edges
    • Click and drag from any edge to any edge of the Agent node
    • Release to create the connection
    • You should see a line connecting them, showing the direction data flows

Step 4: Configure the Start Node

  1. Click on the Start Node to select it
  2. In the right panel, you'll see configuration options
  3. Add test data in the JSON input field: 
    {
  "message": "Hello World",
  "language": "French"
}

Step 5: Configure the Agent Node

  1. Click on the Agent Node to select it

  2. In the right panel, configure:

    Model: pick any of the available models — the default is a good start

    Prompt:

    Translate the following text to {{input.language}}:
"{{input.message}}"

Provide only the translation, no explanations.

    Temperature: 0.3 (lower = more consistent)

    Max Tokens: 100 (enough for short translations)

Step 6: Save Your Workflow

  • Auto-save: Your workflow saves automatically as you build
  • Manual save: Press Cmd+S (Mac) or Ctrl+S (Windows)
  • Name your workflow: Click the title at the top to rename

Step 7: Execute the Workflow

  1. Click the Run button (▶️) in the top toolbar
  2. Watch the visual feedback:
    • Start node turns blue (executing)
    • Connection line animates showing data flow
    • Agent node turns blue (processing)
    • Nodes turn green when complete
  3. View the results:
    • Click on the Agent node
    • See the output in the right panel
    • Should show: "Bonjour le monde"

Understanding What Happened

Data Flow

  1. Start node provided the input data
  2. Data flowed through the connection
  3. Agent node received the data as input
  4. AI processed the prompt with your data
  5. Translation was returned as output

Template Variables

  • {{input.message}} was replaced with "Hello World"
  • {{input.language}} was replaced with "French"
  • These work anywhere in prompts

Visual Feedback

  • Blue glow: Node is currently executing
  • Green check: Node completed successfully
  • Red X: Node encountered an error
  • Animated connection: Data is flowing

Try These Variations

Different Languages

Change the Start node data:

{
  "message": "Hello World",
  "language": "Spanish"  // or "Japanese", "German", etc.
}

Multiple Translations

Add more Agent nodes for multiple languages:

  1. Duplicate the Agent node — select it and click Duplicate in the toolbar that appears
  2. Connect Start to both Agent nodes
  3. Set different languages in each prompt
  4. Run to get parallel translations!

Add Context

Enhance the prompt for better translations:

Translate to {{input.language}} in a formal business context:
"{{input.message}}"

Common Issues & Solutions

"No output from Agent"

  • Check your API key is configured in Settings
  • Ensure the model is selected
  • Verify prompt has closing quotes

"Connection won't stick"

  • Drag from one node's edge to the other node — connection points sit on all four sides
  • Handles glow when hovering if connection is valid
  • Can't connect same node to itself
  • Drag to empty space to open the quick-add node menu

"Workflow won't run"

  • Ensure all nodes are connected
  • Start node must have at least one connection
  • Check for red error indicators on nodes

Next Steps

Enhance Your Workflow

  1. Add a Condition Node

    • Branch based on language
    • Route to different Agent configurations

  2. Use the Code Node

    • Click ✨ AI Wizard
    • Describe: "Format the translation as a JSON response"
    • Auto-generates the code!

  3. Try the Plugin Wizard

    • Click ✨ (Create new plugin with AI) next to Plugins in sidebar
    • Describe any API integration
    • Creates a complete plugin automatically

Learn More

Tips for Success

  1. Start Simple: Build complexity gradually
  2. Use AI Wizards: Let AI write code and conditions for you
  3. Test Often: Run after each change to catch issues early
  4. Watch the Flow: Visual feedback helps understand execution
  5. Read Node Output: Click nodes after running to see their data

Congratulations! 🎉

You've built your first AI-powered workflow! You've learned:

  • ✅ How to add and connect nodes
  • ✅ Configuring AI agents
  • ✅ Using template variables
  • ✅ Executing and debugging workflows

Keep experimenting and building more complex automations. The AI wizards are always there to help!