AI AIAgent

AI AIAgent
Certified
Run an AI agent with tools

Combines a system message, prompt, and optional tools or content retrievers to invoke an LLM and return text/JSON outputs. Content retrievers always run; tools are only called when the model chooses them. maxSequentialToolsInvocations defaults to unlimited; memory keeps prior messages, and outputFiles collects files from the task working directory.

yaml
type: io.kestra.plugin.ai.agent.AIAgent

Examples

Summarize arbitrary text with controllable length and language.

yaml
id: simple_summarizer_agent
namespace: company.ai

inputs:
  - id: summary_length
    displayName: Summary Length
    type: SELECT
    defaults: medium
    values:
      - short
      - medium
      - long

  - id: language
    displayName: Language ISO code
    type: SELECT
    defaults: en
    values:
      - en
      - fr
      - de
      - es
      - it
      - ru
      - ja

  - id: text
    type: STRING
    displayName: Text to summarize
    defaults: |
      Kestra is an open-source orchestration platform that:
      - Allows you to define workflows declaratively in YAML
      - Allows non-developers to automate tasks with a no-code interface
      - Keeps everything versioned and governed, so it stays secure and auditable
      - Extends easily for custom use cases through plugins and custom scripts.

      Kestra follows a "start simple and grow as needed" philosophy. You can schedule a basic workflow in a few minutes, then later add Python scripts, Docker containers, or complicated branching logic if the situation calls for it.

tasks:
  - id: multilingual_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: |
      You are a precise technical assistant.
      Produce a {{ inputs.summary_length }} summary in {{ inputs.language }}.
      Keep it factual, remove fluff, and avoid marketing language.
      If the input is empty or non-text, return a one-sentence explanation.
      Output format:
      - 1-2 sentences for 'short'
      - 2-5 sentences for 'medium'
      - Up to 5 paragraphs for 'long'
    prompt: |
      Summarize the following content: {{ inputs.text }}
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"

  - id: english_brevity
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    prompt: Generate exactly 1 sentence English summary of "{{ outputs.multilingual_agent.textOutput }}"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"

Interact with an MCP Server subprocess running in a Docker container

yaml
id: agent_with_docker_mcp_server_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: What is the current UTC time?

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: "{{ inputs.prompt }}"
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-nano
    tools:
      - type: io.kestra.plugin.ai.tool.DockerMcpClient
        image: mcp/time

Run an AI agent with a memory

yaml
id: agent_with_memory
namespace: company.ai

tasks:
  - id: first_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    memory:
      type: io.kestra.plugin.ai.memory.KestraKVStore
      memoryId: JOHN
      ttl: PT1M
      messages: 5
    prompt: Hi, my name is John and I live in New York!
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    memory:
      type: io.kestra.plugin.ai.memory.KestraKVStore
      memoryId: JOHN
      ttl: PT1M
      messages: 5

  - id: second_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    memory:
      type: io.kestra.plugin.ai.memory.KestraKVStore
      memoryId: JOHN
      ttl: PT1M
      messages: 5
    prompt: What's my name and where do I live?
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    memory:
      type: io.kestra.plugin.ai.memory.KestraKVStore
      memoryId: JOHN
      ttl: PT1M
      messages: 5

Run an AI agent leveraging Tavily Web Search as a content retriever. Note that in contrast to tools, content retrievers are always called to provide context to the prompt, and it's up to the LLM to decide whether to use that retrieved context or not.

yaml
id: agent_with_content_retriever
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: What is the latest Kestra release and what new features does it include? Name at least 3 new features added exactly in this release.

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: "{{ inputs.prompt }}"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"

Run an AI Agent returning a structured output specified in a JSON schema. Note that some providers and models don't support JSON Schema; in those cases, instruct the model to return strict JSON using an inline schema description in the prompt and validate the result downstream.

yaml
id: agent_with_structured_output
namespace: company.ai

inputs:
  - id: customer_ticket
    type: STRING
    defaults: >-
      I can't log into my account. It says my password is wrong, and the reset link never arrives.

tasks:
  - id: support_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: open-mistral-7b

    systemMessage: |
      You are a classifier that returns ONLY valid JSON matching the schema.
      Do not add explanations or extra keys.

    configuration:
      responseFormat:
        type: JSON
        jsonSchema:
          type: object
          required: ["category", "priority"]
          properties:
            category:
              type: string
              enum: ["ACCOUNT", "BILLING", "TECHNICAL", "GENERAL"]
            priority:
              type: string
              enum: ["LOW", "MEDIUM", "HIGH"]

    prompt: |
      Classify the following customer message:
        {{ inputs.customer_ticket }}

Perform market research with an AI Agent using a web search retriever and save the findings as a Markdown report. The retriever gathers up-to-date information, the agent summarizes it, and the filesystem tool writes the result to the task working directory. Mount {{ workingDir }} to a container path (e.g., /tmp) so the generated report file is accessible and can be collected with outputFiles.

yaml
id: market_research_agent
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: |
      Research the latest trends in workflow and data orchestration.
      Use web search to gather current, reliable information from multiple sources.
      Then create a well-structured Markdown report that includes an introduction,
      key trends with short explanations, and a conclusion.
      Save the final report at the path `/tmp/report.md`.

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    prompt: "{{ inputs.prompt }}"
    systemMessage: |
      You are a research assistant that must always follow this process:
      1. Use the TavilyWebSearch content retriever to gather the most relevant and up-to-date information for the user prompt. Do not invent information.
      2. Summarize and structure the findings clearly in Markdown format. Use headings, bullet points, and links when appropriate.
      3. Save the final Markdown report at the path `/tmp/report.md` by using the write_file tool.

      Important rules:
      - Never output raw text in your response. The final result must always be written to `/tmp/report.md`.
      - If no useful results are retrieved, write a short note in `/tmp/report.md` explaining that no information was found.
      - Do not attempt to bypass or ignore the retriever or the filesystem tool.

    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"
        maxResults: 10

    tools:
      - type: io.kestra.plugin.ai.tool.DockerMcpClient
        image: mcp/filesystem
        command: ["/tmp"]
        binds: ["{{ workingDir }}:/tmp"] # mount host_path:container_path to access the generated report
    outputFiles:
      - report.md

Analyze a numeric series with CodeExecution. The agent must call the code tool for all calculations, then explain the results in English.

yaml
id: agent_with_code_execution_stats
namespace: company.ai

inputs:
  - id: series
    type: STRING
    defaults: |
      12, 15, 15, 18, 21, 99, 102, 102, 104

tasks:
  - id: stats_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite

    systemMessage: |
      You are a data analyst.
      Always use the CodeExecution tool for computations.
      Then summarize clearly in English.

    prompt: |
      Here is a numeric series: {{ inputs.series }}
      1) Compute mean, median, min, max, and standard deviation.
      2) Detect outliers using a z-score greater than 2.
      3) Explain the distribution in 5-8 lines.

    tools:
      - type: io.kestra.plugin.ai.tool.CodeExecution
        apiKey: "{{ secret('RAPID_API_KEY') }}"

Generate release notes using Google Custom Web Search as a tool. Unlike content retrievers, tools are called only when the LLM decides it needs fresh context.

yaml
id: agent_with_google_custom_search_release_notes
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: |
      Find the most recent Kestra release and summarize:
      - release date
      - 5 major new features
      - 3 important bug fixes
      Answer in English.

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite

    systemMessage: |
      You are a release-notes assistant.
      If you need up-to-date information, call GoogleCustomWebSearch.
      Summarize sources and avoid hallucinations.

    prompt: "{{ inputs.prompt }}"

    tools:
      - type: io.kestra.plugin.ai.tool.GoogleCustomWebSearch
        apiKey: "{{ secret('GOOGLE_SEARCH_API_KEY') }}"
        csi: "{{ secret('GOOGLE_SEARCH_CSI') }}"

Triage an incident and trigger the right Kestra flow using KestraFlow in implicit mode. The agent infers namespace/flowId from the prompt and executes the flow.

yaml
id: incident_triage_orchestrator
namespace: company.ai

inputs:
  - id: incident
    type: STRING
    defaults: |
      The "billing-prod" SaaS data has been stale for 2 hours.
      We suspect an API extraction failure from an external provider.

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini

    systemMessage: |
      You are an incident triage agent.
      Decide which flow to run to mitigate the issue.
      Use the kestra_flow tool to trigger it with relevant inputs.

    prompt: |
      Incident:
      {{ inputs.incident }}

      You can run the following flows in the "prod.ops" namespace:
      - restart-billing-extract (inputs: service, reason)
      - run-billing-backfill (inputs: service, sinceHours)
      - notify-oncall (inputs: team, severity, message)

      Pick the best flow and execute it using the tool.

    tools:
      - type: io.kestra.plugin.ai.tool.KestraFlow

Route between multiple explicitly-defined Kestra flows. Each flow becomes a separate tool and the LLM selects which one to call.

yaml
id: multi_flow_planner_agent
namespace: company.ai

inputs:
  - id: objective
    type: SELECT
    defaults: ingestion
    values:
      - ingestion
      - cleanup
      - alerting

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite

    prompt: |
      User objective: {{ inputs.objective }}
      Execute the most appropriate flow for this objective.

    tools:
      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: prod.data
        flowId: ingest-daily-snapshots
        description: Daily ingestion of snapshots

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: prod.data
        flowId: purge-stale-partitions
        description: Cleanup of obsolete partitions

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: prod.ops
        flowId: send-severity-alert
        description: Send an on-call alert

Self-healing automation using KestraTask. The agent fills mandatory placeholders ("...") and then runs the task tool.

yaml
id: agent_using_kestra_task_self_healing
namespace: company.ai

inputs:
  - id: error_message
    type: STRING
    defaults: "Disk usage >= 95% on node worker-3"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite

    systemMessage: |
      You are a self-healing automation agent.
      When remediation is needed, call the KestraTask tool.

    prompt: |
      Detected issue: {{ inputs.error_message }}
      1) Propose a safe remediation action.
      2) Execute the corresponding task using the tool.

    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: cleanup
            type: io.kestra.plugin.scripts.shell.Commands
            commands:
              - "..."   # Placeholder: the agent will decide real commands.
            timeout: PT10M

Find places using an MCP SSE client tool. The agent calls the MCP server to retrieve structured results, then ranks them.

yaml
id: agent_with_sse_mcp_places
namespace: company.ai

inputs:
  - id: city
    type: STRING
    defaults: Lyon, France
  - id: cuisine
    type: STRING
    defaults: "bistronomic"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite

    systemMessage: |
      You are a local guide.
      Use the MCP places tool to search restaurants.
      Return a short ranked list with brief reasons.

    prompt: |
      Find 3 {{ inputs.cuisine }} restaurants in {{ inputs.city }}.
      Criteria: rating > 4.5, quiet atmosphere, mid-range budget.
      Provide name, address, and two short reasons for each.

    tools:
      - type: io.kestra.plugin.ai.tool.SseMcpClient
        sseUrl: https://mcp.apify.com/?actors=compass/crawler-google-places
        timeout: PT3M
        headers:
          Authorization: Bearer {{ secret('APIFY_API_TOKEN') }}

Combine TavilyWebSearch and CodeExecution as tools. The agent searches for market data, then computes projections with the code tool.

yaml
id: agent_research_and_validate_forecast
namespace: company.ai

inputs:
  - id: topic
    type: STRING
    defaults: "workflow and data orchestration market"
  - id: year
    type: INT
    defaults: 2028

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite

    systemMessage: |
      You are a market research analyst.
      1) Use TavilyWebSearch to gather current market size and CAGR.
      2) Use CodeExecution to project the market size to the target year.
      3) Summarize in English with sources.

    prompt: |
      Topic: {{ inputs.topic }}
      1) Find credible sources for the current market size and CAGR.
      2) Project the market size for {{ inputs.year }} using the CAGR.
      3) Write a compact report (2 paragraphs) plus a list of sources.

    tools:
      - type: io.kestra.plugin.ai.tool.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"
      - type: io.kestra.plugin.ai.tool.CodeExecution
        apiKey: "{{ secret('RAPID_API_KEY') }}"

    guardrails:
      input:
        - expression: "{{ message.length < 10000 }}"
          message: "Message too long"
      output:
        - expression: "{{ not (response contains 'CONFIDENTIAL') }}"
          message: "Response contains confidential information"

Send agent traces to Langfuse for observability

yaml
id: agent_with_langfuse_observability
namespace: company.ai

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-4o-mini
    systemMessage: You are a helpful assistant.
    prompt: Summarize the latest Kestra release notes.
    tools:
      - type: io.kestra.plugin.ai.tool.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"
    observability:
      type: io.kestra.plugin.ai.domain.LangfuseObservability
      endpoint: "{{ secret('LANGFUSE_ENDPOINT') }}"
      publicKey: "{{ secret('LANGFUSE_PUBLIC_KEY') }}"
      secretKey: "{{ secret('LANGFUSE_SECRET_KEY') }}"
      capturePrompt: true
      captureOutput: true
      captureToolArguments: true
      captureToolResults: true

Properties

prompt *string

Text prompt

Task given to the agent, which drives the whole tool and retrieval loop. No default: this property is required.

provider *

Language model provider

Model provider backing the agent. No default: this property is required.

Definitions

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

Custom base URL overriding the provider's default endpoint. Useful for enterprise gateways, proxies, self-hosted deployments, or test doubles such as WireMock. Defaults to the provider's public endpoint.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Provides Claude chat models only; embeddings and images are unsupported. Enforces Anthropic rules (no seed/responseFormat). Thinking mode requires max_tokens > thinking.budget_tokens; set API key and optional base URL.

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

Maximum number of tokens the model may generate in its response. Not set by default, in which case the Anthropic client default applies. When thinking is enabled, this must be greater than configuration.thinkingBudgetTokens or the task fails.

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

Azure OpenAI API key. Provide either this key or the tenantId/clientId/clientSecret trio for Entra ID authentication; the API key takes precedence when both are set. Store it as a Kestra secret rather than inline.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

Microsoft Entra ID application client secret used for service-principal authentication. Required together with tenantId and clientId when apiKey is not set. Store it as a Kestra secret rather than inline.

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Connects to the Cohere OpenAI-compatible Compatibility API with API key and model name. Supports chat completion (including tool calling) and embeddings. Image generation is not available, and structured output follows Cohere's json_object format rather than OpenAI's strict JSON schema mode.

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

Base URL of the DashScope API. Use https://dashscope.aliyuncs.com/api/v1 for the China (Beijing) region and https://dashscope-intl.aliyuncs.com/api/v1 for the Singapore region. Defaults to the region inferred from the worker's system timezone.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Penalty applied to repeated sequences during generation. Higher values reduce repetition; 1.0 means no penalty. Valid range is (0, +inf). Not set by default, in which case the DashScope default applies.

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Docker Model Runner is built into Docker Desktop and Docker Engine (Linux) and requires no separate setup. It exposes an OpenAI-compatible API and does not require authentication — set apiKey to any non-empty value (the default not-needed works).

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

The default suits a host installation. Most deployments run Kestra in a bridge-networked container, where localhost is the Kestra container itself rather than the Docker Model Runner host — set baseUrl explicitly in that case.

Image generation routes to the Diffusers endpoint (/engines/diffusers/v1) automatically; use a diffuser-capable model such as ai/stable-diffusion. Docker Model Runner does not advertise which models are diffuser-capable and does not reject a chat model, so passing one makes the request hang until it times out. The first image generation also downloads the Diffusers backend, which can take several minutes.

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

Base URL of the Docker Model Runner OpenAI-compatible API. Pick the variant matching where Kestra itself runs: http://model-runner.docker.internal/engines/v1 for Kestra in a container on Docker Desktop, http://172.17.0.1: 12434/engines/v1 for Kestra in a container on Docker Engine (Linux), and the default http://localhost: 12434/engines/v1 for Kestra directly on the host. The model-runner.docker.internal alias exists only inside containers on Docker Desktop.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Tries chat providers in configured order, falling back on connection failures, timeouts, and retriable provider errors such as HTTP 5xx and 429. Each provider attempt receives the full configured timeout independently, so multiple timeouts can make total duration approach N times that timeout, plus overhead; this is not guaranteed because providers differ in how they apply timeouts. It does not fall back on authentication, invalid request, guardrail, tool execution, or JSON/response-processing failures. Image and embedding operations are unsupported.

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Supports Gemini chat and embeddings (image generation is not currently supported). Tools do not support JSON Schema anyOf, and tools cannot be combined with responseFormat; configure either but not both.

Thinking models (e.g. gemini-3.5-flash) attach a thought_signature to every function-call part. This provider automatically captures those signatures (returnThinking defaults to true) and re-attaches them to the conversation history for every follow-up request (sendThinking is always enabled), preventing the 400 INVALID_ARGUMENT – Function call is missing a thought_signature error.

In addition, on Gemini 2.x models thinking is disabled by default (thinkingBudget = 0) to reduce token usage, unless thinkingEnabled: true or thinkingBudgetTokens > 0 is explicitly set. Gemini 3 models cannot have thinking turned off, so no thinking budget is sent for them by default and the model applies its own; set thinkingBudgetTokens to cap it.

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

Google AI Studio API key used to authenticate requests. Store it as a Kestra secret rather than inline. Required unless certificate-based authentication is configured through clientPem, optionally with caPem.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

io.kestra.plugin.ai.provider.GoogleGemini-EmbeddingModelConfiguration

maxRetriesintegerstring

Maximum retries

Number of times a failed embedding request is retried before the task fails. Not set by default, in which case the Gemini client default applies.

outputDimensionalityintegerstring

Output embedding size

Length the embedding vectors are truncated to, which trades a little accuracy for smaller storage. It must match the dimensionality already used in the embedding store. Not set by default (the model's full dimensionality).

taskTypestring

Possible Values

RETRIEVAL_QUERYRETRIEVAL_DOCUMENTSEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGQUESTION_ANSWERINGFACT_VERIFICATION

Embedding task type

Downstream use the embeddings are optimized for, such as RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, SEMANTIC_SIMILARITY or CLASSIFICATION. Use the matching pair at ingestion and query time. Not set by default, in which case the Gemini default applies.

timeoutstring

Request timeout

Maximum time to wait for each embedding request. Not set by default, in which case the Gemini client default applies.

titleMetadataKeystring

Document title metadata key

Metadata key whose value is passed to the model as the document's title, which improves retrieval quality by giving the document context. Not set by default.

modelNamestring

Model name

Use Google Vertex AI models

Calls Vertex AI Gemini chat, embeddings, or images using project, location, and endpoint settings. Authenticates like the GCP plugin: serviceAccount when set, otherwise Application Default Credentials, optionally impersonating impersonatedServiceAccount; ensure response formats are supported by the selected model/region. Tool calls work on Gemini 3 models: the thought_signature returned with each function call is sent back automatically on the following turns. Thinking is left to the model default unless thinkingEnabled or thinkingBudgetTokens is set.

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

Vertex AI API endpoint for image and embedding models, as host: port or a full https:// URL. Not set by default, in which case the endpoint is derived from location (aiplatform.googleapis.com for global). Must not be set for chat models, which always use Gemini.

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

OAuth scopes requested for the credentials. Defaults to https://www.googleapis.com/auth/cloud-platform. Not supported for image models, which always use Application Default Credentials with their default scopes.

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Connects to Langdock's Completion API, which exposes OpenAI/Azure OpenAI-backed models on the OPENAI route and Claude models on the ANTHROPIC route. Set modelFamily to match the modelName you use: Claude models are only reachable when modelFamily is ANTHROPIC. Use the langdock.ListModels task with the matching family to discover valid modelName values.

Embeddings always go through the OpenAI route (only text-embedding-ada-002 is supported there). If your key is refused for embeddings, use a workspace API key with the Embedding API scope. Image generation is not offered by the Completion API.

For a dedicated deployment, set baseUrl to the route root that matches the operation you are using this provider for, e.g. https://acme.langdock.com/api/public/openai/eu/v1 for chat/embeddings on the OpenAI route, or https://acme.langdock.com/api/public/anthropic/eu/v1/ for chat on the Anthropic route; it then takes precedence over region.

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

Langdock Completion API route serving the request: OPENAI for OpenAI and Azure OpenAI-backed models, or ANTHROPIC, which is required to reach Claude models. Defaults to OPENAI. Ignored for embeddings, which always use the OpenAI route.

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Calls Oracle Cloud GenAI chat/embedding models with compartment OCID and region. Auth is handled via OCI SDK provider (config file or instance principals). Ensure the model is permitted in the chosen compartment.

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Runs a BERT-style sentence-embedding model exported to ONNX (for example all-MiniLM, BGE or E5) inside the Kestra worker with ONNX Runtime on CPU: no API key and no model server. Provide the .onnx model file and its Hugging Face tokenizer.json; modelName is only used as a label, and baseUrl, clientPem and caPem are ignored since nothing is called over the network. Embeddings only: chat completion and image generation are not supported. A loaded model stays in the worker's memory and is reused by every task that provides the same model and tokenizer files; it is unloaded after about 10 minutes without use. Each worker keeps at most 2 models loaded between embedding calls (each distinct model, tokenizer and poolingMode combination counts as one): loading another one unloads the least recently used model as soon as no running call uses it, and that model is loaded again on its next use. Administrators can change the limit with the max-loaded-models plugin configuration of io.kestra.plugin.ai.provider.Onnx; set it to at least the number of distinct models used at the same time, otherwise they keep unloading and reloading each other. Models are loaded and unloaded on a single worker thread so that reloading them reuses the same native memory: a worker loads one model at a time, so loading a large model delays the first use of another model, while calls using already loaded models are not affected. On glibc-based workers that also run other plugins allocating native memory from many threads, setting the MALLOC_ARENA_MAX=2 environment variable on the worker further limits native memory growth.

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

URI of the .onnx model file: a namespace file (nsfile:///path), an internal storage file (kestra:///..., e.g. the output of io.kestra.plugin.core.http.Download), or a local file (file:///path, must be allowed by kestra.local-files.allowed-paths).

tokenizerUri*string

Tokenizer file

URI of the Hugging Face tokenizer.json published with the model, using the same schemes as modelUri. A tokenizer from another model fails, or silently produces wrong embeddings when its token ids happen to fit the model's vocabulary.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

How token vectors are combined into one embedding. MEAN suits sentence-transformers models such as all-MiniLM and E5; BGE models expect CLS. A mismatch does not fail but degrades search quality. Defaults to MEAN.

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

assets

Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.

Definitions

io.kestra.core.models.assets.AssetsDeclaration

assetFailureBehaviorstring

Possible Values

IGNOREFAILWARN

Asset failure behavior

Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.

enableAutobooleanstring

Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.

inputsarray

The assets consumed as inputs.

io.kestra.core.models.assets.AssetIdentifier

id*string

Min length1

typestring

outputs

The assets produced as outputs.

io.kestra.plugin.ee.assets.Dataset

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.File

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.Table

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.plugin.ee.assets.VM

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.External

id*string

Min length1

Max length150

type*object

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

io.kestra.core.models.assets.Custom

id*string

Min length1

Max length150

type*string

Min length1

Custom asset type

descriptionstring

displayNamestring

metadataobject

Default{}

namespacestring

Min length1

Max length150

configuration

Default{}

Language model configuration

Chat model settings (temperature, response format, token limits, and so on). Defaults to an empty configuration, so the provider's own defaults apply.

Definitions

io.kestra.plugin.ai.domain.ChatConfiguration

logRequestsbooleanstring

Log LLM requests

If true, the prompts and configuration sent to the LLM are logged at INFO level. Defaults to false.

logResponsesbooleanstring

Log LLM responses

If true, the raw responses returned by the LLM are logged at INFO level. Defaults to false.

maxCumulativeTokensintegerstring

Maximum cumulative tokens

Budget for the total input and output tokens this task's model may consume across all its calls in one task run, including every iteration of the tool loop. Must be at least 1. Not set by default (no limit). The task fails as soon as a response pushes usage over the budget, so that last response is still billed. Nested sub-agents (io.kestra.plugin.ai.tool.AIAgent) and SQL retrievers track their own configuration.maxCumulativeTokens, and the configured model must report token usage.

maxTokenintegerstring

Maximum output tokens

Upper bound on the number of tokens the model may generate in one response, which caps the output length. Not set by default, in which case the provider's own default applies.

promptCachingbooleanstring

Enable prompt caching

If true, ask the provider to cache system messages and tool definitions across requests, which can markedly cut latency and cost when the same system prompt or tool set is reused. Not set by default. Currently honored by Anthropic only; other providers ignore it silently.

responseFormat

Response format

Shape of the model's output: free-form text, or JSON constrained by a schema. Defaults to plain text. Provider support for schema-constrained output varies and may be incompatible with tool use; when a JSON schema is used, the result is returned under the jsonOutput key.

io.kestra.plugin.ai.domain.ChatConfiguration-ResponseFormat

jsonSchemaobject

JSON schema

JSON Schema object describing the expected response structure, written as YAML in a flow. Only allowed when type is JSON. Provider support for strict schema enforcement varies; where it is unsupported, describe the expected shape in the prompt and validate downstream. Not set by default.

jsonSchemaDescriptionstring

Schema description

Natural-language explanation of the schema, which helps the model produce the right fields. Not set by default.

strictJsonbooleanstring

Defaultfalse

Enable strict JSON schema mode

If true, providers that support it enforce the JSON schema strictly instead of treating it as a hint. Only allowed when type is JSON. Defaults to false.

typestring

DefaultTEXT

Possible Values

TEXTJSON

Response format type

How the model returns its output: TEXT for free-form natural language, or JSON for output validated against a JSON schema. Defaults to TEXT.

returnThinkingbooleanstring

Return thinking

If true, the model's reasoning text is parsed out of the response and exposed in the thinking output. It does not trigger thinking by itself. Not set by default, except for Google Gemini, where it defaults to true so that thought_signature values on function-call parts are captured and re-sent on later requests, preventing tool-call failures on native thinking models.

seedintegerstring

Seed

Positive integer seeding the sampler, so that the same seed with identical settings reproduces the same output. Not set by default (non-deterministic generation).

temperaturenumberstring

Temperature

Randomness of the generation, typically between 0.0 and 1.0. Lower values such as 0.2 make outputs focused and repeatable; higher values such as 0.7-1.0 make them more creative and varied. Not set by default, in which case the provider's own default applies.

thinkingBudgetTokensintegerstring

Thinking Token Budget

Maximum number of tokens the model may spend on internal reasoning before producing its final answer. Not set by default. For Google Gemini, when neither this property nor thinkingEnabled is set, Gemini 2.x models get a budget of 0 (thinking disabled), while Gemini 3 and later are sent no budget and apply their own; set this property to cap it on those models.

thinkingEnabledbooleanstring

Enable Thinking

If true, supported models perform internal reasoning steps before answering, which helps on multi-step problems at the cost of extra tokens and latency. Defaults to false. For Google Gemini, when neither this property nor thinkingBudgetTokens is set, Gemini 2.x models get an explicit thinkingBudget of 0 to keep token usage down, while Gemini 3 and later receive no thinking configuration at all, since they reject a zero budget and always think.

topKintegerstring

Top-K

Restricts sampling to the K most likely tokens at each step, typically between 20 and 100. Smaller values reduce randomness, larger values allow more diversity. Not set by default, in which case the provider's own default applies.

topPnumberstring

Top-P (nucleus sampling)

Restricts sampling to the smallest set of tokens whose cumulative probability is at most this value, typically 0.8-0.95. Lower values focus the output, higher values diversify it. Not set by default, in which case the provider's own default applies.

contentRetrievers

Content retrievers

Retrievers whose results are always injected into the agent's context, unlike tools, which the LLM calls only when it decides to. Some sources, such as web search, can act as either. Not set by default.

Definitions

Retrieve context from an embedding store

Builds a content retriever over the configured embedding store using a query embedding from embeddingProvider. Results are filtered by maxResults and minScore (0–1). The store is not mutated; ensure the embedding model dimension matches stored vectors.

Example

Use RAG with AIAgent using an embedding store content retriever. This example ingests documents into a KV embedding store and then uses an AI agent with the EmbeddingStoreRetriever to answer questions grounded in the ingested data.

yaml
id: agent_with_rag
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Paris is the capital of France with a population of over 2.1 million people
      - content: The Eiffel Tower is the most famous landmark in Paris at 330 meters tall

  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.EmbeddingStoreRetriever
        embeddings:
          type: io.kestra.plugin.ai.embeddings.KestraKVStore
        embeddingProvider:
          type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-embedding-001
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
        maxResults: 3
        minScore: 0.0
    prompt: What is the capital of France and how many people live there?

Use multiple embedding stores simultaneously. This demonstrates the power of the content retriever approach - you can retrieve from multiple embedding stores and other sources in a single task.

yaml
id: multi_store_rag
namespace: company.ai

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.EmbeddingStoreRetriever
        embeddings:
          type: io.kestra.plugin.ai.embeddings.Pinecone
          apiKey: "{{ secret('PINECONE_API_KEY') }}"
          index: technical-docs
        embeddingProvider:
          type: io.kestra.plugin.ai.provider.OpenAI
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          modelName: text-embedding-3-small
      - type: io.kestra.plugin.ai.retriever.EmbeddingStoreRetriever
        embeddings:
          type: io.kestra.plugin.ai.embeddings.Qdrant
          host: localhost
          port: 6333
          collectionName: business-docs
        embeddingProvider:
          type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-embedding-001
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
      - type: io.kestra.plugin.ai.retriever.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"
    prompt: What are the latest trends in data orchestration?

embeddingProvider*

Embedding model provider

Model provider used to embed the query before searching the store. It must support embedding generation, and should use the same model that was used at ingestion time. No default: this property is required.

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

io.kestra.plugin.ai.provider.GoogleGemini-EmbeddingModelConfiguration

maxRetriesintegerstring

Maximum retries

Number of times a failed embedding request is retried before the task fails. Not set by default, in which case the Gemini client default applies.

outputDimensionalityintegerstring

Output embedding size

taskTypestring

Possible Values

RETRIEVAL_QUERYRETRIEVAL_DOCUMENTSEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGQUESTION_ANSWERINGFACT_VERIFICATION

Embedding task type

timeoutstring

Request timeout

Maximum time to wait for each embedding request. Not set by default, in which case the Gemini client default applies.

titleMetadataKeystring

Document title metadata key

Metadata key whose value is passed to the model as the document's title, which improves retrieval quality by giving the document context. Not set by default.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

embeddings*

Embedding store

Embedding store queried for content relevant to the user's question. No default: this property is required.

Store embeddings in Chroma

Connects to a Chroma HTTP instance using cosine distance; targets the given collection and drops it when drop=true.

Example

Ingest documents into a Chroma embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Chroma
      baseUrl: http://localhost:8000
      collectionName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

baseUrl*string

Database base URL

Base URL of the Chroma server. No default: this property is required.

collectionName*string

Collection name

Chroma collection that holds the embeddings. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Chromaio.kestra.plugin.langchain4j.embeddings.Chroma

Store embeddings in Elasticsearch

Targets an Elasticsearch 8.15+ cluster using the provided hosts/index; when drop=true the index is deleted. Supports basic auth, custom headers, path prefix, and trust-all TLS for self-signed certs.

Example

Ingest documents into an Elasticsearch embedding store (requires Elasticsearch 8.15+)

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Elasticsearch
      connection:
        hosts:
          - http://localhost:9200
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

connection*

Connection

Elasticsearch connection settings: hosts, authentication, and TLS options. No default: this property is required.

io.kestra.plugin.ai.embeddings.Elasticsearch-ElasticsearchConnection

hosts*array

SubTypestring

Min items1

Elasticsearch HTTP servers

URLs of the Elasticsearch nodes to connect to, each including scheme, host and port. No default: this property is required and must not be empty.

basicAuth

Basic authorization

Username and password used for HTTP basic authentication. Not set by default (anonymous access).

headersarray

SubTypestring

HTTP headers sent with every request

Extra HTTP headers added to each request, each written as a key: value string. Not set by default.

pathPrefixstring

Path prefix for all HTTP requests

Prefix prepended to every request path, so /my/path turns each call into /my/path/ + endpoint. Use it only when Elasticsearch sits behind a proxy that serves it under a base path. Not set by default.

strictDeprecationModebooleanstring

Strict deprecation mode

If true, responses carrying deprecation warnings are treated as failures. Defaults to false.

targetServerVersionintegerstring

Default8

Target Elasticsearch server major version

Major version advertised in the compatible-with media-type headers (Accept and Content-Type). The bundled elasticsearch-java 9.x client would otherwise negotiate compatible-with=9, which Elasticsearch 8 rejects. Use 8 for an Elasticsearch 8 cluster or 9 for Elasticsearch 9. Defaults to 8.

trustAllSslbooleanstring

Trust all SSL CA certificates

If true, accept any TLS certificate presented by the server, which is sometimes needed for self-signed certificates. Defaults to false. WARNING: enabling this disables both certificate chain validation and hostname verification, exposing connections to man-in-the-middle attacks. Prefer supplying a custom CA certificate instead, and use this only in trusted, controlled environments.

indexName*string

Index name

Elasticsearch index that stores the embeddings. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Elasticsearchio.kestra.plugin.langchain4j.embeddings.Elasticsearch

Prototype embeddings in Kestra KV

Stores embeddings in-memory and persists them to Kestra namespace KV on completion. Suitable for small demos; not scalable. drop=true discards any previously saved KV snapshot.

Example

Ingest documents into a KV embedding store.\nWARNING: the KestraKVStore embeddings are for quick prototyping only; since they are stored in a KV store and loaded into memory, this won't scale with large numbers of documents.

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

type*object

Possible Values

io.kestra.plugin.ai.embeddings.KestraKVStoreio.kestra.plugin.langchain4j.embeddings.KestraKVStore

kvNamestring

Default{{ flow.id }}-embedding-store

KV pair name

Key of the Kestra KV pair used to persist the in-memory embedding store between task runs. Defaults to {{ flow.id }}-embedding-store.

Store embeddings in MariaDB

Persists embeddings to a MariaDB table; create/drop behavior is controlled by createTable and drop. Metadata storage mode defaults to COLUMN_PER_KEY (which requires column/index definitions); set COMBINED_JSON to store metadata as a JSON object in a single column. Requires valid JDBC URL and credentials.

Example

Ingest documents into a MariaDB embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.MariaDB
      username: "{{ secret('MARIADB_USERNAME') }}"
      password: "{{ secret('MARIADB_PASSWORD') }}"
      databaseUrl: "{{ secret('MARIADB_DATABASE_URL') }}"
      tableName: embeddings
      fieldName: id
      createTable: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

createTable*booleanstring

Create table if missing

If true, the embeddings table is created when it does not already exist. Defaults to false.

databaseUrl*string

Database URL

JDBC URL of the MariaDB database holding the embeddings. No default: this property is required.

fieldName*string

ID column name

Name of the column used as the unique identifier of each embedding. Defaults to an empty value, which lets the MariaDB store use its own column name.

password*string

Password

Password of the database user. Store it as a Kestra secret rather than inline. No default: this property is required.

tableName*string

Table name

Name of the table where embeddings are stored. No default: this property is required.

type*object

username*string

Username

User connecting to the MariaDB database. No default: this property is required.

columnDefinitionsarray

SubTypestring

Metadata column definitions

SQL column definitions for metadata fields, one per metadata key. Required only when metadataStorageMode is COLUMN_PER_KEY. Not set by default.

indexesarray

SubTypestring

Metadata index definitions

SQL index definitions for the metadata columns. Used only when metadataStorageMode is COLUMN_PER_KEY. Not set by default (no extra index).

metadataStorageModestring

DefaultCOLUMN_PER_KEY

Metadata storage mode

How document metadata is persisted. COLUMN_PER_KEY stores each metadata key in its own column and requires columnDefinitions and indexes; COMBINED_JSON stores all metadata as a single JSON column. Defaults to COLUMN_PER_KEY.

Store embeddings in Milvus

Connects via URI or host/port with token-based auth; creates the target collection if missing. Metric/index/consistency options map to Milvus settings; drop=true clears the collection. Use defaults for host=localhost, port=19530, secure gRPC unless overridden.

Example

Ingest documents into a Milvus embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Milvus
      # Use either `uri` or `host`/`port`:
      # For gRPC (typical): milvus://localhost:19530
      # For HTTP: http://localhost:9091
      uri: "http://localhost:9091"
      token: "{{ secret('MILVUS_TOKEN') }}"
      collectionName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

token*string

Token

Milvus authentication token. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Milvusio.kestra.plugin.langchain4j.embeddings.Milvus

autoFlushOnDeletebooleanstring

Auto flush on delete

Intended to flush the collection after every delete. Note: this property currently has no effect, as it is not passed to the Milvus client when the store is built.

autoFlushOnInsertbooleanstring

Auto flush on insert

If true, flush the collection after every insert so new vectors are immediately searchable. Setting it to false improves ingestion throughput. Defaults to false.

collectionNamestring

Collection name

Collection that stores the embeddings. Not set by default, in which case the Milvus client's own default collection name applies.

consistencyLevelstring

Consistency level

Read/write consistency level applied to the collection: STRONG, BOUNDED, SESSION or EVENTUALLY. Defaults to EVENTUALLY.

databaseNamestring

Database name

Logical Milvus database holding the collection. Not set by default, in which case the server's default database is used.

hoststring

Host

Hostname of the Milvus server, used when uri is not set. Not set by default, in which case the Milvus client's own default applies.

idFieldNamestring

ID field name

Collection field holding the document ID. Not set by default, in which case the collection schema's own field name is used.

indexTypestring

Index type

Vector index built on the collection, such as FLAT, IVF_FLAT, IVF_SQ8, HNSW, DISKANN or AUTOINDEX. The best choice depends on the deployment and dataset size. Defaults to FLAT.

metadataFieldNamestring

Metadata field name

Collection field holding the document metadata. Not set by default, in which case the collection schema's own field name is used.

metricTypestring

Metric type

Similarity metric used to compare vectors: L2, IP, COSINE, HAMMING or JACCARD. It should match the metric the embedding model was trained for. Defaults to COSINE.

passwordstring

Password

Password of the Milvus user. Required only when authentication or TLS is enabled. Store it as a Kestra secret rather than inline. Not set by default.

portintegerstring

Port

Port of the Milvus server, used when uri is not set. Typically 19530 for gRPC or 9091 for HTTP. Not set by default, in which case the Milvus client's own default applies.

retrieveEmbeddingsOnSearchbooleanstring

Retrieve embeddings on search

If true, search results also carry the stored embedding vectors. Defaults to false.

textFieldNamestring

Text field name

Collection field holding the original text segment. Not set by default, in which case the collection schema's own field name is used.

uristring

URI

Full connection URI of the Milvus server, such as milvus://host: 19530 for gRPC or http://host: 9091 for HTTP. Set either this property or host/port, not both. Not set by default.

usernamestring

Username

User authenticating against Milvus. Required only when authentication or TLS is enabled; see https://milvus.io/docs/authenticate.md. Not set by default.

vectorFieldNamestring

Vector field name

Collection field holding the embedding vector. It must match the index definition and the embedding dimensionality. Not set by default, in which case the collection schema's own field name is used.

Store embeddings in MongoDB Atlas

Uses MongoDB Atlas vector search with the provided collection/index; can optionally create the index and wait for readiness (up to 1 minute). Supply scheme/host and credentials; drop=true removes stored vectors.

Example

Ingest documents into a MongoDB Atlas embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.MongoDBAtlas
      scheme: mongodb+srv
      username: "{{ secret('MONGODB_ATLAS_USERNAME') }}"
      password: "{{ secret('MONGODB_ATLAS_PASSWORD') }}"
      host: "{{ secret('MONGODB_ATLAS_HOST') }}"
      database: "{{ secret('MONGODB_ATLAS_DATABASE') }}"
      collectionName: embeddings
      indexName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

collectionName*string

Collection name

Collection that stores the embedding documents. No default: this property is required.

database*string

Database name

Name of the database holding the embeddings collection. No default: this property is required.

host*string

Host

Hostname of the MongoDB cluster, optionally with a port for the mongodb scheme. No default: this property is required.

indexName*string

Index name

Name of the Atlas Vector Search index used to query the collection. No default: this property is required.

scheme*string

Connection scheme

Scheme of the MongoDB connection string: mongodb+srv for Atlas clusters, mongodb for a direct connection. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.MongoDBAtlasio.kestra.plugin.langchain4j.embeddings.MongoDBAtlas

createIndexbooleanstring

Create the index

If true, create the Atlas Vector Search index when it does not already exist. Defaults to false, which assumes the index is provisioned beforehand.

metadataFieldNamesarray

SubTypestring

Metadata field names

Metadata keys to map into the vector search index so they can be filtered on. Not set by default, in which case no metadata index mapping is created.

optionsobject

Connection string options

Extra options appended to the MongoDB connection string as query parameters. Not set by default.

passwordstring

Password

Password of the database user. Store it as a Kestra secret rather than inline. Not set by default; omit it along with username for an unauthenticated connection.

usernamestring

Username

User connecting to the MongoDB Atlas cluster. Not set by default; omit it along with password for an unauthenticated connection.

Store embeddings with pgvector

Uses the PostgreSQL pgvector extension to persist embeddings in the given table. drop=true recreates the table; optional IVF index (useIndex) defaults to false. Ensure pgvector extension is installed and the user can create tables/indexes.

Example

Ingest documents into a PGVector embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.PGVector
      host: localhost
      port: 5432
      user: "{{ secret('POSTGRES_USER') }}"
      password: "{{ secret('POSTGRES_PASSWORD') }}"
      database: postgres
      table: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

database*string

Database name

Name of the PostgreSQL database holding the embeddings table. No default: this property is required.

host*string

Database server host

Hostname or IP address of the PostgreSQL server running the pgvector extension. No default: this property is required.

password*string

Database password

Password of the database user. Store it as a Kestra secret rather than inline. No default: this property is required.

port*integerstring

Database server port

TCP port the PostgreSQL server listens on. No default: this property is required.

table*string

Table name

Table that stores the embeddings. No default: this property is required. When drop is requested by the ingestion task, the table is recreated.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.PGVectorio.kestra.plugin.langchain4j.embeddings.PGVector

user*string

Database user

User connecting to the PostgreSQL database. No default: this property is required.

useIndexbooleanstring

Defaultfalse

Use an IVFFlat index

If true, build an IVFFlat index on the embedding column. IVFFlat divides vectors into lists and searches only the lists closest to the query vector: it builds faster and uses less memory than HNSW, at the cost of a worse speed-recall tradeoff. Defaults to false.

Store embeddings in Pinecone

Creates or connects to a serverless Pinecone index in the given cloud/region; namespace defaults to Pinecone’s default. Requires an API key; drop=true clears the index contents.

Example

Ingest documents into a Pinecone embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Pinecone
      apiKey: "{{ secret('PINECONE_API_KEY') }}"
      cloud: AWS
      region: us-east-1
      index: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

apiKey*string

API Key

Pinecone API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

cloud*string

Cloud provider

Cloud provider hosting the Pinecone serverless index. No default: this property is required.

index*string

Index name

Pinecone index that stores the embeddings. It is created as a serverless index if it does not exist. No default: this property is required.

region*string

Cloud provider region

Region of the cloud provider hosting the serverless index. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Pineconeio.kestra.plugin.langchain4j.embeddings.Pinecone

namespacestring

Namespace

Namespace that partitions vectors inside the index. Not set by default, in which case Pinecone's default namespace is used.

Store embeddings in Qdrant

Uses the Qdrant gRPC client with API key, host, and port. Targets the specified collection; drop=true removes its contents. Distance metric follows the Qdrant collection defaults.

Example

Ingest documents into a Qdrant embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Qdrant
      apiKey: "{{ secret('QDRANT_API_KEY') }}"
      host: localhost
      port: 6334
      collectionName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

apiKey*string

API Key

Qdrant API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

collectionName*string

Collection name

Qdrant collection that holds the embeddings. No default: this property is required.

host*string

Database server host

Hostname or IP address of the Qdrant server. No default: this property is required.

port*integerstring

Database server port

gRPC port the Qdrant server listens on. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Qdrantio.kestra.plugin.langchain4j.embeddings.Qdrant

Store embeddings in Redis

Backs an embedding index with Redis (jedis). Uses indexName (defaults to embedding-index); drop=true clears stored vectors. Ensure Redis deployment supports vector search modules for production use.

Example

Ingest documents into a Redis embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Redis
      host: localhost
      port: 6379
      indexName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

host*string

Database server host

Hostname or IP address of the Redis server (Redis Stack, with the search module enabled). No default: this property is required.

port*integerstring

Database server port

TCP port the Redis server listens on. No default: this property is required.

type*object

indexNamestring

Defaultembedding-index

Index name

Name of the Redis search index that stores the embeddings. Defaults to embedding-index.

Store embeddings in Alibaba Tablestore

Connects to Tablestore using access keys and writes embeddings with cosine distance. Uses the configured instance/endpoint; metadata schemas are optional. drop=true is not supported—manage cleanup in Tablestore.

Example

Ingest documents into a Tablestore embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Tablestore
      endpoint:  "{{ secret('TABLESTORE_ENDPOINT') }}"
      instanceName:  "{{ secret('TABLESTORE_INSTANCE_NAME') }}"
      accessKeyId:  "{{ secret('TABLESTORE_ACCESS_KEY_ID') }}"
      accessKeySecret:  "{{ secret('TABLESTORE_ACCESS_KEY_SECRET') }}"
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

accessKeyId*string

Access Key ID

Alibaba Cloud access key ID used to authenticate against Tablestore. Store it as a Kestra secret rather than inline. No default: this property is required.

accessKeySecret*string

Access Key Secret

Alibaba Cloud access key secret paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

endpoint*string

Endpoint URL

Base URL of the Tablestore instance endpoint. No default: this property is required.

instanceName*string

Instance name

Name of the Tablestore instance holding the embeddings. No default: this property is required.

type*object

metadataSchemaListarray

Metadata schema list

Tablestore field schemas describing the metadata columns to index, so they can be filtered on at search time. Not set by default (no metadata indexed).

com.alicloud.openservices.tablestore.model.search.FieldSchema

analyzerstring

Possible Values

SingleWordMaxWordMinWordSplitFuzzy

analyzerParameter

dateFormatsarray

SubTypestring

enableHighlightingboolean

enableSortAndAggboolean

fieldNamestring

fieldTypestring

Possible Values

LONGDOUBLEBOOLEANKEYWORDTEXTNESTEDGEO_POINTDATEVECTORFUZZY_KEYWORDIPJSONFLATTENEDUNKNOWN

indexboolean

indexOptionsstring

Possible Values

DOCSFREQSPOSITIONSOFFSETS

isArrayboolean

jsonTypestring

Possible Values

FLATTENNESTEDOBJECT

sourceFieldNamesarray

SubTypestring

storeboolean

subFieldSchemasarray

vectorOptions

Store embeddings in Weaviate

Connects to a Weaviate cluster (HTTP + optional gRPC) using the given host/scheme. apiKey, host, port, and objectClass are required. Defaults: scheme "https", avoidDups true, consistency QUORUM, secured gRPC true. drop=true clears the class contents.

Example

Ingest documents into a Weaviate embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Weaviate
      apiKey: "{{ secret('WEAVIATE_API_KEY') }}"
      scheme: https                                 # http | https (defaults to https)
      host: your-cluster-id.weaviate.network        # no protocol
      port: 443                                     # required (e.g. 443 for https, 80 for http)
      objectClass: Documents                        # required; must start with an uppercase letter
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

apiKey*string

API key

Weaviate API key used to authenticate against the cluster. Store it as a Kestra secret rather than inline. No default: this property is required.

host*string

Host

Cluster hostname, without protocol or port. No default: this property is required.

objectClass*string

Object class

Weaviate class that stores the embedded objects. It must start with an uppercase letter. No default: this property is required.

port*integerstring

Port

Port of the Weaviate HTTP endpoint, typically 443 for https and 80 or 8080 for http. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Weaviateio.kestra.plugin.langchain4j.embeddings.Weaviate

avoidDupsbooleanstring

Avoid duplicates

If true, each object ID is derived from a hash of its text segment, so re-ingesting the same text overwrites the existing object instead of duplicating it. If false, a random ID is assigned. Defaults to true.

consistencyLevelstring

Possible Values

ONEQUORUMALL

Consistency level

Write consistency applied to each object: ONE, QUORUM or ALL. Defaults to QUORUM.

grpcPortintegerstring

gRPC port

Port of the Weaviate gRPC endpoint. Required when useGrpcForInserts is true. Not set by default.

metadataFieldNamestring

Metadata field name

Property used to store document metadata on the object. Not set by default, in which case the Weaviate client's own default field name applies.

metadataKeysarray

SubTypestring

Metadata keys

Metadata keys to persist alongside each object. Defaults to an empty list, meaning no metadata is stored.

schemestring

Scheme

Protocol used to reach the cluster: https (recommended) or http. Defaults to https.

securedGrpcbooleanstring

Secure gRPC

Whether the gRPC connection uses TLS. Defaults to true. Only relevant when useGrpcForInserts is true.

useGrpcForInsertsbooleanstring

Use gRPC for batch inserts

If true, batch inserts go over gRPC, which is faster for large ingestions; searches still use HTTP. Requires grpcPort. Defaults to false.

type*object

maxResultsintegerstring

Default3

Maximum results

Number of matching segments returned by the embedding store for each query. Defaults to 3.

minScorenumberstring

Default0.0

Minimum similarity score

Similarity threshold a match must reach to be returned, from 0.0 (keep everything) to 1.0 (exact match only). Defaults to 0.0.

Retrieve web results with Google Custom Search

Uses Google Custom Search (CSE) to fetch web snippets for RAG. Requires API key and CSE ID (csi/cx); maxResults limits returned items (default 3). Requests consume CSE quota.

Example

RAG chat with a web search content retriever (answers grounded in search results)

yaml
id: rag
namespace: company.ai

tasks:
  - id: chat_with_rag_and_websearch_content_retriever
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.GoogleCustomWebSearch
        apiKey: "{{ secret('GOOGLE_SEARCH_API_KEY') }}"
        csi: "{{ secret('GOOGLE_SEARCH_CSI') }}"
    prompt: What is the latest release of Kestra?

apiKey*string

API key

Google Custom Search JSON API key. Store it as a Kestra secret rather than inline. No default: this property is required.

csi*string

Custom Search Engine ID

Identifier of the Programmable Search Engine to query, referred to as cx in Google's documentation. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.retriever.GoogleCustomWebSearchio.kestra.plugin.langchain4j.retriever.GoogleCustomWebSearch

maxResultsintegerstring

Default3

Maximum results

Number of search results retrieved for each query. Defaults to 3.

Retrieve context from SQL (experimental)

Uses LangChain4j’s experimental SqlDatabaseContentRetriever to translate questions into SQL and return rows as context. Requires a read-only JDBC user; supports PostgreSQL/MySQL/H2 with auto driver selection. A new connection is opened for each query and closed right after it.

Example

RAG chat with a SQL Database content retriever (answers grounded in database data)

yaml
id: rag
namespace: company.ai

tasks:
  - id: chat_with_rag_and_sql_retriever
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.SqlDatabaseRetriever
        databaseType: POSTGRESQL
        jdbcUrl: "jdbc:postgresql://localhost:5432/mydb"
        username: "{{ secret('DB_USER') }}"
        password: "{{ secret('DB_PASSWORD') }}"
    prompt: "What are the top 5 customers by revenue?"

databaseType*object

password*string

Database password

Password of the database user. Store it as a Kestra secret rather than inline. No default: this property is required.

provider*

Language model provider

Model provider used to translate the natural-language question into SQL. No default: this property is required.

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

io.kestra.plugin.ai.provider.GoogleGemini-EmbeddingModelConfiguration

maxRetriesintegerstring

Maximum retries

Number of times a failed embedding request is retried before the task fails. Not set by default, in which case the Gemini client default applies.

outputDimensionalityintegerstring

Output embedding size

taskTypestring

Possible Values

RETRIEVAL_QUERYRETRIEVAL_DOCUMENTSEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGQUESTION_ANSWERINGFACT_VERIFICATION

Embedding task type

timeoutstring

Request timeout

Maximum time to wait for each embedding request. Not set by default, in which case the Gemini client default applies.

titleMetadataKeystring

Document title metadata key

Metadata key whose value is passed to the model as the document's title, which improves retrieval quality by giving the document context. Not set by default.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

type*object

username*string

Database username

User connecting to the database. Grant it read-only access, since the model generates the SQL that is executed. No default: this property is required.

configuration

Default{}

Language model configuration

Chat model settings (temperature, response format, token limits, and so on) applied to the SQL-generating model. Defaults to an empty configuration, so the provider's own defaults apply.

io.kestra.plugin.ai.domain.ChatConfiguration

logRequestsbooleanstring

Log LLM requests

If true, the prompts and configuration sent to the LLM are logged at INFO level. Defaults to false.

logResponsesbooleanstring

Log LLM responses

If true, the raw responses returned by the LLM are logged at INFO level. Defaults to false.

maxCumulativeTokensintegerstring

Maximum cumulative tokens

maxTokenintegerstring

Maximum output tokens

Upper bound on the number of tokens the model may generate in one response, which caps the output length. Not set by default, in which case the provider's own default applies.

promptCachingbooleanstring

Enable prompt caching

responseFormat

Response format

io.kestra.plugin.ai.domain.ChatConfiguration-ResponseFormat

jsonSchemaobject

JSON schema

jsonSchemaDescriptionstring

Schema description

Natural-language explanation of the schema, which helps the model produce the right fields. Not set by default.

strictJsonbooleanstring

Defaultfalse

Enable strict JSON schema mode

If true, providers that support it enforce the JSON schema strictly instead of treating it as a hint. Only allowed when type is JSON. Defaults to false.

typestring

DefaultTEXT

Possible Values

TEXTJSON

Response format type

How the model returns its output: TEXT for free-form natural language, or JSON for output validated against a JSON schema. Defaults to TEXT.

returnThinkingbooleanstring

Return thinking

seedintegerstring

Seed

Positive integer seeding the sampler, so that the same seed with identical settings reproduces the same output. Not set by default (non-deterministic generation).

temperaturenumberstring

Temperature

thinkingBudgetTokensintegerstring

Thinking Token Budget

thinkingEnabledbooleanstring

Enable Thinking

topKintegerstring

Top-K

topPnumberstring

Top-P (nucleus sampling)

driverstring

JDBC driver class name

Fully qualified JDBC driver class, which must be on the classpath. Not set by default, in which case it is derived from databaseType: org.postgresql.Driver, com.mysql.cj.jdbc.Driver or org.h2.Driver.

jdbcUrlstring

JDBC URL

JDBC connection URL of the database the model queries. It must be set for the retriever to connect, even though it is not enforced by validation. Each query opens its own connection, so the connect timeout is the driver's: PostgreSQL gives up after 10 seconds by default, while other drivers may wait for the OS TCP timeout unless the URL sets one (for example connectTimeout=30000 for MySQL, in milliseconds). No default.

maxPoolSizeintegerstring

Maximum connection pool size (deprecated)

Deprecated and ignored: no pool is used, a connection is opened for each query and closed right after it.

Retrieve web results with Tavily

Uses Tavily Search to fetch live web context for RAG. Requires API key; maxResults caps returned snippets and defaults to 3. Requests count against Tavily quotas.

Example

Chat with your data using Retrieval Augmented Generation (RAG) and a WebSearch content retriever. The Chat with RAG retrieves contents from a WebSearch client and provides a response grounded in data rather than hallucinating.

yaml
id: rag
namespace: company.ai

tasks:
  - id: chat_with_rag_and_websearch_content_retriever
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"
    prompt: What is the latest release of Kestra?

apiKey*string

API Key

Tavily API key used to authenticate search requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.retriever.TavilyWebSearchio.kestra.plugin.langchain4j.retriever.TavilyWebSearch

maxResultsintegerstring

Default3

Maximum results

Number of search results retrieved for each query. Defaults to 3.

guardrails

Guardrails

Rules validating the call: input guardrails run against the user prompt before the LLM is called, output guardrails against the response before it is returned. The first failing rule stops execution and sets guardrailViolated to true in the output. Not set by default.

Definitions

io.kestra.plugin.ai.domain.Guardrails

inputarray

Input guardrails

Rules evaluated against the user message before it reaches the LLM. Each rule's Pebble expression can read the message variable holding the user message text. The first failing rule halts execution and reports a guardrail violation in the task output. Not set by default.

io.kestra.plugin.ai.domain.GuardrailRule

expression*string

Min length1

Pebble expression

Condition that must evaluate to true for the guardrail to pass. Input guardrails can read message (the user message text); output guardrails can read response (the AI response text), finishReason, inputTokenCount and outputTokenCount. No default: this property is required and must not be blank.

message*string

Min length1

Violation message

Text reported in the task output when the expression evaluates to false. No default: this property is required and must not be blank.

outputarray

Output guardrails

Rules evaluated against the AI response before it is returned. Each rule's Pebble expression can read response (the response text), finishReason, inputTokenCount and outputTokenCount. The first failing rule halts execution and reports a guardrail violation in the task output. Not set by default.

io.kestra.plugin.ai.domain.GuardrailRule

expression*string

Min length1

Pebble expression

message*string

Min length1

Violation message

Text reported in the task output when the expression evaluates to false. No default: this property is required and must not be blank.

maxSequentialToolsInvocations integerstring

Maximum sequential tool invocations

Cap on how many tool calls the agent may chain within one run, which guards against runaway tool loops. Defaults to no limit.

memory

Agent memory

Store that persists the conversation and replays it as history into the LLM context on subsequent runs, so follow-up prompts keep their context. Not set by default (each run starts fresh).

Definitions

Persist chat memory in Kestra KV

Caches chat messages in-memory and saves them to a namespace KV entry keyed by memoryId; TTL sets KV expiry, but some backends may ignore it. drop=AFTER_TASKRUN deletes the KV after use.

Example

Store chat memory inside a KV pair

yaml
id: chat_with_memory
namespace: company.ai

inputs:
  - id: first
    type: STRING
    defaults: Hello, my name is John and I'm from Paris
  - id: second
    type: STRING
    defaults: What's my name and where am I from?

tasks:
  - id: first
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddingProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    memory:
      type: io.kestra.plugin.ai.memory.KestraKVStore
    systemMessage: You are a helpful assistant, answer concisely
    prompt: "{{ inputs.first }}"

  - id: second
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddingProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    memory:
      type: io.kestra.plugin.ai.memory.KestraKVStore
      drop: AFTER_TASKRUN
    systemMessage: You are a helpful assistant, answer concisely
    prompt: "{{ inputs.second }}"

type*object

Possible Values

io.kestra.plugin.ai.memory.KestraKVStoreio.kestra.plugin.ai.memory.KestraKVMemoryio.kestra.plugin.langchain4j.memory.KestraKVMemory

dropstring

DefaultNEVER

Possible Values

NEVERBEFORE_TASKRUNAFTER_TASKRUN

When to drop the memory

Controls when the stored conversation is erased, rather than waiting for ttl to expire. NEVER (default) keeps it until expiry, BEFORE_TASKRUN clears it before the task runs, and AFTER_TASKRUN clears it once the task run completes.

memoryIdstring

Default{{ labels.system.correlationId }}

Memory ID

Identifier under which the conversation is stored, so that different runs or users can keep separate histories. Defaults to the system.correlationId label, which makes one memory span an entire flow execution including its subflows.

messagesintegerstring

Default10

Maximum messages in memory

Number of chat messages retained in memory. When the limit is reached, the oldest messages are evicted first (FIFO); the last system message is always kept. Defaults to 10.

ttlstring

DefaultPT1H

Memory duration

How long the memory is retained before it expires. Defaults to PT1H (one hour).

Persist chat memory in PostgreSQL

Stores chat history in a PostgreSQL table keyed by memory_id; TTL sets an expires_at timestamp. Honors drop policies BEFORE_TASKRUN/AFTER_TASKRUN; defaults to NEVER (memory is retained). Table is created if missing. Requires reachable Postgres with permissions to create tables.

Example

Use PostgreSQL-based chat memory for a conversation

yaml
id: chat_with_memory
namespace: company.ai

tasks:
  - id: first
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    memory:
      type: io.kestra.plugin.ai.memory.PostgreSQL
      host: localhost
      port: 5432
      database: ai_memory
      user: postgres
      password: secret
      tableName: my_custom_memory_table
    systemMessage: You are a helpful assistant, answer concisely
    prompt: "{{ inputs.first }}"

database*string

Database name

Name of the PostgreSQL database holding the chat memory table. No default: this property is required.

host*string

PostgreSQL host

Hostname or IP address of the PostgreSQL server storing the chat memory. No default: this property is required.

password*string

Database password

Password of the database user. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

user*string

Database user

User connecting to the PostgreSQL database. No default: this property is required.

dropstring

DefaultNEVER

Possible Values

NEVERBEFORE_TASKRUNAFTER_TASKRUN

When to drop the memory

memoryIdstring

Default{{ labels.system.correlationId }}

Memory ID

messagesintegerstring

Default10

Maximum messages in memory

Number of chat messages retained in memory. When the limit is reached, the oldest messages are evicted first (FIFO); the last system message is always kept. Defaults to 10.

portintegerstring

Default5432

PostgreSQL port

TCP port the PostgreSQL server listens on. Defaults to 5432.

tableNamestring

Defaultchat_memory

Table name

Table used to persist the chat memory, created with CREATE TABLE IF NOT EXISTS on first use. Must match ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$, or the task fails before connecting; this is enforced to prevent SQL injection, since the name is interpolated into the statements. Defaults to chat_memory.

ttlstring

DefaultPT1H

Memory duration

How long the memory is retained before it expires. Defaults to PT1H (one hour).

Persist chat memory in Redis

Stores chat history in Redis under memoryId with TTL-based expiry. Supports drop policies BEFORE_TASKRUN/AFTER_TASKRUN; defaults to NEVER (memory is retained). Ensure Redis is reachable; no TLS/auth fields are defined here.

Example

Use Redis-based chat memory for a conversation

yaml
id: chat_with_memory
namespace: company.ai

inputs:
  - id: first
    type: STRING
    defaults: Hello, my name is John and I'm from Paris
  - id: second
    type: STRING
    defaults: What's my name and where am I from?

tasks:
  - id: first
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddingProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    memory:
      type: io.kestra.plugin.ai.memory.Redis
      host: localhost
      port: 6379
    systemMessage: You are a helpful assistant, answer concisely
    prompt: "{{ inputs.first }}"

  - id: second
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddingProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    memory:
      type: io.kestra.plugin.ai.memory.Redis
      host: localhost
      port: 6379
      drop: AFTER_TASKRUN
    systemMessage: You are a helpful assistant, answer concisely
    prompt: "{{ inputs.second }}"

host*string

Redis host

Hostname or IP address of the Redis server storing the chat memory. No default: this property is required.

type*object

dropstring

DefaultNEVER

Possible Values

NEVERBEFORE_TASKRUNAFTER_TASKRUN

When to drop the memory

memoryIdstring

Default{{ labels.system.correlationId }}

Memory ID

messagesintegerstring

Default10

Maximum messages in memory

Number of chat messages retained in memory. When the limit is reached, the oldest messages are evicted first (FIFO); the last system message is always kept. Defaults to 10.

portintegerstring

Default6379

Redis port

TCP port the Redis server listens on. Defaults to 6379.

ttlstring

DefaultPT1H

Memory duration

How long the memory is retained before it expires. Defaults to PT1H (one hour).

observability

Observability

OpenTelemetry export of the agent's model calls. Disabled by default, and capturing prompts, outputs and tool payloads is opt-in on top of enabling it.

Definitions

Langfuse observability

OpenTelemetry export settings for Langfuse. Payload capture is disabled by default for security.

type*object

captureOutputbooleanstring

Capture output

If true, model output is exported under the span's output attributes. Defaults to false, since responses may carry sensitive data.

capturePromptbooleanstring

Capture prompt

If true, prompt content is exported under the span's input attributes. Defaults to false, since prompts may carry sensitive data.

captureSystemMessagebooleanstring

Capture system message

If true, the system message is exported in the span metadata. Defaults to false.

captureToolArgumentsbooleanstring

Capture tool arguments

If true, the arguments passed to each tool are exported in tool execution events. Defaults to false.

captureToolResultsbooleanstring

Capture tool results

If true, the value each tool returned is exported in tool execution events. Defaults to false.

endpointstring

Langfuse OTLP endpoint

OTLP endpoint traces are exported to, which differs per Langfuse region or self-hosted install. Not set by default, in which case nothing is exported.

environmentstring

Environment

Deployment environment tagged on the exported traces, so production and staging traffic can be told apart. Not set by default.

exportTimeoutstring

Export timeout

Time allowed for the OpenTelemetry exporter's flush and shutdown operations before giving up. Defaults to PT5S; a zero or negative value falls back to that default.

maxPayloadCharsintegerstring

Maximum payload characters

Length cap applied to every captured payload field, beyond which the value is truncated. Defaults to 2000; a value of 0 or less falls back to that default.

publicKeystring

Langfuse public key

Public half of the Langfuse API key pair, sent as the basic-auth username. No default: required for export to work.

releasestring

Release

Application version or release tagged on the exported traces, which helps correlate behavior changes with deployments. Not set by default.

secretKeystring

Langfuse secret key

Secret half of the Langfuse API key pair, sent as the basic-auth password. Store it as a Kestra secret rather than inline. No default: required for export to work.

serviceNamestring

Service name

Value reported as the OpenTelemetry service.name resource attribute, used to group traces in the observability backend. Defaults to kestra-plugin-ai.

outputFiles array

SubTypestring

The files from the local filesystem to send to Kestra's internal storage.

Must be a list of glob expressions relative to the current working directory, some examples: my-dir/**, my-dir/*/** or my-dir/my-file.txt.

systemMessage string

System message

Instructions prepended to the conversation, defining the agent's role, tone and constraints. Not set by default.

tools

Tools

Tools the agent may call to augment its answer, invoked only when the LLM decides to. Not set by default (no tools).

Definitions

Invoke remote AI agent over A2A

Forwards prompts to a remote AI Agent using the A2A protocol and returns its response. Provide a meaningful name and description so the parent agent can choose the tool; the name defaults to tool. Requires serverUrl to reach the remote agent.

Example

Call a remote AI agent via the A2A protocol.

yaml
id: a2a_remote_agent_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: |
      Each flow can produce outputs that can be consumed by other flows. This is a list property, so that your flow can produce as many outputs as you need.
      Each output needs to have an ID (the name of the output), a type (the same types you know from inputs, e.g., STRING, URI, or JSON), and a value, which is the actual output value that will be stored in internal storage and passed to other flows when needed.
tasks:
  - id: ai-agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: Summarize the user message, then translate it into French using the provided tool.
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.A2AClient
        description: Translation expert
        serverUrl: "http://localhost:10000"

description*string

Agent description

Natural-language summary of what the remote agent does, used by the LLM to decide when to call it. No default: this property is required.

serverUrl*string

Server URL

Base URL of the remote agent's A2A server. No default: this property is required.

type*object

namestring

Defaulttool

Agent name

Name the LLM sees for this tool. Defaults to tool, so it must be set to a distinct value when several agents are used as tools in the same task.

Expose a nested AI Agent as a tool

Wraps another AI Agent so the parent agent can invoke it as a tool. Provide a unique name and description per tool; the name defaults to tool. Content retrievers configured here always run, while other tools are invoked only when the LLM selects them.

Example

Call an AI agent as a tool

yaml
id: ai-agent-with-agent-tools
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: |
      Each flow can produce outputs that can be consumed by other flows. This is a list property, so that your flow can produce as many outputs as you need.
      Each output needs to have an ID (the name of the output), a type (the same types you know from inputs, e.g., STRING, URI, or JSON), and a value, which is the actual output value that will be stored in internal storage and passed to other flows when needed.
tasks:
  - id: ai-agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: Summarize the user message, then translate it into French using the provided tool.
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.AIAgent
        description: Translation expert
        systemMessage: You are an expert in translating text between multiple languages
        provider:
          type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-3.5-flash-lite
          apiKey: "{{ secret('GEMINI_API_KEY') }}"

description*string

Agent description

Natural-language summary of what the sub-agent does, used by the LLM to decide when to call it. No default: this property is required.

provider*

Language model provider

Model provider backing this sub-agent. No default: this property is required.

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

io.kestra.plugin.ai.provider.GoogleGemini-EmbeddingModelConfiguration

maxRetriesintegerstring

Maximum retries

Number of times a failed embedding request is retried before the task fails. Not set by default, in which case the Gemini client default applies.

outputDimensionalityintegerstring

Output embedding size

taskTypestring

Possible Values

RETRIEVAL_QUERYRETRIEVAL_DOCUMENTSEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGQUESTION_ANSWERINGFACT_VERIFICATION

Embedding task type

timeoutstring

Request timeout

Maximum time to wait for each embedding request. Not set by default, in which case the Gemini client default applies.

titleMetadataKeystring

Document title metadata key

Metadata key whose value is passed to the model as the document's title, which improves retrieval quality by giving the document context. Not set by default.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

type*object

configuration

Default{}

Language model configuration

Chat model settings (temperature, response format, token limits, and so on) applied to this sub-agent. Defaults to an empty configuration, so the provider's own defaults apply.

io.kestra.plugin.ai.domain.ChatConfiguration

logRequestsbooleanstring

Log LLM requests

If true, the prompts and configuration sent to the LLM are logged at INFO level. Defaults to false.

logResponsesbooleanstring

Log LLM responses

If true, the raw responses returned by the LLM are logged at INFO level. Defaults to false.

maxCumulativeTokensintegerstring

Maximum cumulative tokens

maxTokenintegerstring

Maximum output tokens

Upper bound on the number of tokens the model may generate in one response, which caps the output length. Not set by default, in which case the provider's own default applies.

promptCachingbooleanstring

Enable prompt caching

responseFormat

Response format

io.kestra.plugin.ai.domain.ChatConfiguration-ResponseFormat

jsonSchemaobject

JSON schema

jsonSchemaDescriptionstring

Schema description

Natural-language explanation of the schema, which helps the model produce the right fields. Not set by default.

strictJsonbooleanstring

Defaultfalse

Enable strict JSON schema mode

If true, providers that support it enforce the JSON schema strictly instead of treating it as a hint. Only allowed when type is JSON. Defaults to false.

typestring

DefaultTEXT

Possible Values

TEXTJSON

Response format type

How the model returns its output: TEXT for free-form natural language, or JSON for output validated against a JSON schema. Defaults to TEXT.

returnThinkingbooleanstring

Return thinking

seedintegerstring

Seed

Positive integer seeding the sampler, so that the same seed with identical settings reproduces the same output. Not set by default (non-deterministic generation).

temperaturenumberstring

Temperature

thinkingBudgetTokensintegerstring

Thinking Token Budget

thinkingEnabledbooleanstring

Enable Thinking

topKintegerstring

Top-K

topPnumberstring

Top-P (nucleus sampling)

contentRetrievers

Content retrievers

Retrievers whose results are always injected into the sub-agent's context, unlike tools, which the LLM calls only when it decides to. Some sources, such as web search, can act as either. Not set by default.

Retrieve context from an embedding store

Example

yaml
id: agent_with_rag
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Paris is the capital of France with a population of over 2.1 million people
      - content: The Eiffel Tower is the most famous landmark in Paris at 330 meters tall

  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.EmbeddingStoreRetriever
        embeddings:
          type: io.kestra.plugin.ai.embeddings.KestraKVStore
        embeddingProvider:
          type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-embedding-001
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
        maxResults: 3
        minScore: 0.0
    prompt: What is the capital of France and how many people live there?

Use multiple embedding stores simultaneously. This demonstrates the power of the content retriever approach - you can retrieve from multiple embedding stores and other sources in a single task.

yaml
id: multi_store_rag
namespace: company.ai

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.EmbeddingStoreRetriever
        embeddings:
          type: io.kestra.plugin.ai.embeddings.Pinecone
          apiKey: "{{ secret('PINECONE_API_KEY') }}"
          index: technical-docs
        embeddingProvider:
          type: io.kestra.plugin.ai.provider.OpenAI
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          modelName: text-embedding-3-small
      - type: io.kestra.plugin.ai.retriever.EmbeddingStoreRetriever
        embeddings:
          type: io.kestra.plugin.ai.embeddings.Qdrant
          host: localhost
          port: 6333
          collectionName: business-docs
        embeddingProvider:
          type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-embedding-001
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
      - type: io.kestra.plugin.ai.retriever.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"
    prompt: What are the latest trends in data orchestration?

embeddingProvider*

Embedding model provider

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

embeddings*

Embedding store

Embedding store queried for content relevant to the user's question. No default: this property is required.

Store embeddings in Chroma

Connects to a Chroma HTTP instance using cosine distance; targets the given collection and drops it when drop=true.

Example

Ingest documents into a Chroma embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Chroma
      baseUrl: http://localhost:8000
      collectionName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

baseUrl*string

Database base URL

Base URL of the Chroma server. No default: this property is required.

collectionName*string

Collection name

Chroma collection that holds the embeddings. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Chromaio.kestra.plugin.langchain4j.embeddings.Chroma

Store embeddings in Elasticsearch

Example

Ingest documents into an Elasticsearch embedding store (requires Elasticsearch 8.15+)

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Elasticsearch
      connection:
        hosts:
          - http://localhost:9200
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

connection*

Connection

Elasticsearch connection settings: hosts, authentication, and TLS options. No default: this property is required.

indexName*string

Index name

Elasticsearch index that stores the embeddings. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Elasticsearchio.kestra.plugin.langchain4j.embeddings.Elasticsearch

Prototype embeddings in Kestra KV

Stores embeddings in-memory and persists them to Kestra namespace KV on completion. Suitable for small demos; not scalable. drop=true discards any previously saved KV snapshot.

Example

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

type*object

Possible Values

io.kestra.plugin.ai.embeddings.KestraKVStoreio.kestra.plugin.langchain4j.embeddings.KestraKVStore

kvNamestring

Default{{ flow.id }}-embedding-store

KV pair name

Key of the Kestra KV pair used to persist the in-memory embedding store between task runs. Defaults to {{ flow.id }}-embedding-store.

Store embeddings in MariaDB

Example

Ingest documents into a MariaDB embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.MariaDB
      username: "{{ secret('MARIADB_USERNAME') }}"
      password: "{{ secret('MARIADB_PASSWORD') }}"
      databaseUrl: "{{ secret('MARIADB_DATABASE_URL') }}"
      tableName: embeddings
      fieldName: id
      createTable: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

createTable*booleanstring

Create table if missing

If true, the embeddings table is created when it does not already exist. Defaults to false.

databaseUrl*string

Database URL

JDBC URL of the MariaDB database holding the embeddings. No default: this property is required.

fieldName*string

ID column name

Name of the column used as the unique identifier of each embedding. Defaults to an empty value, which lets the MariaDB store use its own column name.

password*string

Password

Password of the database user. Store it as a Kestra secret rather than inline. No default: this property is required.

tableName*string

Table name

Name of the table where embeddings are stored. No default: this property is required.

type*object

username*string

Username

User connecting to the MariaDB database. No default: this property is required.

columnDefinitionsarray

SubTypestring

Metadata column definitions

SQL column definitions for metadata fields, one per metadata key. Required only when metadataStorageMode is COLUMN_PER_KEY. Not set by default.

indexesarray

SubTypestring

Metadata index definitions

SQL index definitions for the metadata columns. Used only when metadataStorageMode is COLUMN_PER_KEY. Not set by default (no extra index).

metadataStorageModestring

DefaultCOLUMN_PER_KEY

Metadata storage mode

Store embeddings in Milvus

Example

Ingest documents into a Milvus embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Milvus
      # Use either `uri` or `host`/`port`:
      # For gRPC (typical): milvus://localhost:19530
      # For HTTP: http://localhost:9091
      uri: "http://localhost:9091"
      token: "{{ secret('MILVUS_TOKEN') }}"
      collectionName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

token*string

Token

Milvus authentication token. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Milvusio.kestra.plugin.langchain4j.embeddings.Milvus

autoFlushOnDeletebooleanstring

Auto flush on delete

Intended to flush the collection after every delete. Note: this property currently has no effect, as it is not passed to the Milvus client when the store is built.

autoFlushOnInsertbooleanstring

Auto flush on insert

If true, flush the collection after every insert so new vectors are immediately searchable. Setting it to false improves ingestion throughput. Defaults to false.

collectionNamestring

Collection name

Collection that stores the embeddings. Not set by default, in which case the Milvus client's own default collection name applies.

consistencyLevelstring

Consistency level

Read/write consistency level applied to the collection: STRONG, BOUNDED, SESSION or EVENTUALLY. Defaults to EVENTUALLY.

databaseNamestring

Database name

Logical Milvus database holding the collection. Not set by default, in which case the server's default database is used.

hoststring

Host

Hostname of the Milvus server, used when uri is not set. Not set by default, in which case the Milvus client's own default applies.

idFieldNamestring

ID field name

Collection field holding the document ID. Not set by default, in which case the collection schema's own field name is used.

indexTypestring

Index type

Vector index built on the collection, such as FLAT, IVF_FLAT, IVF_SQ8, HNSW, DISKANN or AUTOINDEX. The best choice depends on the deployment and dataset size. Defaults to FLAT.

metadataFieldNamestring

Metadata field name

Collection field holding the document metadata. Not set by default, in which case the collection schema's own field name is used.

metricTypestring

Metric type

Similarity metric used to compare vectors: L2, IP, COSINE, HAMMING or JACCARD. It should match the metric the embedding model was trained for. Defaults to COSINE.

passwordstring

Password

Password of the Milvus user. Required only when authentication or TLS is enabled. Store it as a Kestra secret rather than inline. Not set by default.

portintegerstring

Port

Port of the Milvus server, used when uri is not set. Typically 19530 for gRPC or 9091 for HTTP. Not set by default, in which case the Milvus client's own default applies.

retrieveEmbeddingsOnSearchbooleanstring

Retrieve embeddings on search

If true, search results also carry the stored embedding vectors. Defaults to false.

textFieldNamestring

Text field name

Collection field holding the original text segment. Not set by default, in which case the collection schema's own field name is used.

uristring

URI

Full connection URI of the Milvus server, such as milvus://host: 19530 for gRPC or http://host: 9091 for HTTP. Set either this property or host/port, not both. Not set by default.

usernamestring

Username

User authenticating against Milvus. Required only when authentication or TLS is enabled; see https://milvus.io/docs/authenticate.md. Not set by default.

vectorFieldNamestring

Vector field name

Collection field holding the embedding vector. It must match the index definition and the embedding dimensionality. Not set by default, in which case the collection schema's own field name is used.

Store embeddings in MongoDB Atlas

Example

Ingest documents into a MongoDB Atlas embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.MongoDBAtlas
      scheme: mongodb+srv
      username: "{{ secret('MONGODB_ATLAS_USERNAME') }}"
      password: "{{ secret('MONGODB_ATLAS_PASSWORD') }}"
      host: "{{ secret('MONGODB_ATLAS_HOST') }}"
      database: "{{ secret('MONGODB_ATLAS_DATABASE') }}"
      collectionName: embeddings
      indexName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

collectionName*string

Collection name

Collection that stores the embedding documents. No default: this property is required.

database*string

Database name

Name of the database holding the embeddings collection. No default: this property is required.

host*string

Host

Hostname of the MongoDB cluster, optionally with a port for the mongodb scheme. No default: this property is required.

indexName*string

Index name

Name of the Atlas Vector Search index used to query the collection. No default: this property is required.

scheme*string

Connection scheme

Scheme of the MongoDB connection string: mongodb+srv for Atlas clusters, mongodb for a direct connection. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.MongoDBAtlasio.kestra.plugin.langchain4j.embeddings.MongoDBAtlas

createIndexbooleanstring

Create the index

If true, create the Atlas Vector Search index when it does not already exist. Defaults to false, which assumes the index is provisioned beforehand.

metadataFieldNamesarray

SubTypestring

Metadata field names

Metadata keys to map into the vector search index so they can be filtered on. Not set by default, in which case no metadata index mapping is created.

optionsobject

Connection string options

Extra options appended to the MongoDB connection string as query parameters. Not set by default.

passwordstring

Password

Password of the database user. Store it as a Kestra secret rather than inline. Not set by default; omit it along with username for an unauthenticated connection.

usernamestring

Username

User connecting to the MongoDB Atlas cluster. Not set by default; omit it along with password for an unauthenticated connection.

Store embeddings with pgvector

Example

Ingest documents into a PGVector embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.PGVector
      host: localhost
      port: 5432
      user: "{{ secret('POSTGRES_USER') }}"
      password: "{{ secret('POSTGRES_PASSWORD') }}"
      database: postgres
      table: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

database*string

Database name

Name of the PostgreSQL database holding the embeddings table. No default: this property is required.

host*string

Database server host

Hostname or IP address of the PostgreSQL server running the pgvector extension. No default: this property is required.

password*string

Database password

Password of the database user. Store it as a Kestra secret rather than inline. No default: this property is required.

port*integerstring

Database server port

TCP port the PostgreSQL server listens on. No default: this property is required.

table*string

Table name

Table that stores the embeddings. No default: this property is required. When drop is requested by the ingestion task, the table is recreated.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.PGVectorio.kestra.plugin.langchain4j.embeddings.PGVector

user*string

Database user

User connecting to the PostgreSQL database. No default: this property is required.

useIndexbooleanstring

Defaultfalse

Use an IVFFlat index

Store embeddings in Pinecone

Creates or connects to a serverless Pinecone index in the given cloud/region; namespace defaults to Pinecone’s default. Requires an API key; drop=true clears the index contents.

Example

Ingest documents into a Pinecone embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Pinecone
      apiKey: "{{ secret('PINECONE_API_KEY') }}"
      cloud: AWS
      region: us-east-1
      index: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

apiKey*string

API Key

Pinecone API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

cloud*string

Cloud provider

Cloud provider hosting the Pinecone serverless index. No default: this property is required.

index*string

Index name

Pinecone index that stores the embeddings. It is created as a serverless index if it does not exist. No default: this property is required.

region*string

Cloud provider region

Region of the cloud provider hosting the serverless index. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Pineconeio.kestra.plugin.langchain4j.embeddings.Pinecone

namespacestring

Namespace

Namespace that partitions vectors inside the index. Not set by default, in which case Pinecone's default namespace is used.

Store embeddings in Qdrant

Uses the Qdrant gRPC client with API key, host, and port. Targets the specified collection; drop=true removes its contents. Distance metric follows the Qdrant collection defaults.

Example

Ingest documents into a Qdrant embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Qdrant
      apiKey: "{{ secret('QDRANT_API_KEY') }}"
      host: localhost
      port: 6334
      collectionName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

apiKey*string

API Key

Qdrant API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

collectionName*string

Collection name

Qdrant collection that holds the embeddings. No default: this property is required.

host*string

Database server host

Hostname or IP address of the Qdrant server. No default: this property is required.

port*integerstring

Database server port

gRPC port the Qdrant server listens on. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Qdrantio.kestra.plugin.langchain4j.embeddings.Qdrant

Store embeddings in Redis

Example

Ingest documents into a Redis embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Redis
      host: localhost
      port: 6379
      indexName: embeddings
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

host*string

Database server host

Hostname or IP address of the Redis server (Redis Stack, with the search module enabled). No default: this property is required.

port*integerstring

Database server port

TCP port the Redis server listens on. No default: this property is required.

type*object

indexNamestring

Defaultembedding-index

Index name

Name of the Redis search index that stores the embeddings. Defaults to embedding-index.

Store embeddings in Alibaba Tablestore

Example

Ingest documents into a Tablestore embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Tablestore
      endpoint:  "{{ secret('TABLESTORE_ENDPOINT') }}"
      instanceName:  "{{ secret('TABLESTORE_INSTANCE_NAME') }}"
      accessKeyId:  "{{ secret('TABLESTORE_ACCESS_KEY_ID') }}"
      accessKeySecret:  "{{ secret('TABLESTORE_ACCESS_KEY_SECRET') }}"
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

accessKeyId*string

Access Key ID

Alibaba Cloud access key ID used to authenticate against Tablestore. Store it as a Kestra secret rather than inline. No default: this property is required.

accessKeySecret*string

Access Key Secret

Alibaba Cloud access key secret paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

endpoint*string

Endpoint URL

Base URL of the Tablestore instance endpoint. No default: this property is required.

instanceName*string

Instance name

Name of the Tablestore instance holding the embeddings. No default: this property is required.

type*object

metadataSchemaListarray

Metadata schema list

Tablestore field schemas describing the metadata columns to index, so they can be filtered on at search time. Not set by default (no metadata indexed).

Store embeddings in Weaviate

Example

Ingest documents into a Weaviate embedding store

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-embedding-001
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.Weaviate
      apiKey: "{{ secret('WEAVIATE_API_KEY') }}"
      scheme: https                                 # http | https (defaults to https)
      host: your-cluster-id.weaviate.network        # no protocol
      port: 443                                     # required (e.g. 443 for https, 80 for http)
      objectClass: Documents                        # required; must start with an uppercase letter
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/content/blogs/release-0-24.md

apiKey*string

API key

Weaviate API key used to authenticate against the cluster. Store it as a Kestra secret rather than inline. No default: this property is required.

host*string

Host

Cluster hostname, without protocol or port. No default: this property is required.

objectClass*string

Object class

Weaviate class that stores the embedded objects. It must start with an uppercase letter. No default: this property is required.

port*integerstring

Port

Port of the Weaviate HTTP endpoint, typically 443 for https and 80 or 8080 for http. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.embeddings.Weaviateio.kestra.plugin.langchain4j.embeddings.Weaviate

avoidDupsbooleanstring

Avoid duplicates

consistencyLevelstring

Possible Values

ONEQUORUMALL

Consistency level

Write consistency applied to each object: ONE, QUORUM or ALL. Defaults to QUORUM.

grpcPortintegerstring

gRPC port

Port of the Weaviate gRPC endpoint. Required when useGrpcForInserts is true. Not set by default.

metadataFieldNamestring

Metadata field name

Property used to store document metadata on the object. Not set by default, in which case the Weaviate client's own default field name applies.

metadataKeysarray

SubTypestring

Metadata keys

Metadata keys to persist alongside each object. Defaults to an empty list, meaning no metadata is stored.

schemestring

Scheme

Protocol used to reach the cluster: https (recommended) or http. Defaults to https.

securedGrpcbooleanstring

Secure gRPC

Whether the gRPC connection uses TLS. Defaults to true. Only relevant when useGrpcForInserts is true.

useGrpcForInsertsbooleanstring

Use gRPC for batch inserts

If true, batch inserts go over gRPC, which is faster for large ingestions; searches still use HTTP. Requires grpcPort. Defaults to false.

type*object

maxResultsintegerstring

Default3

Maximum results

Number of matching segments returned by the embedding store for each query. Defaults to 3.

minScorenumberstring

Default0.0

Minimum similarity score

Similarity threshold a match must reach to be returned, from 0.0 (keep everything) to 1.0 (exact match only). Defaults to 0.0.

Retrieve web results with Google Custom Search

Uses Google Custom Search (CSE) to fetch web snippets for RAG. Requires API key and CSE ID (csi/cx); maxResults limits returned items (default 3). Requests consume CSE quota.

Example

RAG chat with a web search content retriever (answers grounded in search results)

yaml
id: rag
namespace: company.ai

tasks:
  - id: chat_with_rag_and_websearch_content_retriever
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.GoogleCustomWebSearch
        apiKey: "{{ secret('GOOGLE_SEARCH_API_KEY') }}"
        csi: "{{ secret('GOOGLE_SEARCH_CSI') }}"
    prompt: What is the latest release of Kestra?

apiKey*string

API key

Google Custom Search JSON API key. Store it as a Kestra secret rather than inline. No default: this property is required.

csi*string

Custom Search Engine ID

Identifier of the Programmable Search Engine to query, referred to as cx in Google's documentation. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.retriever.GoogleCustomWebSearchio.kestra.plugin.langchain4j.retriever.GoogleCustomWebSearch

maxResultsintegerstring

Default3

Maximum results

Number of search results retrieved for each query. Defaults to 3.

Retrieve context from SQL (experimental)

Example

RAG chat with a SQL Database content retriever (answers grounded in database data)

yaml
id: rag
namespace: company.ai

tasks:
  - id: chat_with_rag_and_sql_retriever
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.SqlDatabaseRetriever
        databaseType: POSTGRESQL
        jdbcUrl: "jdbc:postgresql://localhost:5432/mydb"
        username: "{{ secret('DB_USER') }}"
        password: "{{ secret('DB_PASSWORD') }}"
    prompt: "What are the top 5 customers by revenue?"

databaseType*object

password*string

Database password

Password of the database user. Store it as a Kestra secret rather than inline. No default: this property is required.

provider*

Language model provider

Model provider used to translate the natural-language question into SQL. No default: this property is required.

Use Amazon Bedrock models

Invokes Bedrock-hosted chat/embedding models with AWS credentials. Supports standard AWS region/auth settings; ensure model IDs match your Bedrock region and account access.

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AmazonBedrock
      accessKeyId: "{{ secret('AWS_ACCESS_KEY') }}"
      secretAccessKey: "{{ secret('AWS_SECRET_KEY') }}"
      modelName: anthropic.claude-3-sonnet-20240229-v1:0
      thinkingBudgetTokens: 1024
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accessKeyId*string

AWS Access Key ID

AWS access key ID used to sign Bedrock requests. Store it as a Kestra secret rather than inline. No default: this property is required.

secretAccessKey*string

AWS Secret Access Key

AWS secret access key paired with accessKeyId. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AmazonBedrockio.kestra.plugin.langchain4j.provider.AmazonBedrock

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

Family of the Bedrock embedding model, which selects the request/response format used for embeddings. One of COHERE or TITAN. Defaults to COHERE. Ignored for chat and image models.

Use Anthropic Claude models

Example

Chat completion with Anthropic

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Anthropic
      apiKey: "{{ secret('ANTHROPIC_API_KEY') }}"
      modelName: claude-3-haiku-20240307
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: false
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Anthropic API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Anthropicio.kestra.plugin.langchain4j.provider.Anthropic

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxTokensintegerstring

Maximum Tokens

modelNamestring

Model name

Use Azure OpenAI deployments

Targets Azure-hosted OpenAI models via the resource endpoint and deployment name. Supports API key or AAD client credentials; set apiVersion when required by the deployment.

Example

Chat completion with Azure OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.AzureOpenAI
      apiKey: "{{ secret('AZURE_API_KEY') }}"
      endpoint: https://your-resource.openai.azure.com/
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

API endpoint

Azure OpenAI resource endpoint, in the form https://{resource}.openai.azure.com/. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.AzureOpenAIio.kestra.plugin.langchain4j.provider.AzureOpenAI

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientIdstring

Client ID

Microsoft Entra ID application (client) ID used for service-principal authentication. Required together with tenantId and clientSecret when apiKey is not set.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

clientSecretstring

Client secret

modelNamestring

Model name

serviceVersionstring

API version

Azure OpenAI REST API version to call. Not set by default, in which case the Azure SDK's latest supported version is used.

tenantIdstring

Tenant ID

Microsoft Entra ID tenant used for service-principal authentication. Required together with clientId and clientSecret when apiKey is not set.

Use Cohere models

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Cohere
      apiKey: "{{ secret('COHERE_API_KEY') }}"
      modelName: command-a-03-2025
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://api.cohere.ai/compatibility/v1

API base URL

Base URL of the Cohere OpenAI-compatible API. Defaults to https://api.cohere.ai/compatibility/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use DashScope (Qwen) models

Calls Alibaba Cloud DashScope for Qwen chat/embeddings/images with API key. Some params (timeouts, retries, stop, maxTokens) map directly to DashScope limits.

Example

Chat completion with DashScope (Qwen)

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DashScope
      apiKey: "{{ secret('DASHSCOPE_API_KEY') }}"
      modelName: qwen-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Alibaba Cloud DashScope API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://dashscope-intl.aliyuncs.com/api/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

enableSearchbooleanstring

Enable Internet search

If true, the model may use Internet search results as reference when generating text. Defaults to false.

maxTokensintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Not set by default, in which case the DashScope default applies.

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

Use DeepSeek models

Connects to DeepSeek’s OpenAI-compatible endpoint with API key and model name for chat/embedding tasks.

Example

Chat completion with DeepSeek

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DeepSeek
      apiKey: "{{ secret('DEEPSEEK_API_KEY') }}"
      modelName: deepseek-chat
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.DeepSeekio.kestra.plugin.langchain4j.provider.DeepSeek

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

Base URL of the DeepSeek OpenAI-compatible API. Defaults to https://api.deepseek.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Docker Model Runner

Routes inference to a locally running Docker Model Runner instance via its OpenAI-compatible REST API.

Base URL variants — pick the one matching where Kestra itself runs:

Kestra in a container on Docker Desktop: http://model-runner.docker.internal/engines/v1
Kestra in a container on Docker Engine (Linux): http://172.17.0.1: 12434/engines/v1
Kestra directly on the host (default): http://localhost: 12434/engines/v1

Pair this provider with io.kestra.plugin.docker.model.Pull (plugin-docker) to manage model lifecycle in the same flow.

Example

Chat completion with Docker Model Runner

yaml
id: docker_model_chat
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: pull_model
    type: io.kestra.plugin.docker.model.Pull
    model: ai/smollm2

  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion (container-internal base URL)

yaml
id: docker_model_chat_container
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ask
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.DockerModel
      modelName: ai/smollm2
      baseUrl: http://model-runner.docker.internal/engines/v1
    messages:
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

apiKeystring

Defaultnot-needed

API Key

Placeholder credential: Docker Model Runner requires no authentication and accepts any non-empty value. Defaults to not-needed.

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Configure ordered model providers for fallback

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: ai_agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Fallback
      providers:
        - type: io.kestra.plugin.ai.provider.OpenAI
          modelName: gpt-5-mini
          apiKey: "{{ secret('OPENAI_API_KEY') }}"
          baseUrl: https://api.openai.com/v1
        - type: io.kestra.plugin.ai.provider.GoogleGemini
          modelName: gemini-2.5-flash
          apiKey: "{{ secret('GEMINI_API_KEY') }}"
    systemMessage: You are a helpful assistant. Answer clearly and concisely.
    prompt: "{{ inputs.prompt }}"

providers*

Providers

Model providers in the order they should be considered for fallback.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use GitHub Models via Azure AI Inference

Calls GitHub Models through the Azure AI Inference API with a GitHub token. Supports chat and embeddings; response format options map to Azure AI Inference capabilities.

Example

Chat completion with GitHub Models

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GitHubModels
      gitHubToken: "{{ secret('GITHUB_TOKEN') }}"
      modelName: gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely.
      - type: USER
        content: "{{ inputs.prompt }}"

gitHubToken*string

GitHub Token

GitHub Personal Access Token (PAT) used to access GitHub Models. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Google Gemini models

Example

Chat completion with Google Gemini

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GOOGLE_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Gemini with a local base URL + PEM certificates

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      clientPem: "{{ secret('CLIENT_PEM') }}"
      caPem: "{{ secret('CA_PEM') }}"
      baseUrl: "https://internal.gemini.company.com/endpoint"
    configuration:
      thinkingEnabled: true
      thinkingBudgetTokens: 1024
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleGeminiio.kestra.plugin.langchain4j.provider.GoogleGemini

apiKeystring

API Key

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

embeddingModelConfiguration

Embedding model configuration

Settings applied when this provider is used to generate embeddings rather than chat completions. Not set by default, in which case the Gemini client defaults apply.

modelNamestring

Model name

Use Google Vertex AI models

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleVertexAI
      modelName: gemini-3.5-flash-lite
      location: your-google-cloud-region
      projectId: your-google-cloud-project-id
      serviceAccount: "{{ secret('GCP_SERVICE_ACCOUNT_JSON') }}"
    messages:
      - type: USER
        content: What is the capital of France?

location*string

Project location

Google Cloud region hosting the Vertex AI model, or global to use the global endpoint aiplatform.googleapis.com. No default: this property is required for chat models.

type*object

Possible Values

io.kestra.plugin.ai.provider.GoogleVertexAIio.kestra.plugin.langchain4j.provider.GoogleVertexAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

endpointstring

Endpoint URL

impersonatedServiceAccountstring

Service account to impersonate

Email of the service account to impersonate. Not supported for image models.

modelNamestring

Model name

projectstring

Project ID (deprecated)

Deprecated, use projectId instead. Only used when projectId is not set.

projectIdstring

Project ID

Google Cloud project ID that owns the Vertex AI resources. When not set, it is taken from the service account credentials.

scopesarray

SubTypestring

Default["https://www.googleapis.com/auth/cloud-platform"]

OAuth scopes

serviceAccountstring

Service account JSON key

Content of a Google Cloud service account JSON key. When not set, Application Default Credentials are used. Not supported for image models, which always use Application Default Credentials.

Use Hugging Face Inference endpoints

Routes requests to Hugging Face Inference Endpoints via the OpenAI-compatible gateway (default router.huggingface.co). Requires an API token and deployment model name.

Example

Chat completion with HuggingFace

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.HuggingFace
      apiKey: "{{ secret('HUGGING_FACE_API_KEY') }}"
      modelName: HuggingFaceTB/SmolLM3-3B:hf-inference
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

Base URL of the Hugging Face router's OpenAI-compatible API. Defaults to https://router.huggingface.co/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Langdock models

Example

Chat completion with a Langdock-hosted OpenAI model

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: OPENAI
      modelName: gpt-5.4-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

AI agent using a Langdock-hosted Claude model with a Kestra tool

yaml
id: agent_with_tool
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: "Log the message 'Hello from Langdock!'"

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_API_KEY') }}"
      modelFamily: ANTHROPIC
      modelName: claude-sonnet-4-6-default
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..."

Ingest documents into a KV embedding store using Langdock embeddings

yaml
id: document_ingestion
namespace: company.ai

tasks:
  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Langdock
      apiKey: "{{ secret('LANGDOCK_WORKSPACE_API_KEY') }}"
      modelName: text-embedding-ada-002
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromExternalURLs:
      - https://raw.githubusercontent.com/kestra-io/docs/refs/heads/main/README.md

apiKey*string

API Key

Langdock API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

Langdock region that serves the request: EU or US. Defaults to EU. Ignored when baseUrl points at a dedicated deployment.

Use LocalAI OpenAI-compatible server

Targets a self-hosted LocalAI instance via its OpenAI-compatible API for chat/embeddings/images. Set baseUrl if your server is not on the default.

Example

Chat completion with LocalAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.LocalAI
      modelName: gemma-3-1b-it
      baseUrl: http://localhost:8080/v1
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

baseUrl*string

API base URL

Base URL of the LocalAI server's OpenAI-compatible API. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.LocalAIio.kestra.plugin.langchain4j.provider.LocalAI

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Mistral models

Calls Mistral chat/embedding APIs with an API key. topK is not supported; chat configuration must respect model limits.

Example

Chat completion with Mistral AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.MistralAI
      apiKey: "{{ secret('MISTRAL_API_KEY') }}"
      modelName: mistral-small-latest
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

Mistral AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.MistralAIio.kestra.plugin.langchain4j.provider.MistralAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OCI Generative AI models

Example

Chat completion with OciGenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OciGenAI
      region: "{{ secret('OCI_GENAI_MODEL_REGION_PROPERTY') }}"
      compartmentId: "{{ secret('OCI_GENAI_COMPARTMENT_ID_PROPERTY') }}"
      authProvider: "{{ secret('OCI_GENAI_CONFIG_PROFILE_PROPERTY') }}"
      modelName: cohere.command-r-plus
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

compartmentId*string

Compartment OCID

OCID of the OCI compartment holding the generative AI model. No default: this property is required.

region*string

OCI region

OCI region the client connects to, which must offer the OCI Generative AI service. No default: this property is required.

type*object

authProviderstring

OCI config profile name

Name of the profile in your OCI config file used to authenticate the SDK client. Defaults to DEFAULT.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use local Ollama models

Calls an Ollama server for chat/embeddings using the given endpoint and model name. Ideal for self-hosted/local models; ensure the Ollama daemon is reachable.

Example

Chat completion with Ollama

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.Ollama
      modelName: llama3
      endpoint: http://localhost:11434
    configuration:
      thinkingEnabled: true
      returnThinking: true
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

endpoint*string

Model endpoint

Base URL of the Ollama server exposing the model. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.Ollamaio.kestra.plugin.langchain4j.provider.Ollama

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Compute embeddings in-process with an ONNX model

Example

Ingest and search documents with all-MiniLM-L6-v2 downloaded from Hugging Face

yaml
id: onnx_rag
namespace: company.ai

tasks:
  - id: model
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx

  - id: tokenizer
    type: io.kestra.plugin.core.http.Download
    uri: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json

  - id: ingest
    type: io.kestra.plugin.ai.rag.IngestDocument
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    drop: true
    fromDocuments:
      - content: Kestra is an open-source orchestration platform for data and AI workflows.
      - content: PostgreSQL is a relational database.

  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: all-MiniLM-L6-v2
      modelUri: "{{ outputs.model.uri }}"
      tokenizerUri: "{{ outputs.tokenizer.uri }}"
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: Which tool orchestrates workflows?
    maxResults: 1
    minScore: 0.3
    fetchType: FETCH

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

tasks:
  - id: search
    type: io.kestra.plugin.ai.rag.Search
    provider:
      type: io.kestra.plugin.ai.provider.Onnx
      modelName: bge-small-en-v1.5
      modelUri: nsfile:///models/bge-small-en-v1.5/model.onnx
      tokenizerUri: nsfile:///models/bge-small-en-v1.5/tokenizer.json
      poolingMode: CLS
    embeddings:
      type: io.kestra.plugin.ai.embeddings.KestraKVStore
    query: "{{ inputs.query }}"
    maxResults: 3
    minScore: 0.5
    fetchType: FETCH

modelUri*string

ONNX model file

tokenizerUri*string

Tokenizer file

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

Use OpenAI models

Connects to OpenAI-compatible endpoints (defaults to api.openai.com) for chat, embeddings, or images. Requires API key; override baseUrl for Azure-compatible or proxy setups.

Example

Chat completion with OpenAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenAI
      apiKey: "{{ secret('OPENAI_API_KEY') }}"
      modelName: gpt-5-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

API key used to authenticate against the provider. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenAIio.kestra.plugin.langchain4j.provider.OpenAI

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

Base URL of the OpenAI-compatible API. Override it to target Azure OpenAI, a proxy, or a self-hosted gateway. Defaults to https://api.openai.com/v1.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use OpenRouter models

Routes requests through OpenRouter’s multi-model API using your API key. Supports chat/embedding/image models exposed by OpenRouter; honor provider-specific safety/usage limits.

Example

Chat completion with OpenRouter

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.OpenRouter
      apiKey: "{{ secret('OPENROUTER_API_KEY') }}"
      baseUrl: https://openrouter.ai/api/v1
      modelName: openai/gpt-4o-mini
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

OpenRouter API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.OpenRouterio.kestra.plugin.langchain4j.provider.OpenRouter

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use IBM watsonx.ai models

Calls IBM watsonx.ai chat/embedding endpoints with API key and project ID. Ensure the selected model ID is available in the configured project.

Example

Chat completion with Watsonx AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WatsonxAI
      apiKey: "{{ secret('WATSONX_API_KEY') }}"
      projectId: "{{ secret('WATSONX_PROJECT_ID') }}"
      modelName: ibm/granite-3-3-8b-instruct
      baseUrl : "https://api.eu-de.dataplatform.cloud.ibm.com/wx"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

IBM Cloud API key used to authenticate against watsonx.ai. Store it as a Kestra secret rather than inline. No default: this property is required.

projectId*string

Project ID

Identifier of the watsonx.ai project the model runs under. No default: this property is required.

type*object

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use Cloudflare Workers AI models

Invokes Workers AI chat, embedding, and image models using account ID and API key. Ensure the selected model is available in your account/region.

Example

Chat completion with WorkersAI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.WorkersAI
      accountId: "{{ secret('WORKERS_AI_ACCOUNT_ID') }}"
      apiKey: "{{ secret('WORKERS_AI_API_KEY') }}"
      modelName: "@cf/meta/llama-2-7b-chat-fp16"
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

accountId*string

Account Identifier

Cloudflare account ID that owns the Workers AI deployment. No default: this property is required.

apiKey*string

API Key

Cloudflare API token with Workers AI access. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.provider.WorkersAIio.kestra.plugin.langchain4j.provider.WorkersAI

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

modelNamestring

Model name

Use ZhiPu AI models

Calls ZhiPu’s OpenAI-compatible chat/embedding/image APIs with API key and model name. Supports stop tokens, retry count, and max tokens per request.

Example

Chat completion with ZhiPu AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.ZhiPuAI
      apiKey: "{{ secret('ZHIPU_API_KEY') }}"
      modelName: glm-4.5-flash
    messages:
      - type: SYSTEM
        content: You are a helpful assistant, answer concisely, avoid overly casual language or unnecessary verbosity.
      - type: USER
        content: "{{ inputs.prompt }}"

apiKey*string

API Key

ZhiPu AI API key used to authenticate requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

Base URL of the ZhiPu AI API. Defaults to https://open.bigmodel.cn/.

caPemstring

CA PEM certificate content

PEM-encoded certificate authority chain, as text, used to verify the TLS certificate presented by a custom endpoint. Not set by default, in which case the JVM's default trust store is used.

clientPemstring

Client PEM certificate content

PEM-encoded client certificate and private key, as text, used for mutual-TLS authentication against enterprise AI endpoints. Not set by default, in which case the default HTTP client is used.

maxRetriesintegerstring

Maximum retries

Number of times a failed request is retried before the task fails. Defaults to 3.

maxTokenintegerstring

Maximum output tokens

Maximum number of tokens returned by a single request. Defaults to 512.

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

Strings that stop generation as soon as the model is about to produce one of them. The stop sequence itself is not included in the output. Not set by default (no stop sequence).

type*object

username*string

Database username

User connecting to the database. Grant it read-only access, since the model generates the SQL that is executed. No default: this property is required.

configuration

Default{}

Language model configuration

Chat model settings (temperature, response format, token limits, and so on) applied to the SQL-generating model. Defaults to an empty configuration, so the provider's own defaults apply.

io.kestra.plugin.ai.domain.ChatConfiguration

logRequestsbooleanstring

Log LLM requests

If true, the prompts and configuration sent to the LLM are logged at INFO level. Defaults to false.

logResponsesbooleanstring

Log LLM responses

If true, the raw responses returned by the LLM are logged at INFO level. Defaults to false.

maxCumulativeTokensintegerstring

Maximum cumulative tokens

maxTokenintegerstring

Maximum output tokens

Upper bound on the number of tokens the model may generate in one response, which caps the output length. Not set by default, in which case the provider's own default applies.

promptCachingbooleanstring

Enable prompt caching

responseFormat

Response format

returnThinkingbooleanstring

Return thinking

seedintegerstring

Seed

Positive integer seeding the sampler, so that the same seed with identical settings reproduces the same output. Not set by default (non-deterministic generation).

temperaturenumberstring

Temperature

thinkingBudgetTokensintegerstring

Thinking Token Budget

thinkingEnabledbooleanstring

Enable Thinking

topKintegerstring

Top-K

topPnumberstring

Top-P (nucleus sampling)

driverstring

JDBC driver class name

jdbcUrlstring

JDBC URL

maxPoolSizeintegerstring

Maximum connection pool size (deprecated)

Deprecated and ignored: no pool is used, a connection is opened for each query and closed right after it.

Retrieve web results with Tavily

Uses Tavily Search to fetch live web context for RAG. Requires API key; maxResults caps returned snippets and defaults to 3. Requests count against Tavily quotas.

Example

yaml
id: rag
namespace: company.ai

tasks:
  - id: chat_with_rag_and_websearch_content_retriever
    type: io.kestra.plugin.ai.rag.ChatCompletion
    chatProvider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    contentRetrievers:
      - type: io.kestra.plugin.ai.retriever.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"
    prompt: What is the latest release of Kestra?

apiKey*string

API Key

Tavily API key used to authenticate search requests. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.retriever.TavilyWebSearchio.kestra.plugin.langchain4j.retriever.TavilyWebSearch

maxResultsintegerstring

Default3

Maximum results

Number of search results retrieved for each query. Defaults to 3.

maxSequentialToolsInvocationsintegerstring

Maximum sequential tool invocations

Cap on how many tool calls the sub-agent may chain within one run, which guards against runaway tool loops. Defaults to no limit.

namestring

Defaulttool

Agent name

Name the LLM sees for this sub-agent tool. Defaults to tool, so it must be set to a distinct value when several agents are used as tools in the same task.

systemMessagestring

System message

Instructions prepended to the sub-agent's conversation, defining its role and constraints. Not set by default.

tools

Tools

Tools this sub-agent may call to augment its answer. Not set by default (no tools).

Execute JavaScript via Judge0

Sends JavaScript snippets to the Judge0 sandbox (RapidAPI) and returns the program output. Requires a RapidAPI key; execution limits and timeouts follow the Judge0 plan. Avoid sending untrusted secrets in code.

Example

Agent performing mathematical calculations using the Judge0 Code Execution API

yaml
id: calculator_agent
namespace: company.ai

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    prompt: What is the square root of 49506838032859?
    tools:
      - type: io.kestra.plugin.ai.tool.CodeExecution
        apiKey: "{{ secret('RAPID_API_KEY') }}"

apiKey*string

RapidAPI key for Judge0

RapidAPI key authorizing calls to the Judge0 code-execution API, obtainable from the RapidAPI website. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Run MCP tools in Docker

Launches an MCP server inside a Docker container and exposes its tools to the agent. Requires an image; optional command, env, and binds control the container. Docker host defaults to the detected runtime; logEvents defaults to false. Provide registry credentials and TLS settings when pulling from private registries.

Example

Agent calling an MCP server in a Docker container

yaml
id: docker_mcp_client
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: What is the current UTC time?

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.DockerMcpClient
        image: mcp/time

Agent calling an MCP server in a Docker container and generating output files

yaml
id: docker_mcp_client
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: Create the file '/tmp/hello.txt' with the content "Hello World".

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    prompt: "{{ inputs.prompt }}"
    systemMessage: |
      You are a filesystem assistant. Always use the write_file tool with the exact absolute path provided in the user's request.
    tools:
      - type: io.kestra.plugin.ai.tool.DockerMcpClient
        image: mcp/filesystem
        command: ["/tmp"]
        # Mount the container path to the task working directory to access the generated file
        binds: ["{{ workingDir }}:/tmp"]
    outputFiles:
      - hello.txt

image*string

Container image

Docker image running the MCP server. No default: this property is required.

type*object

apiVersionstring

Docker API version

Docker Engine API version used by the client. Not set by default, in which case the version is negotiated with the daemon.

bindsarray

SubTypestring

Volume binds

Host-to-container volume mounts in host_path: container_path form, used for example to share the task working directory with the MCP server. Not set by default (no mount).

commandarray

SubTypestring

MCP server arguments

Arguments passed to the container entrypoint, each element a separate command part. Not set by default, in which case the image's own entrypoint arguments are used.

dockerCertPathstring

Docker certificate path

Directory holding the TLS client certificates used to reach the Docker daemon. Not set by default.

dockerConfigstring

Docker configuration

Docker client configuration as JSON, typically holding registry credentials. Not set by default, in which case the worker's Docker config is used.

dockerContextstring

Docker context

Name of the Docker CLI context selecting which daemon to talk to. Not set by default (the current context is used).

dockerHoststring

Docker host

URI of the Docker daemon that runs the container. Not set by default, in which case the host is auto-detected from the worker environment.

dockerTlsVerifybooleanstring

Verify Docker TLS certificates

If true, verify the Docker daemon's TLS certificate when connecting over TLS. Not set by default, in which case the Docker client default applies.

envobject

Environment variables

Environment variables set inside the container, typically to supply credentials to the MCP server. Not set by default.

logEventsbooleanstring

Defaultfalse

Log events

If true, MCP protocol events exchanged with the container are logged. Defaults to false.

registryEmailstring

Container registry email

Email associated with the container registry account, required by some private registries. Not set by default.

registryPasswordstring

Container registry password

Password or token used to pull the image from a private registry. Store it as a Kestra secret rather than inline. Not set by default (anonymous pull).

registryUrlstring

Container registry URL

Registry the image is pulled from. Not set by default, in which case Docker Hub is used.

registryUsernamestring

Container registry username

User authenticating against a private container registry. Not set by default (anonymous pull).

Search the web with Google CSE

Runs queries through Google Custom Search and returns results to the agent. Requires a Google API key and Custom Search Engine ID (csi/cx); usage is subject to your CSE quotas and filters.

Example

Agent using Google Custom Search for web queries

yaml
id: agent_searching_web
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: What is the latest Kestra release and what new features does it include?

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    prompt: "{{ inputs.prompt }}"
    tools:
      - type: io.kestra.plugin.ai.tool.GoogleCustomWebSearch
        apiKey: "{{ secret('GOOGLE_SEARCH_API_KEY') }}"
        csi: "{{ secret('GOOGLE_SEARCH_CSI') }}"

apiKey*string

API key

Google Custom Search JSON API key. Store it as a Kestra secret rather than inline. No default: this property is required.

csi*string

Custom Search Engine ID

Identifier of the Programmable Search Engine to query, referred to as cx in Google's documentation. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.tool.GoogleCustomWebSearchio.kestra.plugin.langchain4j.tool.GoogleCustomWebSearch

Execute Kestra flows from an agent

Triggers Kestra flows as tools, either predefined (kestra_flow_<namespace>_<flowId>) or generic (kestra_flow with namespace/flowId provided by the prompt). A description is mandatory from the flow or the tool description; inputs, labels, and schedule provided by the LLM override tool defaults. Labels are not inherited unless inheritLabels=true, while the correlationId is inherited when none is supplied.

Example

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-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: business-automation
        description: Business Automation
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: business-processes
        description: Business Processes
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: data-engineering-pipeline
        description: Data Engineering Pipeline
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: dwh-and-analytics
        description: Data Warehouse and Analytics
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: file-processing
        description: File Processing
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: hello-world
        description: Hello World
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: infrastructure-automation
        description: Infrastructure Automation
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

      - type: io.kestra.plugin.ai.tool.KestraFlow
        namespace: tutorial
        flowId: microservices-and-apis
        description: Microservices and APIs
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

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-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraFlow
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

Limit an agent to explicitly allowed flows

yaml
id: agent_calling_allowed_flows
namespace: company.ai

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: Execute the hello-world flow in the tutorial namespace.
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraFlow
        allowedFlows:
          - namespace: tutorial
            flowId: hello-world
        auth:
          apiToken: "{{ secret('KESTRA_API_TOKEN') }}"

type*object

allowedFlowsarray

Allowed flows

Allowlist of exact namespace and flow ID pairs the tool may execute. Not set by default, meaning no restriction. When set, it must be non-empty and every entry must resolve to a non-blank namespace and flow ID; the permitted pairs are exposed to the model and any selection outside the list is rejected before the API is called. The restriction applies even when namespace and flowId are predefined on the tool.

An allowed flow

flowId*string

Allowed flow ID

Identifier of a flow the tool is permitted to execute. No default: this property is required on each allowlist entry.

namespace*string

Allowed flow namespace

Namespace of a flow the tool is permitted to execute. No default: this property is required on each allowlist entry.

auth

API authentication

Credentials used to call the Kestra API: either an API token or HTTP Basic username/password, never both. Not set by default, in which case credentials are taken from Kestra's own configuration.

io.kestra.plugin.ai.tool.KestraFlow-Auth

apiTokenstring

API token

Bearer token authenticating calls to the Kestra API. Store it as a Kestra secret rather than inline. Mutually exclusive with username/password.

autobooleanstring

Defaulttrue

Auto-retrieve credentials

If true, missing credentials are taken from Kestra's own configuration when available. Defaults to true. Set it to false, with no credentials, to call a Kestra API that requires no authentication.

passwordstring

HTTP Basic password

Password paired with username for HTTP Basic authentication. Store it as a Kestra secret rather than inline. Mutually exclusive with apiToken.

usernamestring

HTTP Basic username

User authenticating against the Kestra API with HTTP Basic. Must be paired with password and is mutually exclusive with apiToken.

descriptionstring

Tool description

Natural-language summary of what the called flow does, which the LLM uses to decide whether to call it. Not set by default: the target flow's own description is used, so this property is only needed when that flow has none, or when the flow is chosen dynamically through allowedFlows.

flowIdstring

Flow ID

Identifier of the flow to execute. Not set by default, in which case the LLM chooses the flow, constrained by allowedFlows when it is configured.

inheritLabelsbooleanstring

Defaultfalse

Inherit labels from the calling execution

If true, the triggered execution inherits all labels from the agent's own execution. Defaults to false. Any label the LLM supplies still takes precedence.

inputsobject

Flow execution inputs

Input values passed to the triggered execution. Any input the LLM supplies overrides the value defined here. Not set by default.

kestraUrlstring

Kestra API endpoint

Base URL used for calls to the Kestra API. Not set by default, in which case {{ kestra.url }} is rendered from configuration, falling back to http://localhost: 8080.

labelsarrayobject

Flow execution labels

Labels added to the triggered execution. Any label the LLM supplies overrides the value defined here. Not set by default.

namespacestring

Flow namespace

Namespace of the flow to execute. Not set by default, in which case the LLM chooses the namespace, constrained by allowedFlows when it is configured.

revisionintegerstring

Flow revision

Specific revision of the flow to execute. Not set by default, in which case the latest revision runs.

scheduleDatestring

Scheduled execution date

Date and time at which the execution should start, rather than immediately. Not set by default (immediate execution). A scheduleDate supplied by the LLM overrides this value.

tenantIdstring

Target tenant

Tenant the API calls are made against. Defaults to the tenant of the current execution.

Expose Kestra runnable tasks as tools

Creates one tool per runnable task named kestra_task_<taskId>. Properties you set stay fixed; set a required property to ... to force the agent to supply it, and unset optionals may be filled by the agent. anyOf schemas are flattened to a single branch because many models do not support anyOf; the generated schema appears in debug logs.

Example

Call a Kestra runnable task as a tool, letting the agent set the message property for you

yaml
id: call_a_kestra_task
namespace: company.ai

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.KestraTask
        tasks:
          - id: log
            type: io.kestra.plugin.core.log.Log
            message: "..." # This is a placeholder; the agent will fill it.
    prompt: "Log the following message: 'Hello World!'"

tasks*array

Kestra runnable tasks

Runnable tasks exposed to the LLM as callable tools, one tool per task, named after each task's id. No default: this property is required.

type*object

Provide skills to an AI agent

Exposes langchain4j skills as tools for an AI agent. Skills are structured instructions that the agent can activate on demand. Each skill has a name, description, and content that gets returned when the agent activates it. Skills can also include resources that the agent can read separately.

Example

Use skills to provide structured instructions to an AI agent

yaml
id: agent_with_skills
namespace: company.ai

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: Translate the following text to French - "Hello, how are you today?"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.Skill
        skills:
          - name: translation_expert
            description: Expert translator for multiple languages
            content: |
              You are an expert translator. When translating text:
              1. Preserve the original meaning and tone
              2. Use natural phrasing in the target language
              3. Keep proper nouns unchanged

Load skill content from Kestra internal storage

yaml
id: agent_with_skill_from_storage
namespace: company.ai

tasks:
  - id: write_instructions
    type: io.kestra.plugin.core.storage.Write
    content: |
      You are a senior code reviewer. When reviewing code:
      1. Check for security vulnerabilities
      2. Ensure proper error handling
      3. Verify naming conventions are followed
      4. Flag any code duplication

  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: Review this Python function - "def add(a, b): return a + b"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.Skill
        skills:
          - name: code_review_expert
            description: Expert code reviewer with strict guidelines
            contentUri: "{{ outputs.write_instructions.uri }}"

skills*array

Skill definitions

Structured instruction sets the agent can activate on demand. Each skill needs a name, a description, and either inline content or a contentUri pointing to Kestra internal storage. No default: this property is required.

A skill definition

description*string

Skill description

Natural-language summary of what the skill does, used by the LLM to decide when to activate it. No default: this property is required.

name*string

Skill name

Identifier the LLM uses to activate the skill. No default: this property is required.

contentstring

Inline skill content

Instructions making up the skill, written inline. Mutually exclusive with contentUri; exactly one of the two must be set.

contentUristring

Skill content URI

Kestra internal storage URI of a file holding the skill instructions. Mutually exclusive with content; exactly one of the two must be set.

resourcesarray

Skill resources

Extra files attached to the skill, which the agent reads on demand through the read_skill_resource tool rather than receiving them upfront. Not set by default.

A skill resource definition

content*string

Resource content

Body of the resource file, returned verbatim when the agent reads it. No default: this property is required.

relativePath*string

Resource relative path

Path identifying the resource within the skill, as the agent refers to it when reading the file. No default: this property is required.

type*object

Call MCP server over SSE

Connects to an MCP server that streams Server-Sent Events and exposes its tools to the agent. Requires sseUrl; timeout is optional. Request/response logging is disabled by default; add headers for auth tokens.

Example

Agent calling an MCP server via SSE

yaml
id: mcp_client_sse
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: Find 2 restaurants in Lille, France with the best reviews

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: "{{ inputs.prompt }}"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.SseMcpClient
        sseUrl: https://mcp.apify.com/?actors=compass/crawler-google-places
        timeout: PT5M
        headers:
          Authorization: Bearer {{ secret('APIFY_API_TOKEN') }}

sseUrl*string

SSE URL of the MCP server

Server-Sent Events endpoint of the MCP server exposing the tools. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.tool.SseMcpClientio.kestra.plugin.ai.tool.HttpMcpClientio.kestra.plugin.langchain4j.tool.HttpMcpClient

headersobject

Custom headers

Extra HTTP headers sent with every request, typically to carry an authentication token via the Authorization header. Not set by default.

logRequestsbooleanstring

Defaultfalse

Log requests

If true, requests sent to the MCP server are logged at INFO level. Defaults to false.

logResponsesbooleanstring

Defaultfalse

Log responses

If true, responses received from the MCP server are logged at INFO level. Defaults to false.

timeoutstring

Connection timeout duration

Maximum time to wait for a response from the MCP server. Not set by default, in which case the MCP transport's own default applies.

Run MCP tools over stdio

Starts an MCP server via a local command and exposes its advertised tools to the agent over stdio. command is required; logEvents defaults to false. Use env to pass credentials or config needed by the server process.

Example

Agent calling an MCP server via Stdio

yaml
id: mcp_client_stdio
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: What is the current time in New York?

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: "{{ inputs.prompt }}"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
      modelName: gemini-3.5-flash-lite
    tools:
      - type: io.kestra.plugin.ai.tool.StdioMcpClient
        command: ["docker", "run", "--rm", "-i", "mcp/time"]

command*array

SubTypestring

MCP server command

Command that starts the MCP server process, split into its parts, which the client talks to over standard input/output. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.tool.StdioMcpClientio.kestra.plugin.langchain4j.tool.StdioMcpClient

envobject

Environment variables

Environment variables passed to the MCP server process, typically to supply credentials. Not set by default.

logEventsbooleanstring

Defaultfalse

Log events

If true, MCP protocol events exchanged with the server process are logged. Defaults to false.

Call MCP server over HTTP streaming

Connects to an MCP server via HTTP streaming (chunked responses) and surfaces its tools to the agent. Requires url; timeout, headers, logRequests, and logResponses are optional, with request/response logging off by default.

Example

Agent calling an MCP server via HTTP streaming

yaml
id: mcp_client_streamable_http
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: Find the 2 restaurants in Lille, France with the best reviews.

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: "{{ inputs.prompt }}"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.StreamableHttpMcpClient
        url: https://mcp.apify.com/?actors=compass/crawler-google-places
        timeout: PT5M
        headers:
          Authorization: Bearer {{ secret('APIFY_API_TOKEN') }}

type*object

url*string

URL of the MCP server

Streamable HTTP endpoint of the MCP server exposing the tools. No default: this property is required.

headersobject

Custom headers

Extra HTTP headers sent with every request, typically to carry an authentication token via the Authorization header. Not set by default.

logRequestsbooleanstring

Defaultfalse

Log requests

If true, requests sent to the MCP server are logged at INFO level. Defaults to false.

logResponsesbooleanstring

Defaultfalse

Log responses

If true, responses received from the MCP server are logged at INFO level. Defaults to false.

timeoutstring

Connection timeout duration

Maximum time to wait for a response from the MCP server. Not set by default, in which case the MCP transport's own default applies.

Search the web with Tavily

Uses Tavily's web search API to fetch live results for the agent. Requires a Tavily API key; queries count against your Tavily quota and follow Tavily relevance settings.

Example

Agent searching the web using the Tavily API

yaml
id: research_agent
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: What is the latest Kestra release and what new features does it include? (name 10 new features)

tasks:
  - id: agent
    type: io.kestra.plugin.ai.agent.AIAgent
    prompt: "{{ inputs.prompt }}"
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-3.5-flash-lite
      apiKey: "{{ secret('GEMINI_API_KEY') }}"
    tools:
      - type: io.kestra.plugin.ai.tool.TavilyWebSearch
        apiKey: "{{ secret('TAVILY_API_KEY') }}"

apiKey*string

Tavily API Key

Tavily API key authorizing web-search calls, obtainable from the Tavily website. Store it as a Kestra secret rather than inline. No default: this property is required.

type*object

Possible Values

io.kestra.plugin.ai.tool.TavilyWebSearchio.kestra.plugin.langchain4j.tool.TavilyWebSearch

Outputs

finishReason string

Possible Values

STOPLENGTHTOOL_EXECUTIONCONTENT_FILTEROTHER

Finish reason

Why the model stopped generating, such as STOP, LENGTH or CONTENT_FILTER, when the provider reports it.

guardrailViolated boolean

Defaultfalse

Guardrail violated

Whether an input or output guardrail expression evaluated to false. When true, guardrailViolationMessage holds the rule's message and no LLM output is available. Defaults to false.

guardrailViolationMessage string

Guardrail violation message

Message from the first guardrail rule that failed. Null when no guardrail was violated.

intermediateResponses array

Intermediate responses

Model responses produced at each step of the tool loop before the final answer, useful for debugging agent behavior.

Definitions

io.kestra.plugin.ai.domain.AIOutput-AIResponse

completionstring

Generated text completion

Text the model generated at this step of the tool loop.

finishReasonstring

Possible Values

STOPLENGTHTOOL_EXECUTIONCONTENT_FILTEROTHER

Finish reason

Why the model stopped generating at this step, such as STOP, LENGTH or TOOL_EXECUTION, when the provider reports it.

idstring

Response identifier

Identifier the provider assigned to this intermediate response.

requestDurationinteger

Request duration

Duration in milliseconds for this individual model call when the provider returns a response ID. It may be null for providers such as Ollama because the local task-level fallback applies only to the top-level requestDuration.

tokenUsage

Token usage

Input, output and total tokens billed for this individual model call, when the provider reports them.

io.kestra.plugin.ai.domain.TokenUsage

inputTokenCountinteger

Input token count

Number of tokens in the prompt sent to the model.

outputTokenCountinteger

Output token count

Number of tokens the model generated in its response.

totalTokenCountinteger

Total token count

Sum of the input and output token counts, which is what the provider bills.

toolExecutionRequestsarray

Tool execution requests

Tool calls the model asked for at this step, before they were executed.

io.kestra.plugin.ai.domain.AIOutput-AIResponse-ToolExecutionRequest

argumentsobject

Tool request arguments

Arguments the model supplied for the tool call.

idstring

Tool execution request identifier

Identifier the model assigned to this tool call, used to match it with its result.

namestring

Tool name

Name of the tool the model asked to call.

jsonOutput object

JSON output

Structured object the model generated. Populated when the response format is JSON, and null otherwise.

outputFiles object

SubTypestring

Output file URIs

Kestra internal storage URIs of the files the task produced, keyed by file name.

requestDuration integer

Request duration

Duration in milliseconds. When the provider returns a response ID, this is the duration of the final model call measured by the timing listener. When the provider does not return a response ID, such as Ollama, this is the end-to-end duration of the surrounding task call and may include guardrail evaluation, memory handling, retrieval, tool execution, and additional model calls.

sources array

Content sources

Text segments the content retrievers injected into the context, with their metadata, so an answer can be traced back to the documents it came from. Empty when no retriever ran.

Definitions

io.kestra.plugin.ai.domain.AIOutput-ContentSource

contentstring

Extracted text segment

Snippet of retrieved text relevant to the query, typically a sentence or paragraph.

metadataobject

Source metadata

Context about where the retrieved content came from, such as a URL, document title or file name.

textOutput string

Text output

Text the model generated. Populated when the response format is TEXT (the default), and null otherwise.

thinking string

Thinking output

The model's internal reasoning text, including chain-of-thought style intermediate steps. Populated only when the model supports thinking and configuration.returnThinking is enabled; null otherwise.

tokenUsage

Token usage

Input, output and total tokens billed for the call, summed across every model call the task made, when the provider reports them.

Definitions

io.kestra.plugin.ai.domain.TokenUsage

inputTokenCountinteger

Input token count

Number of tokens in the prompt sent to the model.

outputTokenCountinteger

Output token count

Number of tokens the model generated in its response.

totalTokenCountinteger

Total token count

Sum of the input and output token counts, which is what the provider bills.

toolExecutions array

Tool executions

Tools the model called while producing the answer, each with its arguments and result, in call order. Empty when no tool was used.

Definitions

io.kestra.plugin.ai.domain.AIOutput-ToolExecution

requestArgumentsobject

Request arguments

Arguments the model passed to the tool, parsed from its request.

requestIdstring

Request ID

Identifier the model assigned to this tool execution request.

requestNamestring

Request name

Name of the tool the model invoked.

resultstring

Result

Value the tool returned, which is fed back to the model.

Metrics

ai.agent.tool.calls counter

Unitcalls

Number of AI tool invocations during agent execution, tagged by tool class name

ai.provider.calls counter

Unitcalls

Number of times a chat model is obtained from a provider, tagged by provider class name

input.token.count counter

Unittoken

Large Language Model (LLM) input token count

output.token.count counter

Unittoken

Large Language Model (LLM) output token count

total.token.count counter

Unittoken

Large Language Model (LLM) total token count

Azure

Leverage Microsoft Azure services within Kestra data workflows.

AICloudDataInfrastructure

TypeSafe

Evaluate content with TypeSafe AI's System One models.

AIData

AI AIAgentCertifiedRun an AI agent with tools

More Plugins in this Category

Azure

TypeSafe

AI AIAgent
Certified
Run an AI agent with tools