Skip to main content
The Agent Workflow node exposes a downstream workflow as a callable tool for an upstream Agent. When the Agent decides to call it, the node runs its connected workflow nodes and sends a ToolMessage result back to the calling Agent. Use Agent Workflow when a tool result needs multi-step orchestration, such as retrieving data, running logic branches, iterating over records, calling other tools, and formatting a final result. :::note Agent Workflow replaces the legacy Agent Tool workflow node. Existing agent-tool nodes continue to run for compatibility, but new workflows should use agent-workflow. :::

​
How It Works

  1. Tool registration
    • The node is registered as a tool that an upstream Agent can call.
    • Tool Name, Tool Description, and Tool Parameters become the tool name, description, and schema seen by the Agent model.
  2. Argument passing
    • When the Agent calls the tool, the call arguments are stored in the Agent Workflow node state.
    • Each configured input parameter is exposed to downstream workflow nodes as args.<parameterName>.
  3. Sub-workflow execution
    • Connected workflow nodes run as the implementation of the tool.
    • The sub-workflow can include branches, iteration, tool invocation, HTTP requests, code, templates, knowledge retrieval, and Agent nodes.
  4. Return to the caller Agent
    • After the sub-workflow completes, Agent Workflow creates a ToolMessage and writes it back to the calling Agent.
    • The caller Agent then continues reasoning with that tool result.

​
Configuration

​
Return Content

Agent Workflow supports three return modes: When the downstream path ends with an Iteration node, do not rely on Last message. Select the iteration output variable, usually output_str, or add an Answer node after the iteration and return that result. Validation reports an error when an Agent Workflow ends on an iterator path while still using the legacy last-message return mode.

​
Compatibility

  • New nodes use WorkflowNodeTypeEnum.AGENT_WORKFLOW with the value agent-workflow.
  • Legacy nodes with WorkflowNodeTypeEnum.AGENT_TOOL and the value agent-tool are still loaded and executed for existing workflows.
  • The old Agent Tool documentation page is kept only as a deprecated compatibility entry.

​
Best Practices

  1. Give the tool a clear name and description so the Agent model can choose it reliably.
  2. Define explicit input parameters instead of expecting the downstream workflow to infer context.
  3. Prefer Variable or Template return content for production workflows.
  4. Use Last message only for simple legacy-style flows that end with an Answer or Agent response.
  5. For branches, make sure the selected return variable is produced on every possible path, or use a template or Answer node on each branch.