Skip to content

For developers

The module has a small extension surface. It ships no hooks of its own (no .api.php file) and no plugin types. What other code can build on:

Surface Where Page
FlowDrop node processor ai_agents_executor src/Plugin/FlowDropNodeProcessor/Agents.php This page
JSON endpoints for agents and search indexes src/Controller/Api/AgentApiController.php HTTP API
Editor field widgets for ai_agent_selector and ai_search_index_selector lib/src/ Editor field widgets

The node processor

Drupal\flowdrop_agents\Plugin\FlowDropNodeProcessor\Agents is a final FlowDrop node processor with the ID ai_agents_executor. Node types reference it in executor_plugin as flowdrop_agents:ai_agents_executor, as the shipped node type does.

It implements:

  • ExecutionContextAwareInterface, to receive the execution context.
  • ResumableNodeProcessorInterface. process() runs the agent; resume() runs it again with the person's answer when an interrupt is resolved.

It depends on plugin.manager.ai_agents and ai.provider.

classDiagram
    class AbstractFlowDropNodeProcessor
    class ExecutionContextAwareInterface
    class ResumableNodeProcessorInterface
    class Agents {
      +getParameterSchema()
      +getOutputSchema()
      +validateParams(params)
      +process(params)
      +resume(interrupt, params)
    }
    AbstractFlowDropNodeProcessor <|-- Agents
    ExecutionContextAwareInterface <|.. Agents
    ResumableNodeProcessorInterface <|.. Agents
    Agents --> AiAgentManager
    Agents --> AiProviderPluginManager

Using it from your own node type

The class is final. To expose the executor with different defaults or port flags, add a flowdrop_node_type config entity in your module that points at the same executor plugin:

id: my_module_content_agent
label: 'Content Agent'
description: 'Runs the content agent'
category: agents
icon: 'mdi:robot-outline'
version: '1.0.0'
enabled: true
executor_plugin: 'flowdrop_agents:ai_agents_executor'
parameters:
  agent_id:
    configurable: false
    connectable: false
    required: true
    default: content_creator
  task_description:
    configurable: false
    connectable: true
    required: true
outputs:
  response:
    exposed: true
  success:
    exposed: true

Use config/install/flowdrop_node_type.flowdrop_node_type.flowdrop_agents_ai_agents_executor.yml as the full reference for parameter and output keys.

Behaviour worth knowing

  • Infrastructure failures are thrown as \RuntimeException, so FlowDrop records the job as failed. An agent's own "not solvable" verdict is returned as normal output with success: false.
  • InterruptRequiredException is always rethrown untouched.
  • Chat history roles are allow-listed to user, assistant and tool.
  • tool_usage_limits is merged over the agent's configured limits through AiAgentEntityWrapper::overrideFunctions(); it does not replace them.

Static analysis

phpstan.neon scans the stubs in phpstan-stubs/ for ai, ai_agents, flowdrop and flowdrop_interrupt, so PHPStan runs without those modules' full sources. Keep the stubs in step when you call new methods on those modules.