ChatCompletion

Chat completion with AI models

Handles chat interactions using AI models (OpenAI, Ollama, Gemini, Anthropic, MistralAI, Deepseek).

yaml
type: "io.kestra.plugin.ai.completion.ChatCompletion"

Examples

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: "{{ kv('GOOGLE_API_KEY') }}"
      modelName: gemini-2.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}}"

Chat Completion with Google Gemini and a WebSearch tool

yaml
id: chat_completion_with_tools
namespace: company.ai

inputs:
  - id: prompt
    type: STRING

tasks:
  - id: chat_completion_with_tools
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      apiKey: "{{ kv('GOOGLE_API_KEY') }}"
      modelName: gemini-2.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}}"
    tools:
      - type: io.kestra.plugin.ai.tool.GoogleCustomWebSearch
        apiKey: "{{ kv('GOOGLE_SEARCH_API_KEY') }}"
        csi: "{{ kv('GOOGLE_SEARCH_CSI') }}"

Extract structured outputs with a JSON schema. Not all model providers support JSON schema; in those cases, you have to specify the schema in the prompt.

yaml
id: structured-output
namespace: company.ai

inputs:
  - id: prompt
    type: STRING
    defaults: |
      Hello, my name is John. I was born on January 1, 2000.

tasks:
  - id: ai-agent
    type: io.kestra.plugin.ai.completion.ChatCompletion
    provider:
      type: io.kestra.plugin.ai.provider.GoogleGemini
      modelName: gemini-2.5-flash
      apiKey: "{{ kv('GEMINI_API_KEY') }}"
    configuration:
      responseFormat:
        type: JSON
        jsonSchema:
          type: object
          properties:
            name:
              type: string
            birth:
              type: string
      messages:
      - type: USER
        content: "{{inputs.prompt}}"

Properties

messages *array

SubType

Chat Messages

The list of chat messages for the current conversation. There can be only one system message, and the last message must be a user message

provider *AmazonBedrock Anthropic AzureOpenAI DashScope DeepSeek GoogleGemini GoogleVertexAI HuggingFace LocalAI MistralAI OciGenAI Ollama OpenAI OpenRouter WorkersAI ZhiPuAI

Language Model Provider

configuration ChatConfiguration

Default {}

Chat configuration

tools A2AAgent AIAgent CodeExecution DockerMcpClient GoogleCustomWebSearch KestraFlow KestraTask SseMcpClient StdioMcpClient StreamableHttpMcpClient TavilyWebSearch

Tools that the LLM may use to augment its response

Outputs

finishReason string

Possible Values

STOPLENGTHTOOL_EXECUTIONCONTENT_FILTEROTHER

Finish reason

intermediateResponses array

SubType

Intermediate responses

jsonOutput object

LLM output for JSON response format

The result of the LLM completion for response format of type JSON, null otherwise.

outputFiles object

SubType string

URIs of the generated files in Kestra's internal storage

requestDuration integer

Request duration in milliseconds

sources array

SubType

Content sources used during RAG retrieval

textOutput string

LLM output for TEXT response format

The result of the LLM completion for response format of type TEXT (default), null otherwise.

thinking string

Model's Thinking Output

Contains the model's internal reasoning or 'thinking' text, if the model supports it and 'returnThinking' is enabled. This may include intermediate reasoning steps, such as chain-of-thought explanations. Null if thinking is not supported, not enabled, or not returned by the model.

tokenUsage TokenUsage

Token usage

toolExecutions array

SubType

Tool executions

Metrics

input.token.count counter

Unit token

Large Language Model (LLM) input token count

output.token.count counter

Unit token

Large Language Model (LLM) output token count

total.token.count counter

Unit token

Large Language Model (LLM) total token count

Definitions

io.kestra.plugin.ai.domain.ChatMessage

content string

type string

Possible Values

SYSTEMAIUSER

Mistral AI Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Model Context Protocol (MCP) Stdio client tool

command *array

SubType string

MCP client command, as a list of command parts

type *object

env object

SubType string

Environment variables

logEvents booleanstring

Default false

Log events

ZhiPu AI Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Default https://open.bigmodel.cn/

API base URL

The base URL for ZhiPu API (defaults to https://open.bigmodel.cn/)

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

maxRetries integerstring

The maximum retry times to request

maxToken integerstring

The maximum number of tokens returned by this request

stops array

SubType string

With the stop parameter, the model will automatically stop generating text when it is about to contain the specified string or token_id

Call a Kestra flow as a tool

type *object

description string

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

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

flowId string

Flow ID of the flow that should be called

inheritLabels booleanstring

Default false

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

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

inputs object

Input values that should be passed to flow's execution

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

labels arrayobject

Labels that should be added to the flow's execution

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

namespace string

Namespace of the flow that should be called

revision integerstring

Revision of the flow that should be called

scheduleDate string

Format date-time

Schedule the flow execution at a later date

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

Model Context Protocol (MCP) SSE client tool

type *object

url *string

URL of the MCP server

headers object

SubType string

Custom headers

Useful, for example, for adding authentication tokens via the Authorization header.

logRequests booleanstring

Default false

Log requests

logResponses booleanstring

Default false

Log responses

timeout string

Format duration

Connection timeout duration

Call a Kestra runnable task as a tool

tasks *array

SubType

List of Kestra runnable tasks

type *object

io.kestra.plugin.ai.domain.AIOutput-ToolExecution

requestArguments object

requestId string

requestName string

result string

Deepseek Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Default https://api.deepseek.com/v1

API base URL

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Call an AI Agent as a tool

description *string

Agent description

The description will be used to instruct the LLM what the tool is doing.

provider *AmazonBedrock Anthropic AzureOpenAI DashScope DeepSeek GoogleGemini GoogleVertexAI HuggingFace LocalAI MistralAI OciGenAI Ollama OpenAI OpenRouter WorkersAI ZhiPuAI

Language model provider

type *object

configuration ChatConfiguration

Default {}

Language model configuration

contentRetrievers GoogleCustomWebSearch SqlDatabaseRetriever TavilyWebSearch

Content retrievers

Some content retrievers, like WebSearch, can also be used as tools. However, when configured as content retrievers, they will always be used, whereas tools are only invoked when the LLM decides to use them.

maxSequentialToolsInvocations integerstring

Maximum sequential tools invocations

name string

Default tool

Agent name

It must be set to a different value than the default in case you want to have multiple agents used as tools in the same task.

systemMessage string

System message

The system message for the language model

tools A2AAgent AIAgent CodeExecution DockerMcpClient GoogleCustomWebSearch KestraFlow KestraTask SseMcpClient StdioMcpClient StreamableHttpMcpClient TavilyWebSearch

Tools that the LLM may use to augment its response

io.kestra.plugin.ai.domain.AIOutput-AIResponse

completion string

Generated text completion

The result of the text completion

finishReason string

Possible Values

STOPLENGTHTOOL_EXECUTIONCONTENT_FILTEROTHER

Finish reason

id string

Response identifier

requestDuration integer

Request duration in milliseconds

tokenUsage TokenUsage

Token usage

toolExecutionRequests array

SubType

Tool execution requests

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

jsonSchema object

JSON Schema (used when type = JSON)

Provide a JSON Schema describing the expected structure of the response. In Kestra flows, define the schema in YAML (it is still a JSON Schema object). Example (YAML):

text

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

Note: Provider support for strict schema enforcement varies. If unsupported, guide the model about the expected output structure via the prompt and validate downstream.

jsonSchemaDescription string

Schema description (optional)

Natural-language description of the schema to help the model produce the right fields. Example: "Classify a customer ticket into category and priority."

type string

Default TEXT

Possible Values

TEXTJSON

Response format type

Specifies how the LLM should return output. Allowed values:

TEXT (default): free-form natural language.
JSON: structured output validated against a JSON Schema.

OpenRouter Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Model Context Protocol (MCP) Docker client tool

image *string

Container image

type *object

apiVersion string

API version

binds array

SubType string

Volume binds

command array

SubType string

MCP client command, as a list of command parts

dockerCertPath string

Docker certificate path

dockerConfig string

Docker configuration

dockerContext string

Docker context

dockerHost string

Docker host

dockerTlsVerify booleanstring

Whether Docker should verify TLS certificates

env object

SubType string

Environment variables

logEvents booleanstring

Default false

Whether to log events

registryEmail string

Container registry email

registryPassword string

Container registry password

registryUrl string

Container registry URL

registryUsername string

Container registry username

Google Custom Search web tool

apiKey *string

API key

csi *string

Custom search engine ID (cx)

type *object

Ollama Model Provider

endpoint *string

Model endpoint

modelName *string

Model name

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Code execution tool using Judge0

apiKey *string

RapidAPI key for Judge0

You can obtain it from the RapidAPI website.

type *object

OpenAI Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Default https://api.openai.com/v1

API base URL

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

SQL Database content retriever using LangChain4j experimental SqlDatabaseContentRetriever. ⚠ IMPORTANT: the database user should have READ-ONLY permissions.

databaseType *string

Possible Values

POSTGRESQLMYSQLH2

Type of database to connect to (PostgreSQL, MySQL, or H2)

Determines the default JDBC driver and connection format.

password *string

Database password

provider *AmazonBedrock Anthropic AzureOpenAI DashScope DeepSeek GoogleGemini GoogleVertexAI HuggingFace LocalAI MistralAI OciGenAI Ollama OpenAI OpenRouter WorkersAI ZhiPuAI

Language model provider

type *object

username *string

Database username

configuration ChatConfiguration

Default {}

Language model configuration

driver string

Optional JDBC driver class name – automatically resolved if not provided.

jdbcUrl string

JDBC connection URL to the target database

maxPoolSize integerstring

Default 2

Maximum number of database connections in the pool

io.kestra.plugin.ai.domain.AIOutput-ContentSource

content string

Extracted text segment

A snippet of text relevant to the user's query, typically a sentence, paragraph, or other discrete unit of text.

metadata object

Source metadata

Key-value pairs providing context about the origin of the content, such as URLs, document titles, or other relevant attributes.

Web search content retriever for Google Custom Search

apiKey *string

API key

csi *string

Custom search engine ID (cx)

type *object

maxResults integerstring

Default 3

Maximum number of results

io.kestra.plugin.ai.domain.ChatConfiguration

logRequests booleanstring

Log LLM requests

If true, prompts and configuration sent to the LLM will be logged at INFO level.

logResponses booleanstring

Log LLM responses

If true, raw responses from the LLM will be logged at INFO level.

maxToken integerstring

Maximum number of tokens the model can generate in the completion (response). This limits the length of the output.

responseFormat ChatConfiguration-ResponseFormat

Response format

Defines the expected output format. Default is plain text. Some providers allow requesting JSON or schema-constrained outputs, but support varies and may be incompatible with tool use. When using a JSON schema, the output will be returned under the key jsonOutput.

returnThinking booleanstring

Return Thinking

Controls whether to return the model's internal reasoning or 'thinking' text, if available. When enabled, the reasoning content is extracted from the response and made available in the AiMessage object. It Does not trigger the thinking process itself—only affects whether the output is parsed and returned.

seed integerstring

Seed

Optional random seed for reproducibility. Provide a positive integer (e.g., 42, 1234). Using the same seed with identical settings produces repeatable outputs.

temperature numberstring

Temperature

Controls randomness in generation. Typical range is 0.0–1.0. Lower values (e.g., 0.2) make outputs more focused and deterministic, while higher values (e.g., 0.7–1.0) increase creativity and variability.

thinkingBudgetTokens integerstring

Thinking Token Budget

Specifies the maximum number of tokens allocated as a budget for internal reasoning processes, such as generating intermediate thoughts or chain-of-thought sequences, allowing the model to perform multi-step reasoning before producing the final output.

thinkingEnabled booleanstring

Enable Thinking

Enables internal reasoning ('thinking') in supported language models, allowing the model to perform intermediate reasoning steps before producing a final output; this is useful for complex tasks like multi-step problem solving or decision making, but may increase token usage and response time, and is only applicable to compatible models.

topK integerstring

Top-K

Limits sampling to the top K most likely tokens at each step. Typical values are between 20 and 100. Smaller values reduce randomness; larger values allow more diverse outputs.

topP numberstring

Top-P (nucleus sampling)

Selects from the smallest set of tokens whose cumulative probability is ≤ topP. Typical values are 0.8–0.95. Lower values make the output more focused, higher values increase diversity.

io.kestra.plugin.ai.domain.TokenUsage

inputTokenCount integer

outputTokenCount integer

totalTokenCount integer

io.kestra.plugin.ai.domain.AIOutput-AIResponse-ToolExecutionRequest

arguments object

Tool request arguments

id string

Tool execution request identifier

name string

Tool name

WorkersAI Model Provider

accountId *string

Account Identifier

Unique identifier assigned to an account

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Azure OpenAI Model Provider

endpoint *string

API endpoint

The Azure OpenAI endpoint in the format: https://{resource}.openai.azure.com/

modelName *string

Model name

type *object

apiKey string

API Key

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientId string

Client ID

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

clientSecret string

Client secret

serviceVersion string

API version

tenantId string

Tenant ID

Google VertexAI Model Provider

endpoint *string

Endpoint URL

location *string

Project location

modelName *string

Model name

project *string

Project ID

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Google Gemini Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

OciGenAI Model Provider

compartmentId *string

OCID of OCI Compartment with the model

modelName *string

Model name

region *string

OCI Region to connect the client to

type *object

authProvider string

OCI SDK Authentication provider

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Call a remote AI agent via the A2A protocol.

description *string

Agent description

The description will be used to instruct the LLM what the tool is doing.

serverUrl *string

Server URL

The URL of the remote agent A2A server

type *object

name string

Default tool

Agent name

It must be set to a different value than the default in case you want to have multiple agents used as tools in the same task.

Model Context Protocol (MCP) SSE client tool

sseUrl *string

SSE URL of the MCP server

type *object

headers object

SubType string

Custom headers

Could be useful, for example, to add authentication tokens via the Authorization header.

logRequests booleanstring

Default false

Log requests

logResponses booleanstring

Default false

Log responses

timeout string

Format duration

Connection timeout duration

WebSearch content retriever for Tavily Search

apiKey *string

API Key

type *object

maxResults integerstring

Default 3

Maximum number of results to return

Anthropic AI Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

maxTokens integerstring

Maximum Tokens

Specifies the maximum number of tokens that the model is allowed to generate in its response.

WebSearch tool for Tavily Search

apiKey *string

Tavily API Key - you can obtain one from the Tavily website

type *object

DashScope (Qwen) Model Provider from Alibaba Cloud

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Default https://dashscope-intl.aliyuncs.com/api/v1

API base URL

text

If you use a model in the China (Beijing) region, you need to replace the URL with: https://dashscope.aliyuncs.com/api/v1,
otherwise use the Singapore region of: "https://dashscope-intl.aliyuncs.com/api/v1.
The default value is computed based on the system timezone.

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

enableSearch booleanstring

Whether the model uses Internet search results for reference when generating text or not

maxTokens integerstring

The maximum number of tokens returned by this request

repetitionPenalty numberstring

Repetition in a continuous sequence during model generation

text

Increasing repetition_penalty reduces the repetition in model generation,
1.0 means no penalty. Value range: (0, +inf)

LocalAI Model Provider

baseUrl *string

API base URL

modelName *string

Model name

type *object

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

Amazon Bedrock Model Provider

accessKeyId *string

AWS Access Key ID

modelName *string

Model name

secretAccessKey *string

AWS Secret Access Key

type *object

baseUrl string

Base URL

Custom base URL to override the default endpoint (useful for local tests, WireMock, or enterprise gateways).

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

modelType string

Default COHERE

Possible Values

COHERETITAN

Amazon Bedrock Embedding Model Type

HuggingFace Model Provider

apiKey *string

API Key

modelName *string

Model name

type *object

baseUrl string

Default https://router.huggingface.co/v1

API base URL

caPem string

CA PEM certificate content

CA certificate as text, used to verify SSL/TLS connections when using custom endpoints.

clientPem string

Client PEM certificate content

PEM client certificate as text, used to authenticate the connection to enterprise AI endpoints.

​Chat​Completion

ChatCompletion