Skip to content

Error handling

The node separates three kinds of failure. Each one reaches the workflow in a different way.

Validation errors

Checked before the agent runs. The node does not execute and FlowDrop reports the errors:

  • Agent ID is required
  • Agent ID '<id>' does not exist
  • Task description is required
  • Chat history item at index <n> must be an array
  • Chat history item at index <n> must have 'role' and 'content' keys

The agent refuses the task

When the agent reports Not Solvable, the node completes normally with:

  • success: false
  • response: the agent's answer, or Task is not solvable
  • error_message: the agent's explanation, or Agent cannot solve this task

The job counts as completed, so the node's error port does not fire. Branch on success to handle it.

Runtime failures

Any exception while building the request or running the agent (provider errors, a missing tool, a failed save) fails the job. The node rethrows it as a RuntimeException with the message AI Agent "<agent_id>" failed: <original message>.

FlowDrop then marks the job as failed. That routes execution to the node's error port when the workflow connects one, and applies the node's retry settings.

flowchart LR
    Run[AI Agent Executor] -->|success: true| Ok[Normal path]
    Run -->|success: false| Refused[Branch on success]
    Run -->|exception| ErrorPort[error port / retries]

Interrupts are not failures. A paused node waits for an answer; see Job status and questions.