AI SqlDatabaseRetriever

AI SqlDatabaseRetriever
Certified
Retrieve context from SQL (experimental)

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

yaml
type: io.kestra.plugin.ai.retriever.SqlDatabaseRetriever

Examples

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

Properties

databaseType *string

Possible Values

POSTGRESQLMYSQLH2

Database type

Database engine to connect to: POSTGRESQL, MYSQL or H2. It selects the default JDBC driver when driver is not set. 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.

provider *

Language model provider

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

Definitions

Use Amazon Bedrock models

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

Example

Chat completion with Amazon Bedrock

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

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

accessKeyId*string

AWS Access Key ID

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

secretAccessKey*string

AWS Secret Access Key

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

baseUrlstring

Base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

modelTypestring

DefaultCOHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

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

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.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

maxTokensintegerstring

Maximum Tokens

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

modelNamestring

Model name

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.

apiKeystring

API Key

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

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientIdstring

Client ID

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

clientPemstring

Client PEM certificate content

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

clientSecretstring

Client secret

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

modelNamestring

Model name

serviceVersionstring

API version

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

tenantIdstring

Tenant ID

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

typeobject

Possible Values

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

Use Cohere models

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

Example

Chat completion with Cohere

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

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

apiKey*string

API Key

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

baseUrlstring

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

API base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

typeobject

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.

baseUrlstring

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

API base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

enableSearchbooleanstring

Enable Internet search

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

maxTokensintegerstring

Maximum output tokens

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

modelNamestring

Model name

repetitionPenaltynumberstring

Repetition penalty

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

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.

baseUrlstring

Defaulthttps://api.deepseek.com/v1

API base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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

apiKeystring

Defaultnot-needed

API Key

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

baseUrlstring

Defaulthttp://localhost:12434/engines/v1

API base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

typeobject

Configure ordered model providers for fallback

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

Example

AI agent with ordered provider fallback

yaml
id: ai_agent_with_fallback
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

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

providers*

Providers

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

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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

apiKeystring

API Key

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

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

embeddingModelConfiguration

Embedding model configuration

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

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

maxRetriesintegerstring

Maximum retries

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

outputDimensionalityintegerstring

Output embedding size

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

taskTypestring

Possible Values

RETRIEVAL_QUERYRETRIEVAL_DOCUMENTSEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGQUESTION_ANSWERINGFACT_VERIFICATION

Embedding task type

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

timeoutstring

Request timeout

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

titleMetadataKeystring

Document title metadata key

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

modelNamestring

Model name

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. Authenticates like the GCP plugin: serviceAccount when set, otherwise Application Default Credentials, optionally impersonating impersonatedServiceAccount; ensure response formats are supported by the selected model/region. Tool calls work on Gemini 3 models: the thought_signature returned with each function call is sent back automatically on the following turns. Thinking is left to the model default unless thinkingEnabled or thinkingBudgetTokens is set.

Example

Chat completion with Google Vertex AI

yaml
id: chat_completion
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

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

Chat completion with Google Vertex AI using a service account

yaml
id: chat_completion_service_account
namespace: company.ai

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

location*string

Project location

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

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

endpointstring

Endpoint URL

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

impersonatedServiceAccountstring

Service account to impersonate

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

modelNamestring

Model name

projectstring

Project ID (deprecated)

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

projectIdstring

Project ID

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

scopesarray

SubTypestring

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

OAuth scopes

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

serviceAccountstring

Service account JSON key

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

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.

baseUrlstring

Defaulthttps://router.huggingface.co/v1

API base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelFamilystring

DefaultOPENAI

Possible Values

OPENAIANTHROPIC

Model family

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

modelNamestring

Model name

regionstring

DefaultEU

Possible Values

EUUS

Region

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

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.

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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.

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.

modelNamestring

Model name

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.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

typeobject

Possible Values

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

Compute embeddings in-process with an ONNX model

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

Example

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

yaml
id: onnx_rag
namespace: company.ai

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

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

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

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

Use a BGE model stored as namespace files

yaml
id: onnx_bge_search
namespace: company.ai

inputs:
  - id: query
    type: STRING

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

modelUri*string

ONNX model file

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

tokenizerUri*string

Tokenizer file

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

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

poolingModestring

DefaultMEAN

Possible Values

CLSMEAN

Pooling mode

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

typeobject

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.

baseUrlstring

Defaulthttps://api.openai.com/v1

API base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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.

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.

modelNamestring

Model name

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.

baseUrlstring

Base URL

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

modelNamestring

Model name

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.

baseUrlstring

Defaulthttps://open.bigmodel.cn/

API base URL

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

caPemstring

CA PEM certificate content

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

clientPemstring

Client PEM certificate content

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

maxRetriesintegerstring

Maximum retries

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

maxTokenintegerstring

Maximum output tokens

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

modelNamestring

Model name

stopsarray

SubTypestring

Stop sequences

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

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.

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.

driver string

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.

jdbcUrl string

JDBC URL

JDBC connection URL of the database the model queries. It must be set for the retriever to connect, even though it is not enforced by validation. Each query opens its own connection, so the connect timeout is the driver's: PostgreSQL gives up after 10 seconds by default, while other drivers may wait for the OS TCP timeout unless the URL sets one (for example connectTimeout=30000 for MySQL, in milliseconds). No default.

Metrics

ai.provider.calls counter

Unitcalls

Number of times a chat model is obtained from a provider, tagged by provider class name