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


βš™οΈ 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


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

Writing Effective Tool Descriptions:


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

Handling Timeouts:


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

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

Advanced Input Config Patterns:

When to Use Input Config:


πŸ“Š Workflow Tool Response Format

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

Success Response

Error Response (Detailed)

Error Response (Anonymous Users)

How Agents Handle Responses:


πŸ“Š Workflow Types & Use Cases

🎨 Data Processing Workflows as Tools

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

Configuration Example:

βš™οΈ Business Process Workflows as Tools

Turn complex business processes into agent-callable tools:

πŸ€– Integration Workflows as Tools

Connect external systems and services through workflow tools:


πŸš€ Workflow Tool Best Practices

Design Principles

1. Clear Tool Descriptions

2. Appropriate Run Behavior Selection

3. Optimal Timeout Configuration

4. Strategic Input Config Usage


βš™οΈ Testing & Validation

Testing Workflow Tools

Pre-Deployment Testing Checklist

Testing Scenarios


πŸ”„ 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


🎯 Common Patterns & Examples

Pattern 1: Read-Only Data Query

Pattern 2: Confirmation-Required Action

Pattern 3: Multi-Step Process Automation


πŸ” Security & Error Handling

Security Considerations

Error Information Disclosure

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

Input Validation & Constraints

Error Handling Patterns

Transient Errors

Validation Errors

Business Logic Errors


🎯 Workflow Tool Configuration Checklist

Before deploying workflow tools with your agent:

Configuration

Testing

Security

Performance


πŸ“š Additional Resources

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

Common Configuration Examples

Data Query Tool:

Financial Transaction Tool:

Process Automation Tool:


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

Last updated

Was this helpful?