Workflow Integration

Overview

Integrating AI agents into workflows enables powerful automation scenarios. Agents can process data, make decisions, generate content, and interact with other workflow nodes to create intelligent automation pipelines.

AI Agent Node

The AI Agent node allows you to call an agent from within a workflow.

Basic Configuration

jsonCopy
{
  "node": {
    "type": "ai_agent",
    "name": "Process Support Request",
    "config": {
      "agent_id": "agent_abc123",
      "message": "{{trigger.data.message}}",
      "wait_for_response": true
    }
  }
}

Node Properties

Integration Patterns

1. Simple Processing

Single agent processes input and returns result:

┌──────────┐    ┌──────────┐    ┌──────────┐
│ Webhook  │───▶│ AI Agent │───▶│  HTTP    │
│ Trigger  │    │ Process  │    │ Response │
└──────────┘    └──────────┘    └──────────┘

Example: Email Classification

jsonCopy
{
  "workflow": {
    "nodes": [
      {
        "id": "trigger",
        "type": "webhook",
        "config": {
          "method": "POST",
          "path": "/incoming-email"
        }
      },
      {
        "id": "classify",
        "type": "ai_agent",
        "config": {
          "agent_id": "email_classifier",
          "message": "Classify this email and extract key information:\n\nSubject: {{trigger.body.subject}}\nBody: {{trigger.body.content}}",
          "response_format": {
            "type": "json",
            "schema": {
              "category": "string",
              "priority": "string",
              "sentiment": "string",
              "key_topics": "array"
            }
          }
        }
      },
      {
        "id": "route",
        "type": "switch",
        "config": {
          "expression": "{{classify.response.category}}"
        }
      }
    ]
  }
}

2. Decision Making

Agent makes decisions that control workflow branching:

                    ┌─────────────┐
                    │  AI Agent   │
                    │  Evaluate   │
                    └──────┬──────┘
                           │
            ┌──────────────┼──────────────┐
            ▼              ▼              ▼
      ┌──────────┐  ┌──────────┐  ┌──────────┐
      │ Approve  │  │  Review  │  │  Reject  │
      └──────────┘  └──────────┘  └──────────┘

Example: Lead Qualification

jsonCopy
{
  "nodes": [
    {
      "id": "qualify",
      "type": "ai_agent",
      "config": {
        "agent_id": "lead_qualifier",
        "message": "Evaluate this lead based on our ideal customer profile:\n\nCompany: {{trigger.company}}\nRole: {{trigger.role}}\nCompany Size: {{trigger.company_size}}\nIndustry: {{trigger.industry}}\nBudget: {{trigger.budget}}",
        "response_format": {
          "type": "json",
          "schema": {
            "score": "number",
            "qualification": "enum:hot,warm,cold",
            "reasoning": "string",
            "next_steps": "array"
          }
        }
      }
    },
    {
      "id": "route_lead",
      "type": "switch",
      "config": {
        "cases": [
          {
            "condition": "{{qualify.response.qualification}} === 'hot'",
            "next": "notify_sales_urgent"
          },
          {
            "condition": "{{qualify.response.qualification}} === 'warm'",
            "next": "add_to_nurture"
          },
          {
            "condition": "{{qualify.response.qualification}} === 'cold'",
            "next": "send_resources"
          }
        ]
      }
    }
  ]
}

3. Content Generation

Agent generates content for downstream use:

Example: Personalized Response

jsonCopy
{
  "nodes": [
    {
      "id": "get_customer",
      "type": "database",
      "config": {
        "operation": "select",
        "table": "customers",
        "where": { "id": "{{trigger.customer_id}}" }
      }
    },
    {
      "id": "generate_response",
      "type": "ai_agent",
      "config": {
        "agent_id": "response_writer",
        "message": "Write a personalized response to this customer inquiry:\n\nCustomer: {{get_customer.rows[0].name}}\nPlan: {{get_customer.rows[0].plan}}\nHistory: {{get_customer.rows[0].support_history}}\n\nInquiry: {{trigger.message}}",
        "context": {
          "tone": "friendly",
          "max_length": 200
        }
      }
    },
    {
      "id": "send_email",
      "type": "send_email",
      "config": {
        "to": "{{trigger.email}}",
        "subject": "Re: {{trigger.subject}}",
        "body": "{{generate_response.response}}"
      }
    }
  ]
}

4. Multi-Agent Pipeline

Chain multiple agents for complex processing:

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Extract  │───▶│ Analyze  │───▶│ Generate │───▶│  Review  │
│  Agent   │    │  Agent   │    │  Agent   │    │  Agent   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘

Example: Document Processing Pipeline

jsonCopy
{
  "nodes": [
    {
      "id": "extract",
      "type": "ai_agent",
      "config": {
        "agent_id": "document_extractor",
        "message": "Extract all key information from this document: {{trigger.document_content}}"
      }
    },
    {
      "id": "analyze",
      "type": "ai_agent",
      "config": {
        "agent_id": "data_analyzer",
        "message": "Analyze this extracted data and identify patterns:\n{{extract.response}}"
      }
    },
    {
      "id": "generate_report",
      "type": "ai_agent",
      "config": {
        "agent_id": "report_writer",
        "message": "Generate an executive summary based on this analysis:\n{{analyze.response}}"
      }
    },
    {
      "id": "quality_check",
      "type": "ai_agent",
      "config": {
        "agent_id": "quality_reviewer",
        "message": "Review this report for accuracy and completeness:\n{{generate_report.response}}",
        "response_format": {
          "type": "json",
          "schema": {
            "approved": "boolean",
            "issues": "array",
            "final_report": "string"
          }
        }
      }
    }
  ]
}

Conversation Management

New Conversation

Each workflow execution starts fresh:

jsonCopy
{
  "config": {
    "agent_id": "support_agent",
    "message": "{{trigger.message}}",
    "conversation_mode": "new"
  }
}

Continue Conversation

Maintain context across workflow executions:

jsonCopy
{
  "config": {
    "agent_id": "support_agent",
    "message": "{{trigger.message}}",
    "conversation_id": "{{trigger.conversation_id}}",
    "conversation_mode": "continue"
  }
}

Store Conversation ID

Save conversation ID for future use:

jsonCopy
{
  "nodes": [
    {
      "id": "agent_response",
      "type": "ai_agent",
      "config": {
        "agent_id": "support_agent",
        "message": "{{trigger.message}}"
      }
    },
    {
      "id": "store_conversation",
      "type": "database",
      "config": {
        "operation": "update",
        "table": "tickets",
        "set": {
          "conversation_id": "{{agent_response.conversation_id}}"
        },
        "where": { "id": "{{trigger.ticket_id}}" }
      }
    }
  ]
}

Response Handling

Structured Responses

Request JSON responses for easier processing:

jsonCopy
{
  "config": {
    "agent_id": "analyzer",
    "message": "Analyze this support ticket",
    "response_format": {
      "type": "json",
      "schema": {
        "category": {
          "type": "string",
          "enum": ["billing", "technical", "general"]
        },
        "priority": {
          "type": "string",
          "enum": ["low", "medium", "high", "urgent"]
        },
        "suggested_response": {
          "type": "string"
        },
        "escalate": {
          "type": "boolean"
        }
      }
    }
  }
}

Using Response Data

Access response fields in subsequent nodes:

jsonCopy
{
  "nodes": [
    {
      "id": "analyze",
      "type": "ai_agent"
    },
    {
      "id": "condition",
      "type": "condition",
      "config": {
        "expression": "{{analyze.response.priority}} === 'urgent' && {{analyze.response.escalate}} === true"
      }
    },
    {
      "id": "create_ticket",
      "type": "database",
      "config": {
        "operation": "insert",
        "table": "tickets",
        "values": {
          "category": "{{analyze.response.category}}",
          "priority": "{{analyze.response.priority}}",
          "suggested_response": "{{analyze.response.suggested_response}}"
        }
      }
    }
  ]
}

Context Injection

Static Context

Provide fixed context to the agent:

jsonCopy
{
  "config": {
    "agent_id": "support_agent",
    "message": "{{trigger.message}}",
    "context": {
      "product": "Arcanflows",
      "support_hours": "9am-5pm EST",
      "current_promotions": ["20% off annual plans"]
    }
  }
}

Dynamic Context

Include data from other nodes:

jsonCopy
{
  "config": {
    "agent_id": "support_agent",
    "message": "{{trigger.message}}",
    "context": {
      "customer_name": "{{lookup_customer.rows[0].name}}",
      "customer_plan": "{{lookup_customer.rows[0].plan}}",
      "recent_orders": "{{get_orders.rows}}",
      "open_tickets": "{{get_tickets.rows}}"
    }
  }
}

Error Handling

Timeout Handling

jsonCopy
{
  "config": {
    "agent_id": "analyzer",
    "timeout": 60,
    "on_timeout": {
      "action": "fallback",
      "fallback_response": {
        "category": "unknown",
        "priority": "medium",
        "note": "Agent timeout - manual review required"
      }
    }
  }
}

Error Recovery

jsonCopy
{
  "config": {
    "agent_id": "processor",
    "error_handling": {
      "on_error": {
        "action": "retry",
        "max_retries": 2,
        "retry_delay": 5000
      },
      "on_final_error": {
        "action": "continue",
        "set_variable": {
          "agent_error": true,
          "agent_error_message": "{{error.message}}"
        }
      }
    }
  }
}

Best Practices

1. Use Structured Responses

Always request JSON when you need to use the data:

jsonCopy
{
  "response_format": {
    "type": "json",
    "strict": true
  }
}

2. Provide Clear Instructions

Be specific in your message prompts:

jsonCopy
{
  "message": "Classify the following customer inquiry into exactly one category: billing, technical, sales, or general. Respond with JSON containing 'category' and 'confidence' fields.\n\nInquiry: {{trigger.message}}"
}

3. Handle Edge Cases

Account for unexpected responses:

jsonCopy
{
  "nodes": [
    {
      "id": "validate",
      "type": "condition",
      "config": {
        "expression": "{{agent.response.category}} !== undefined && {{agent.response.category}} !== null"
      }
    }
  ]
}

4. Monitor Performance

Track agent performance in workflows:

jsonCopy
{
  "monitoring": {
    "log_responses": true,
    "track_latency": true,
    "alert_on_timeout": true
  }
}

5. Optimize Token Usage

Pass only necessary context:

jsonCopy
{
  "context": {
    "customer_summary": "{{customer.name}} - {{customer.plan}} plan",
    "relevant_orders": "{{orders | slice(0, 3)}}"
  }
}

Example Workflows

Support Ticket Router

jsonCopy
{
  "name": "Support Ticket Router",
  "trigger": {
    "type": "webhook",
    "path": "/support/new-ticket"
  },
  "nodes": [
    {
      "id": "classify",
      "type": "ai_agent",
      "config": {
        "agent_id": "ticket_classifier",
        "message": "Classify this support ticket:\n\n{{trigger.body.description}}",
        "response_format": {
          "type": "json",
          "schema": {
            "department": "string",
            "priority": "string",
            "tags": "array"
          }
        }
      }
    },
    {
      "id": "create_ticket",
      "type": "database",
      "config": {
        "operation": "insert",
        "table": "tickets",
        "values": {
          "subject": "{{trigger.body.subject}}",
          "description": "{{trigger.body.description}}",
          "department": "{{classify.response.department}}",
          "priority": "{{classify.response.priority}}",
          "tags": "{{classify.response.tags}}"
        }
      }
    },
    {
      "id": "notify",
      "type": "send_notification",
      "config": {
        "channel": "slack",
        "message": "New {{classify.response.priority}} ticket: {{trigger.body.subject}}"
      }
    }
  ]
}

Automated Report Generator

jsonCopy
{
  "name": "Weekly Report Generator",
  "trigger": {
    "type": "schedule",
    "cron": "0 9 * * 1"
  },
  "nodes": [
    {
      "id": "get_data",
      "type": "database",
      "config": {
        "operation": "raw",
        "query": "SELECT * FROM metrics WHERE created_at > NOW() - INTERVAL '7 days'"
      }
    },
    {
      "id": "analyze",
      "type": "ai_agent",
      "config": {
        "agent_id": "data_analyst",
        "message": "Analyze this week's metrics and provide insights:\n{{get_data.rows | json}}"
      }
    },
    {
      "id": "generate_report",
      "type": "ai_agent",
      "config": {
        "agent_id": "report_writer",
        "message": "Write a professional weekly report based on:\n{{analyze.response}}"
      }
    },
    {
      "id": "send_report",
      "type": "send_email",
      "config": {
        "to": ["[email protected]"],
        "subject": "Weekly Performance Report",
        "body": "{{generate_report.response}}"
      }
    }
  ]
}