AI AIAgent

AI AIAgent
Certified
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.

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

Examples

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') }}"

Properties

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.

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.

modelName*string

Model name

Identifier of the model to call, as named by the provider. Valid values depend on the provider and on whether the model is used for chat, embeddings, or image generation; see the provider's model catalog. 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.

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.

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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 }}"

modelName*string

Model name

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

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 }}"

modelName*string

Model name

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.

typeobject

Possible Values

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

Use Google Vertex AI models

Calls Vertex AI Gemini chat, embeddings, or images using project, location, and endpoint settings. Requires GCP credentials; ensure response formats are supported by the selected model/region.

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
      project: 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 }}"

endpoint*string

Endpoint URL

Vertex AI API endpoint for image and embedding models. Not set by default, in which case the endpoint is derived from location. Must not be set for chat models, which always use Gemini.

location*string

Project location

Google Cloud region hosting the Vertex AI model. No default: this property is required for chat models.

modelName*string

Model name

project*string

Project ID

Google Cloud project ID that owns the Vertex AI resources. No default: this property is required.

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

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.

modelName*string

Model name

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.

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

region*string

OCI region

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

projectId*string

Project ID

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

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).

typeobject

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.

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 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.

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.

modelName*string

Model name

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.

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.

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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

typeobject

Possible Values

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

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.

modelName*string

Model name

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

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

repetitionPenaltynumberstring

Repetition penalty

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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 }}"

modelName*string

Model name

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

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 }}"

modelName*string

Model name

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.

typeobject

Possible Values

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

Use Google Vertex AI models

Calls Vertex AI Gemini chat, embeddings, or images using project, location, and endpoint settings. Requires GCP credentials; ensure response formats are supported by the selected model/region.

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
      project: 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 }}"

endpoint*string

Endpoint URL

Vertex AI API endpoint for image and embedding models. Not set by default, in which case the endpoint is derived from location. Must not be set for chat models, which always use Gemini.

location*string

Project location

Google Cloud region hosting the Vertex AI model. No default: this property is required for chat models.

modelName*string

Model name

project*string

Project ID

Google Cloud project ID that owns the Vertex AI resources. No default: this property is required.

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

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.

modelName*string

Model name

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

region*string

OCI region

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

projectId*string

Project ID

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

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).

typeobject

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.

typeobject

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.

typeobject

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

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.

typeobject

Possible Values

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

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.

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.

typeobject

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.

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.

typeobject

Possible Values

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

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.

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.

typeobject

Possible Values

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

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.

user*string

Database user

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

typeobject

Possible Values

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

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.

namespacestring

Namespace

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

typeobject

Possible Values

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

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.

typeobject

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.

indexNamestring

Defaultembedding-index

Index name

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

typeobject

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.

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

typeobject

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.

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.

typeobject

Possible Values

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

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.

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.

typeobject

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.

maxResultsintegerstring

Default3

Maximum results

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

typeobject

Possible Values

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

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. Connection pooling defaults to size 2.

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.

modelName*string

Model name

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.

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.

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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

typeobject

Possible Values

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

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.

modelName*string

Model name

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

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

repetitionPenaltynumberstring

Repetition penalty

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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 }}"

modelName*string

Model name

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

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 }}"

modelName*string

Model name

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.

typeobject

Possible Values

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

Use Google Vertex AI models

Calls Vertex AI Gemini chat, embeddings, or images using project, location, and endpoint settings. Requires GCP credentials; ensure response formats are supported by the selected model/region.

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
      project: 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 }}"

endpoint*string

Endpoint URL

Vertex AI API endpoint for image and embedding models. Not set by default, in which case the endpoint is derived from location. Must not be set for chat models, which always use Gemini.

location*string

Project location

Google Cloud region hosting the Vertex AI model. No default: this property is required for chat models.

modelName*string

Model name

project*string

Project ID

Google Cloud project ID that owns the Vertex AI resources. No default: this property is required.

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

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.

modelName*string

Model name

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

region*string

OCI region

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

projectId*string

Project ID

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

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.

typeobject

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.

modelName*string

Model name

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.

typeobject

Possible Values

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

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.

modelName*string

Model name

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.

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).

typeobject

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 is passed straight to the connection pool, so it must be set for the retriever to connect, even though it is not enforced by validation. No default.

maxPoolSizeintegerstring

Default2

Maximum connection pool size

Maximum number of concurrent database connections held by the pool. Defaults to 2.

typeobject

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.

maxResultsintegerstring

Default3

Maximum results

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

typeobject

Possible Values

io.kestra.plugin.ai.retriever.TavilyWebSearchio.kestra.plugin.langchain4j.retriever.TavilyWebSearch

maxSequentialToolsInvocations integerstring

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.

name string

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.

systemMessage string

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).

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.

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.

typeobject

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.

typeobject

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.

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).

typeobject

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.

typeobject

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') }}"

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.

typeobject

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.

typeobject

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.

typeobject

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.

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.

typeobject

Possible Values

io.kestra.plugin.ai.tool.SseMcpClientio.kestra.plugin.ai.tool.HttpMcpClientio.kestra.plugin.langchain4j.tool.HttpMcpClient

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.

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.

typeobject

Possible Values

io.kestra.plugin.ai.tool.StdioMcpClientio.kestra.plugin.langchain4j.tool.StdioMcpClient

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') }}

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.

typeobject

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.

typeobject

Possible Values

io.kestra.plugin.ai.tool.TavilyWebSearchio.kestra.plugin.langchain4j.tool.TavilyWebSearch

Metrics

ai.agent.tool.calls counter

Unitcalls

Number of AI tool invocations during nested 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

Huggingface

Tasks that call Hugging Face Inference APIs.

Gemini

Tasks that call Google Gemini models for text, chat, structured outputs, multimodal prompts, and video generation.

AI AIAgentCertifiedExpose a nested AI Agent as a tool

More Plugins in this Category

Huggingface

Gemini

AI AIAgent
Certified
Expose a nested AI Agent as a tool