HomeCommunityDiscordLogin

Workflow Tools Configuration

🔄 Turn Workflows Into Agent Tools

The Workflows tab is where your AI agent gains the superpower to execute complex, multi-step automations on demand. By configuring workflows as tools, your agent can intelligently decide when and how to trigger sophisticated business processes based on conversation context, user requests, or specific conditions—transforming your agent from a simple chatbot into a powerful automation orchestrator.

🎯 What Are Workflow Tools?

Workflow tools allow your AI agent to execute pre-built visual workflows (with 193+ available nodes) as callable functions. When configured as tools:

  • Agent Decides When: The AI determines when a workflow should run based on user intent

  • Dynamic Input: Agent extracts parameters from conversation and passes them to the workflow

  • Real-Time Execution: Workflow runs and returns results back to the agent

  • Conversational Feedback: Agent interprets workflow output and responds naturally to the user

  • Error Handling: Agent can gracefully handle workflow failures and provide alternatives

🏗️ How Workflow Tools Work

When you add a workflow as a tool to your agent, the system creates a specialized function that:

  1. Exposes Workflow Parameters: The workflow's input schema becomes the tool's parameter schema

  2. Generates Tool Description: Uses the workflow's description to help the agent understand when to use it

  3. Handles Execution: Runs the workflow in the background when the agent calls the tool

  4. Returns Results: Provides workflow output, status, and any errors back to the agent

  5. Enables Conversation: Agent interprets results and communicates naturally with the user

Execution Flow Example

User: "Please process my order for 100 units of Product X"
↓
Agent Analysis: Identifies order processing intent
↓
Tool Selection: Chooses "Order Processing" workflow tool
↓
Parameter Extraction:
  - product = "Product X"
  - quantity = 100
  - customer_id = (from conversation context)
↓
Workflow Execution:
  1. Validate inventory availability
  2. Check customer credit limit
  3. Generate order confirmation
  4. Send to fulfillment team
  5. Update CRM records
↓
Tool Response:
  - output: {"order_id": "12345", "status": "confirmed"}
  - status: "success"
  - error: null
↓
Agent Response: "Your order has been processed successfully!
Confirmation #12345 has been sent to your email."

⚙️ Configuring Workflow Tools

To configure a workflow as an agent tool, you need to provide the following configuration settings. These settings control how the agent interacts with and executes your workflow:

🎛️ Tool Configuration Settings

1. Workflow Selection

Workflow ID (Required)

  • Choose which workflow this tool will execute

  • Only workflows in your workspace are available

  • Workflow must have a defined input schema

Example:
Workflow: "Customer Onboarding Workflow"
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

2. Tool Description

Description (Optional, but Highly Recommended)

  • Overrides the workflow's default description

  • Helps the agent understand when and how to use this tool

  • Should clearly explain the tool's purpose, required context, and expected outcomes

Default Behavior:
If not provided, agent uses the workflow's description field

Best Practice Example:
Description: "Use this tool to onboard new enterprise customers.
Required information: company name, contact email, industry, and
estimated user count. Call this tool when a new enterprise customer
signs up or requests onboarding assistance."

Poor Example:
Description: "Onboards customers" (Too vague)

Writing Effective Tool Descriptions:

Good Tool Descriptions Include:
✅ Purpose: What does this tool do?
✅ When to Use: Under what circumstances should agent call it?
✅ Required Inputs: What parameters are needed?
✅ Expected Output: What will the tool return?
✅ Context Clues: Keywords or phrases that indicate this tool is needed

Example Templates:

1. Process Automation:
"Use this tool to process [ACTION] when the user requests [INTENT].
Required: [PARAM1], [PARAM2]. Returns: [OUTPUT_DESCRIPTION]"

2. Data Retrieval:
"Call this tool to fetch [DATA_TYPE] from [SOURCE]. Requires [FILTERS].
Returns structured data including [FIELDS]"

3. Business Logic:
"Execute this tool to [BUSINESS_PROCESS]. Use when user mentions
[KEYWORDS]. Input: [PARAMS]. Output: [RESULT] with status indicator"

3. Timeout Configuration

Timeout (Required, Default: 150 seconds)

  • Maximum time (in seconds) the agent will wait for workflow completion

  • Range: 1-300 seconds (5 minutes maximum)

  • If exceeded, agent receives timeout error and can respond accordingly

Timeout Guidelines:

Quick Operations (1-30 seconds):
- Database queries
- API lookups
- Simple calculations
- File reads

Standard Operations (30-90 seconds):
- Multi-step processes
- External API integrations
- Document generation
- Email sending

Complex Operations (90-300 seconds):
- Large data processing
- Multiple external service calls
- Report generation with aggregation
- Batch operations

Example Configuration:
Quick Lookup Workflow: timeout = 30
Order Processing: timeout = 90
Monthly Report Generation: timeout = 300

Handling Timeouts:

When Timeout Occurs:
- Agent receives error status from tool
- Can inform user of delay and suggest alternatives
- Can retry with different parameters if appropriate
- Should log timeout for monitoring and optimization

Agent Response Example:
"I started processing your request, but it's taking longer than
expected. I've queued it for completion and you'll receive an
email notification when it's done. Can I help you with anything
else in the meantime?"

4. Input Configuration (Pre-filled Parameters)

Input Config (Optional)

  • Pre-configure specific workflow input parameters

  • Remove parameters from agent's decision-making

  • Useful for setting constant values, security constraints, or workspace context

Purpose:
✅ Set constant values (workspace_id, api_keys, etc.)
✅ Apply security constraints (user_role, permissions)
✅ Provide context not available to agent (configuration settings)
✅ Simplify agent's parameter decisions

How Input Config Works

When you specify input_config, those parameters:

  1. Are automatically filled with your specified values

  2. Are removed from the tool's schema (agent doesn't see them)

  3. Cannot be overridden by the agent

Example 1: Workspace Context
Workflow Input Schema:
{
  "workspace_id": "string (required)",
  "customer_email": "string (required)",
  "action": "string (required)"
}

Input Config:
{
  "workspace_id": "{{ workspace_id }}"  # Automatically populated
}

Agent Only Sees:
{
  "customer_email": "string (required)",
  "action": "string (required)"
}

Result:
- Agent extracts customer_email and action from conversation
- workspace_id is automatically injected from context
- Agent doesn't need to know or decide workspace_id
Example 2: Security Constraints
Workflow Input Schema:
{
  "user_id": "string (required)",
  "action": "string (required)",
  "max_amount": "number (required)",
  "requires_approval": "boolean (required)"
}

Input Config:
{
  "max_amount": 1000,
  "requires_approval": true
}

Agent Only Sees:
{
  "user_id": "string (required)",
  "action": "string (required)"
}

Result:
- Agent cannot exceed $1000 limit (hardcoded)
- Approval is always required (security enforcement)
- Agent only decides user_id and action
Example 3: Configuration Values
Workflow Input Schema:
{
  "email_template": "string (required)",
  "recipient": "string (required)",
  "sender_name": "string (required)",
  "reply_to": "string (required)"
}

Input Config:
{
  "sender_name": "Customer Support Team",
  "reply_to": "[email protected]"
}

Agent Only Sees:
{
  "email_template": "string (required)",
  "recipient": "string (required)"
}

Result:
- Consistent sender identity across all emails
- Standardized reply-to address
- Agent chooses template and recipient only

Advanced Input Config Patterns:

Pattern 1: Dynamic Templates with Static Constraints
{
  "template_type": "{{user_tier}}_welcome",  # Dynamic from context
  "max_discount": 0.15,                       # Static limit
  "currency": "USD"                           # Static config
}

Pattern 2: Role-Based Parameter Injection
{
  "user_role": "{{current_user_role}}",      # From auth context
  "access_level": "read_only",                # Security constraint
  "audit_enabled": true                       # Compliance requirement
}

Pattern 3: Environment Configuration
{
  "api_endpoint": "{{env.api_base_url}}",    # Environment variable
  "rate_limit": 100,                          # Quota management
  "retry_attempts": 3                         # Reliability setting
}

When to Use Input Config:

Best Practices:

Use Input Config For:
✅ Security-sensitive values (API keys, credentials)
✅ Workspace or tenant identifiers
✅ Compliance requirements (audit flags, data retention)
✅ Rate limits and quotas
✅ Standard business rules
✅ Configuration that shouldn't change per-request
✅ Values the agent shouldn't decide

Don't Use Input Config For:
❌ User-provided data (names, emails, preferences)
❌ Request-specific parameters (search queries, filters)
❌ Dynamic business logic decisions
❌ Values that vary based on conversation context

📊 Workflow Tool Response Format

When a workflow tool executes, it returns a structured response to the agent:

Success Response

{
  "output": "{\"order_id\": \"12345\", \"total\": 1500.00}",
  "status": "success",
  "error": null
}

Error Response (Detailed)

{
  "output": null,
  "status": "error",
  "error": {
    "message": "Insufficient inventory for requested quantity",
    "code": "INVENTORY_ERROR",
    "failed_node": "Check Inventory Node",
    "workflow_id": "abc-123-def",
    "workflow_name": "Order Processing",
    "node_error": {
      "node_name": "inventory_check",
      "error_message": "Available: 50, Requested: 100",
      "error_code": "INSUFFICIENT_STOCK",
      "error_details": {"available": 50, "requested": 100}
    }
  }
}

Error Response (Anonymous Users)

{
  "output": null,
  "status": "error",
  "error": "An error occurred while running the workflow."
}

How Agents Handle Responses:

Success:
- Agent parses output JSON
- Extracts relevant data
- Formulates natural language response
- May suggest next steps

Example:
Output: {"order_id": "12345", "total": 1500}
Agent: "Your order #12345 has been placed successfully!
Total: $1,500. You'll receive confirmation shortly."

Error:
- Agent receives error details
- Explains what went wrong in user-friendly terms
- Suggests alternatives or solutions
- May retry with different parameters

Example:
Error: "Insufficient inventory"
Agent: "I'm sorry, we only have 50 units available, but you
requested 100. Would you like to order 50 units now, or would
you prefer to wait until we restock?"

📊 Workflow Types & Use Cases

🎨 Data Processing Workflows as Tools

Configure data-focused workflows as agent tools for automated information handling:

Use Cases:
├── Customer Data Enrichment
│   ├── Agent: Receives customer email or ID
│   ├── Workflow: Fetches CRM data, social profiles, purchase history
│   └── Returns: Enriched customer profile
│
├── Report Generation on Demand
│   ├── Agent: User requests "monthly sales report"
│   ├── Workflow: Queries database, generates charts, formats PDF
│   └── Returns: Download link and summary statistics
│
├── Data Validation & Cleanup
│   ├── Agent: User uploads CSV file
│   ├── Workflow: Validates format, deduplicates, enriches missing fields
│   └── Returns: Cleaned data file and validation report
│
└── Real-Time Data Aggregation
    ├── Agent: User asks "what's our current revenue?"
    ├── Workflow: Queries multiple sources, calculates totals
    └── Returns: Real-time financial metrics

Configuration Example:

Workflow Tool: "Customer Data Lookup"
Description: "Use this tool to fetch detailed customer information
when the user provides a customer ID, email, or company name.
Returns: customer profile, purchase history, support tickets, and
account status."

Run Behavior: auto_run (safe read-only operation)
Timeout: 45 seconds
Input Config:
{
  "data_sources": ["crm", "support", "billing"],
  "include_pii": false  # Compliance constraint
}

⚙️ Business Process Workflows as Tools

Turn complex business processes into agent-callable tools:

Use Cases:
├── Order Processing
│   ├── Agent: "Process order for 100 units"
│   ├── Workflow: Inventory check → Credit verification → Order creation → Notification
│   ├── Run Behavior: request_confirmation (financial transaction)
│   └── Returns: Order ID, confirmation, estimated delivery
│
├── Customer Onboarding
│   ├── Agent: "Onboard new enterprise customer"
│   ├── Workflow: Account creation → Setup tasks → Welcome emails → Team assignment
│   ├── Run Behavior: auto_run (internal process)
│   └── Returns: Account details, next steps checklist
│
├── Support Ticket Escalation
│   ├── Agent: Detects high-priority issue
│   ├── Workflow: Classify urgency → Assign specialist → Notify stakeholders
│   ├── Run Behavior: auto_run (time-sensitive)
│   └── Returns: Ticket ID, assigned agent, SLA timeline
│
└── Document Approval Workflow
    ├── Agent: "Submit contract for approval"
    ├── Workflow: Upload document → Route to approvers → Track status
    ├── Run Behavior: request_confirmation (legal process)
    └── Returns: Approval tracking link, estimated completion

🤖 Integration Workflows as Tools

Connect external systems and services through workflow tools:

Use Cases:
├── Multi-System Data Sync
│   ├── Agent: "Sync customer data across systems"
│   ├── Workflow: CRM → Marketing Platform → Support System → Analytics
│   ├── Tools Used: Salesforce, HubSpot, Zendesk, Google Sheets
│   └── Returns: Sync status, records updated, any conflicts
│
├── Email Campaign Trigger
│   ├── Agent: "Send welcome email to new users"
│   ├── Workflow: Template selection → Personalization → Send via API
│   ├── Tools Used: Email service provider (SendGrid, Mailchimp)
│   └── Returns: Campaign ID, recipients count, delivery status
│
├── Payment Processing
│   ├── Agent: "Process refund for order #12345"
│   ├── Workflow: Verify order → Process refund → Update records → Send receipt
│   ├── Tools Used: Stripe/PayPal API, database, email service
│   ├── Run Behavior: request_confirmation (financial)
│   └── Returns: Refund ID, amount, status, receipt URL
│
└── Calendar & Meeting Management
    ├── Agent: "Schedule demo with lead"
    ├── Workflow: Check availability → Create meeting → Send invites → Add to CRM
    ├── Tools Used: Google Calendar, Zoom, Salesforce
    └── Returns: Meeting link, calendar event, CRM activity logged

🚀 Workflow Tool Best Practices

Design Principles

1. Clear Tool Descriptions

✅ Good Description:
"Use this tool to process customer refunds. Required: order_id,
amount, reason. Validates order exists, checks refund eligibility,
processes refund via payment gateway, sends confirmation email.
Returns refund_id and status. Call when user requests refund or
reports payment issue requiring resolution."

❌ Poor Description:
"Handles refunds"

2. Appropriate Run Behavior Selection

Auto Run For:
✅ Data lookups and queries
✅ Report generation
✅ Status checks
✅ Read-only operations
✅ Internal process automation

Request Confirmation For:
⚠️ Financial transactions
⚠️ Data modifications or deletions
⚠️ External communications
⚠️ Account changes
⚠️ Irreversible operations

3. Optimal Timeout Configuration

Guidelines:
- Quick operations: 15-30 seconds
- Standard workflows: 60-90 seconds
- Complex processes: 120-300 seconds
- Monitor actual execution times and adjust
- Consider adding buffer for external API delays

4. Strategic Input Config Usage

Pre-fill When:
✅ Value is constant (workspace_id, environment settings)
✅ Security constraint must be enforced (max_amount, permissions)
✅ Compliance requirement (audit_enabled, data_retention)
✅ Configuration simplification for agent

Let Agent Decide When:
✅ User-specific data (names, emails, preferences)
✅ Request-specific parameters (quantities, dates)
✅ Dynamic context (search queries, filters)

⚙️ Testing & Validation

Testing Workflow Tools

Pre-Deployment Testing Checklist

- [ ] Tool description clearly explains when to use the tool
- [ ] Agent correctly identifies when to call the tool
- [ ] Required parameters are properly extracted from conversation
- [ ] Input config correctly pre-fills constant values
- [ ] Timeout is appropriate for workflow complexity
- [ ] Run behavior matches risk level (auto vs confirmation)
- [ ] Success responses are properly interpreted by agent
- [ ] Error responses provide actionable feedback
- [ ] Edge cases are handled gracefully
- [ ] Performance meets user expectations

Testing Scenarios

1. Happy Path Test:
   - User provides all required information
   - Workflow executes successfully
   - Agent responds with appropriate confirmation

2. Missing Parameters Test:
   - User provides incomplete information
   - Agent asks clarifying questions
   - Once complete, executes workflow

3. Error Handling Test:
   - Workflow encounters an error (e.g., insufficient inventory)
   - Agent receives error details
   - Agent explains issue and suggests alternatives

4. Timeout Test:
   - Workflow takes longer than expected
   - Agent handles timeout gracefully
   - User is informed and provided options

5. Confirmation Flow Test (if run_behavior = request_confirmation):
   - Agent explains what will happen
   - User approves, denies, or modifies
   - Agent responds appropriately to each choice

🔄 Workflow Execution Flow

When an agent calls a workflow tool, the system follows this execution sequence:

Execution Steps

  1. Parameter Collection: Agent extracts required parameters from conversation context and user input

  2. Input Template Application: Any pre-configured input_config values are merged with agent-provided parameters

  3. Parameter Substitution: Template variables (like {{workspace_id}}) are replaced with actual values

  4. Workflow Run Creation: System creates a workflow run record marked as "triggered_by: agent"

  5. Workflow Execution: Workflow engine processes all nodes in the workflow

  6. Event Callbacks: Each workflow step fires events that are processed and stored

  7. Response Generation: Workflow completes and returns output, status, and any errors

  8. Agent Response: Agent interprets the result and formulates a natural language response

Data Flow Example

Agent Call:
run_workflow_order_processing(
  product_sku="PROD-X",
  quantity=100,
  customer_id="CUST-123"
)

Input Template Applied:
{
  "workspace_id": "abc-workspace-123",  # From input_config
  "product_sku": "PROD-X",              # From agent
  "quantity": 100,                      # From agent
  "customer_id": "CUST-123",            # From agent
  "max_discount": 0.10,                 # From input_config
  "requires_approval": false            # From input_config
}

Workflow Executes:
→ Node 1: Validate inventory (50 units available)
→ Node 2: ERROR - Insufficient stock

Error Response:
{
  "output": null,
  "status": "error",
  "error": {
    "message": "Insufficient inventory for requested quantity",
    "code": "INVENTORY_ERROR",
    "failed_node": "Validate Inventory",
    "node_error": {
      "node_name": "inventory_check",
      "error_message": "Available: 50, Requested: 100",
      "available": 50,
      "requested": 100
    }
  }
}

Agent Interprets & Responds:
"I checked our inventory and we currently have 50 units of Product X
available, but you requested 100 units. Would you like to order the
50 units we have in stock, or wait until we restock?"

🎯 Common Patterns & Examples

Pattern 1: Read-Only Data Query

Workflow Tool: "customer_lookup"
Description: "Fetch customer details by ID, email, or company name"

Configuration:
- run_behavior: "auto_run" (safe read operation)
- timeout: 30 seconds
- input_config:
  {
    "workspace_id": "{{workspace_id}}",
    "include_sensitive_data": false
  }

Agent Usage:
User: "What's the status of customer ABC Corp?"
Agent extracts: company_name="ABC Corp"
Agent calls: customer_lookup(company_name="ABC Corp")
Returns: Customer profile with account status, recent orders
Agent responds: "ABC Corp is an active customer since 2022..."

Pattern 2: Confirmation-Required Action

Workflow Tool: "process_refund"
Description: "Process customer refund for an order"

Configuration:
- run_behavior: "request_confirmation" (financial operation)
- timeout: 90 seconds
- input_config:
  {
    "workspace_id": "{{workspace_id}}",
    "max_refund_amount": 5000,
    "notify_accounting": true
  }

Agent Usage:
User: "I need a refund for order #12345"
Agent analyzes: order_id="12345", validates order exists
Agent proposes:
  "I can process a refund for order #12345 ($1,200).
   This will:
   - Credit the original payment method
   - Send confirmation email
   - Update order status to 'refunded'
   Would you like me to proceed?"
User: "Yes"
Agent calls: process_refund(order_id="12345")
Returns: Refund confirmation with transaction ID

Pattern 3: Multi-Step Process Automation

Workflow Tool: "onboard_customer"
Description: "Complete customer onboarding process"

Configuration:
- run_behavior: "auto_run" (internal process)
- timeout: 120 seconds
- input_config:
  {
    "workspace_id": "{{workspace_id}}",
    "onboarding_template": "enterprise",
    "assign_success_manager": true
  }

Agent Usage:
User: "New customer: Acme Inc, email: [email protected], 500 seats"
Agent extracts:
  company_name="Acme Inc"
  email="[email protected]"
  seat_count=500
Agent calls: onboard_customer(...)
Workflow executes:
  → Create account
  → Provision licenses
  → Send welcome email
  → Assign success manager
  → Schedule kickoff call
Returns: Account details, next steps
Agent responds: "Welcome aboard! I've created your account..."

🔐 Security & Error Handling

Security Considerations

Error Information Disclosure

The workflow tool automatically adjusts error detail based on user authentication:

Authenticated Users (Detailed Errors):
- Full error message and error code
- Failed node name and workflow information
- Node-specific error details
- Helpful for debugging and troubleshooting

Anonymous Users (Generic Errors):
- Generic error message only
- No internal system details exposed
- Prevents information leakage
- Maintains security boundaries

Configuration:
show_detailed_errors = true   # For authenticated users
show_detailed_errors = false  # For anonymous users

Input Validation & Constraints

Security Best Practices:

1. Use input_config to enforce limits:
   {
     "max_amount": 5000,           # Financial limits
     "allowed_actions": ["read"],  # Permission constraints
     "rate_limit": 100             # Quota management
   }

2. Validate workflow input schema:
   - Required parameters are enforced
   - Type validation prevents injection
   - Range checks prevent abuse

3. Workspace isolation:
   - workspace_id automatically injected
   - Users cannot access other workspaces
   - Data segregation enforced

Error Handling Patterns

Transient Errors

Scenario: External API timeout or temporary failure

Workflow Behavior:
- Returns error status with details
- Agent can suggest retry

Agent Response:
"I encountered a temporary issue connecting to the payment
system. Would you like me to try again, or would you prefer
to complete this transaction later?"

Validation Errors

Scenario: User provides invalid input (e.g., negative quantity)

Workflow Behavior:
- Validation node catches error early
- Returns specific validation failure

Agent Response:
"I notice you entered a negative quantity. Please provide
a positive number of units you'd like to order."

Business Logic Errors

Scenario: Business rule violation (e.g., insufficient funds)

Workflow Behavior:
- Business logic node evaluates condition
- Returns actionable error with context

Agent Response:
"Your account has a credit limit of $10,000 and this order
would exceed that limit. Would you like to:
1. Place a smaller order within your limit
2. Contact our sales team to increase your credit limit"

🎯 Workflow Tool Configuration Checklist

Before deploying workflow tools with your agent:

Configuration

Testing

Security

Performance

📚 Additional Resources

Related Documentation

Key Concepts

  • Workflow Input Schema: Defines parameters the workflow accepts

  • Tool Description: Guides agent on when to use the tool

  • Run Behavior: Controls automatic execution vs confirmation requirement

  • Input Config: Pre-fills constant values and enforces constraints

  • Timeout: Maximum execution time before timeout error

💡 Quick Reference

Configuration Schema

{
  "workflow_id": "UUID (required)",
  "description": "string (optional, recommended)",
  "run_behavior": "auto_run | request_confirmation (default: auto_run)",
  "timeout": "number (1-300 seconds, default: 150)",
  "input_config": {
    "param_name": "static_value or {{template_variable}}"
  }
}

Common Configuration Examples

Data Query Tool:

{
  "workflow_id": "customer-lookup-workflow-id",
  "description": "Fetch customer data by ID, email, or company name",
  "run_behavior": "auto_run",
  "timeout": 30,
  "input_config": {
    "workspace_id": "{{workspace_id}}",
    "include_pii": false
  }
}

Financial Transaction Tool:

{
  "workflow_id": "refund-processing-workflow-id",
  "description": "Process customer refund for completed orders",
  "run_behavior": "request_confirmation",
  "timeout": 90,
  "input_config": {
    "workspace_id": "{{workspace_id}}",
    "max_refund_amount": 5000,
    "notify_accounting": true
  }
}

Process Automation Tool:

{
  "workflow_id": "customer-onboarding-workflow-id",
  "description": "Complete new customer onboarding process",
  "run_behavior": "auto_run",
  "timeout": 120,
  "input_config": {
    "workspace_id": "{{workspace_id}}",
    "onboarding_template": "enterprise"
  }
}

Transform your AI agent into a powerful automation orchestrator by connecting conversations directly to workflow execution.

PreviousKnowledge & Data SourcesNextMCP Tools Configuration

Last updated

Was this helpful?