pluginsplugin-aitool

KestraFlow​Kestra​Flow

Call a Kestra flow as a tool

This tool allows an LLM to call a Kestra flow.

It supports two usage modes:

1. Call a flow explicitly defined in the tool specification In this mode, the AI Agent creates a tool named kestra_flow_<namespace>_<flowId>. Multiple flows can be added as separate tools, and the LLM can choose which one to call. The tool's description comes from the tool's description property or the flow's description. If no description is available, an error will be raised.

2. Call a flow defined in the LLM prompt In this mode, the AI Agent creates a single tool named kestra_flow. The LLM will infer the namespace and flowId parameters from the prompt.

The LLM can also set inputs, labels, and scheduledDate if required. If no correlationId is provided, the called flow will inherit correlationId from the agent's execution.

yaml
type: "io.kestra.plugin.ai.tool.KestraFlow"

Call a Kestra flow as a tool, explicitly defining the flow ID and namespace in the tool definition

yaml
id: agent_calling_flows_explicitly
namespace: company.ai

inputs:
  - id: use_case
    type: SELECT
    description: Your Orchestration Use Case
    defaults: Hello World
    values:
      - Business Automation
      - Business Processes
      - Data Engineering Pipeline
      - Data Warehouse and Analytics
      - Infrastructure Automation
      - Microservices and APIs
      - Hello World

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: Execute a flow that best matches the {{ inputs.use_case }} use case selected by the user
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-2.5-flash
      apiKey: "{{ kv('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: business-automation
        description: Business Automation

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: business-processes
        description: Business Processes

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: data-engineering-pipeline
        description: Data Engineering Pipeline

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: dwh-and-analytics
        description: Data Warehouse and Analytics

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: file-processing
        description: File Processing

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: hello-world
        description: Hello World

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: infrastructure-automation
        description: Infrastructure Automation

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: microservices-and-apis
        description: Microservices and APIs

Call a Kestra flow as a tool, implicitly passing the flow ID and namespace in the prompt

yaml
id: agent_calling_flows_implicitly
namespace: company.ai

inputs:
  - id: use_case
    type: SELECT
    description: Your Orchestration Use Case
    defaults: Hello World
    values:
      - Business Automation
      - Business Processes
      - Data Engineering Pipeline
      - Data Warehouse and Analytics
      - Infrastructure Automation
      - Microservices and APIs
      - Hello World

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: |
      Execute a flow that best matches the {{ inputs.use_case }} use case selected by the user. Use the following mapping of use cases to flow IDs:
      - Business Automation: business-automation
      - Business Processes: business-processes
      - Data Engineering Pipeline: data-engineering-pipeline
      - Data Warehouse and Analytics: dwh-and-analytics
      - Infrastructure Automation: infrastructure-automation
      - Microservices and APIs: microservices-and-apis
      - Hello World: hello-world
      Remember that all those flows are in the tutorial namespace.
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-2.5-flash
      apiKey: "{{ kv('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraFlow
Properties

Description of the flow if not already provided inside the flow itself

Use it only if you define the flow in the tool definition. The LLM needs a tool description to identify whether to call it. If the flow has a description, the tool will use it. Otherwise, the description property must be explicitly defined.

Flow ID of the flow that should be called

Default false

Whether the flow should inherit labels from this execution that triggered it

By default, labels are not inherited. If you set this option to true, the flow execution will inherit all labels from the agent's execution. Any labels passed by the LLM will override those defined here.

Input values that should be passed to flow's execution

Any inputs passed by the LLM will override those defined here.

Labels that should be added to the flow's execution

Any labels passed by the LLM will override those defined here.

Namespace of the flow that should be called

Revision of the flow that should be called

Format date-time

Schedule the flow execution at a later date

If the LLM sets a scheduleDate, it will override the one defined here.