Skip to main content

​
Overview

The Custom Agent Node is a specialized Integration Designer workflow node that enables you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
Custom Agent Node

​
Key features

  • Tool Access: Connect to one or more MCP servers to provide tools to the AI agent
  • Reasoning & Acting: Built-in ReAct (Reasoning and Acting) model for intelligent decision-making
  • Multi-Step Execution: Agent can use multiple tools in sequence to accomplish complex tasks
  • Structured Responses: Define expected response schemas for consistent output
  • Execution Tracking: Monitor tool usage and agent reasoning in console logs
Custom Agent nodes automatically apply the ReAct (Reasoning and Acting) model, which enables the AI agent to think through problems, decide which tools to use, and take actions based on the results.

​
When to use custom agent nodes

Custom Agent nodes are ideal for scenarios where you need:
  • Dynamic Decision Making: The agent determines which tools to use based on the task
  • External System Integration: Access external APIs, databases, or services through MCP tools
  • Complex Multi-Step Operations: Execute workflows that require multiple tool interactions
  • Autonomous Problem Solving: Let the AI agent figure out how to accomplish a goal using available tools

​
Example use cases

Create an agent that can:
  • Look up customer information from a CRM system
  • Check order status from an order management system
  • Generate personalized responses based on the gathered data
  • Create support tickets if needed
Build an agent that:
  • Queries multiple databases for relevant data
  • Performs calculations and aggregations
  • Generates charts and visualizations
  • Produces formatted reports
Design an agent that:
  • Monitors external systems for events
  • Validates data across multiple sources
  • Triggers actions in integrated systems
  • Handles exceptions and error cases
Implement an agent that:
  • Coordinates operations across multiple systems
  • Transforms data between different formats
  • Handles complex business logic
  • Manages transaction workflows

​
Adding a Custom Agent node

To add a Custom Agent node to an Integration Designer workflow:
  1. Open Integration Designer and navigate to your workflow
  2. Click Select Next Node dropdown
  3. Select Custom Agent from the available node types
  4. Configure the node settings
Add Custom Agent
Custom Agent nodes are available in Integration Designer workflows, alongside other node types like REST Endpoint, Script, Condition, and Subworkflow nodes.
The Custom Agent node is specifically designed for Integration Designer workflows. For BPMN process workflows, use the Start Integration Workflow action to invoke workflows that contain Custom Agent nodes.

​
Configuring a Custom Agent node

After adding a Custom Agent node to your Integration Designer workflow, configure it through the node configuration panel:
​
operationPrompt
string
required
The instruction prompt that defines what the AI agent should accomplish.This prompt should clearly describe:
  • The task or goal
  • Any specific requirements or constraints
  • Expected behavior or approach
  • Context from the process data (using placeholders)
Example Prompts:
Retrieve customer information for customer ID ${application.customerId} 
and summarize their recent order history. Include order totals and dates.

Analyze the sales data for Q4 ${application.year} and identify the 
top 5 products by revenue. Calculate the percentage change from Q3.

Check the inventory status for product ${application.productId} 
across all warehouses. If stock is below ${application.minStock}, 
create a reorder request.
​
mcpServers
array
One or more MCP servers whose tools will be available to the AI agent.Configuration:
  • Select from locally defined MCP servers
  • Include MCP servers from dependency libraries
  • Multiple selections allowed
Only enabled tools from the selected MCP servers will be available to the agent. Tools can be managed in the MCP server details page.
​
responseSchema
string
required
JSON Schema defining the expected structure of the agent’s response.This ensures the agent returns data in a consistent, predictable format that can be easily processed by subsequent nodes.Example Schema:
{
  "type": "object",
  "properties": {
    "customerInfo": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "email": { "type": "string" }
      }
    },
    "orderSummary": {
      "type": "object",
      "properties": {
        "totalOrders": { "type": "number" },
        "totalValue": { "type": "number" },
        "recentOrders": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "orderId": { "type": "string" },
              "date": { "type": "string" },
              "total": { "type": "number" }
            }
          }
        }
      }
    }
  },
  "required": ["customerInfo", "orderSummary"]
}
​
responseKey
string
required
The key in the process data where the agent’s response will be stored.Example: agentResponse, customerData, analysisResultsIf the key already exists in the process data, it will be overwritten with the agent’s response.
Custom Agent AI Config

​
How custom agent nodes execute

When a Custom Agent node is executed in an Integration Designer workflow, the following process occurs:
1

Initialization

The FlowX Engine sends the operation prompt and available tools to the AI Service.
2

Reasoning

The AI agent analyzes the prompt and determines which tools it needs to use and in what order.
3

Tool Execution

The agent requests tool execution through the MCP server:
  • Agent provides input parameters based on its reasoning
  • MCP server executes the tool
  • Results are returned to the agent
4

Iteration

The agent evaluates the results and decides whether to:
  • Use additional tools to gather more information
  • Process the data and formulate a response
  • Handle any errors or unexpected results
5

Response Generation

Once the agent has all necessary information, it generates a structured response according to the defined schema.
6

Data Storage

The response is stored in the process data at the specified response key and the workflow continues.
The agent’s reasoning process, tool invocations, and results are all logged in the console for debugging and monitoring purposes.

​
Monitoring agent execution

After running a workflow with a Custom Agent node, you can monitor its execution in the Console Logs:

​
Node logs tab

The Logs tab displays:
  • Execution Status: Success, failure, or in-progress
  • Duration: Time taken to complete the node execution
  • Tool Usage Summary: Quick overview of which tools are used during the execution
  • Standard Output: Agent’s final response
Agent Node Logs

​
Tools tab

The Tools tab is only displayed when MCP tools have been used during execution.
For each tool invocation, you can see:
​
Tool
string
The name of the tool that was invoked.
​
Thoughts
string
The AI agent’s reasoning for using this tool - why it decided this tool was necessary and what it hoped to accomplish.Example: “I need to retrieve the customer’s information from the CRM system to get their contact details and account status.”
​
Input
object
The parameters sent by the AI agent to the MCP tool.Example:
{
  "customerId": "CUST-12345",
  "includeOrders": true
}
​
Output
object
The response received from the MCP tool for the AI agent to interpret.Example:
{
  "customer": {
    "id": "CUST-12345",
    "name": "John Doe",
    "email": "[email protected]",
    "tier": "premium"
  },
  "orders": [
    {
      "orderId": "ORD-001",
      "date": "2025-03-15",
      "total": 299.99
    }
  ]
}
Agent Tools Tab

​
Workflow-level logs

If the Custom Agent node is part of a larger workflow, tool usage information is also displayed at the workflow level:
  1. Navigate to the workflow instance in Console Logs
  2. View the workflow’s Tools tab for an aggregated view of all tool usage
  3. Drill down into specific nodes to see detailed tool execution

​
Best practices

​
Writing effective operation prompts

Be Specific: Clearly define what the agent should accomplish
Good: "Retrieve customer order history for the last 6 months and calculate total spend"
Avoid: "Get customer info"
Provide Context: Include relevant process data using placeholders
"For customer ${application.customerId}, check if they have any pending orders 
from the ${application.orderSystem} system"
Set Expectations: Describe the expected output format
"Return a summary with: customer name, total orders, and average order value"
Handle Edge Cases: Include instructions for error scenarios
"If the customer is not found, return an error message explaining that 
the customer ID is invalid"

​
Selecting MCP servers

Relevance: Only include MCP servers whose tools are relevant to the agent’s task
Minimize Scope: Fewer tools = faster decision-making and more predictable behavior
Tool Availability: Ensure required tools are enabled in the MCP server configuration

​
Defining response schemas

Match Use Case: Design the schema to match downstream data requirements
Required Fields: Mark essential fields as required in the schema
Type Safety: Use appropriate JSON Schema types for validation
Documentation: Add descriptions to schema properties for clarity

​
Troubleshooting

Problem: The agent doesn’t use the tools you expected.Possible Causes:
  • Operation prompt doesn’t clearly indicate the need for specific tools
  • Tools are disabled in the MCP server configuration
  • Agent found an alternative approach
Solutions:
  • Review and refine the operation prompt to be more specific
  • Check MCP server tool status (enabled/disabled)
  • Review agent reasoning in the Tools tab to understand its decision-making
Problem: The agent’s response doesn’t conform to the defined schema.Possible Causes:
  • Schema is too restrictive or doesn’t match the prompt
  • Tools return unexpected data structures
  • Agent encountered errors during execution
Solutions:
  • Verify schema matches what the prompt asks for
  • Test tools independently to verify their outputs
  • Review error logs for execution issues
  • Adjust schema or prompt to align better
Problem: The Custom Agent node takes too long to execute.Possible Causes:
  • Too many MCP servers/tools available
  • Complex multi-step operations
  • External systems responding slowly
Solutions:
  • Limit MCP servers to only those needed
  • Break complex tasks into multiple simpler agent nodes
  • Optimize external system performance
  • Increase timeout configuration if appropriate
Problem: A tool invocation fails during agent execution.Possible Causes:
  • MCP server connection issues
  • Invalid parameters sent by agent
  • Tool authentication or permission errors
Solutions:
  • Test MCP server connection in Integration Designer
  • Review tool input schema and agent’s input in the Tools tab
  • Verify authentication credentials for the MCP server
  • Check tool-specific error messages in console logs

​
Next steps

MCP Integration Overview

Learn about MCP integration capabilities

MCP Data Sources

Add, configure, and manage MCP servers and tools

Integration Designer

Learn about Integration Designer workflows

MCP API Reference

View complete API documentation

Integration Designer Workflows

Learn about other Integration Designer workflow nodes

Start Integration Workflow

Learn how to call Integration Designer workflows from BPMN processes