Interact with LLMs using OpenAI's Responses API with built-in tools and structured output.

For more information, refer to the OpenAI Responses API docs.

yaml
type: "io.kestra.plugin.openai.responses"

Send a simple text prompt to OpenAI and output the result as text.

yaml
id: simple_text
namespace: company.team

inputs:
  - id: prompt
    type: STRING
    defaults: Explain what is Kestra in 3 sentences

tasks:
  - id: explain
    type: io.kestra.plugin.openai.Responses
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4.1-mini
    input: "{{ inputs.prompt }}"

  - id: log
    type: io.kestra.plugin.core.log.Log
    message: "{{ outputs.explain.outputText }}"

Use the OpenAI's web-search tool to find recent trends in workflow orchestration.

yaml
id: web_search
namespace: company.team

inputs:
  - id: prompt
    type: STRING
    defaults: List recent trends in workflow orchestration

tasks:
  - id: trends
    type: io.kestra.plugin.openai.Responses
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4.1-mini
    input: "{{ inputs.prompt }}"
    toolChoice: REQUIRED
    tools:
      - type: web_search_preview

  - id: log
    type: io.kestra.plugin.core.log.Log
    message: "{{ outputs.trends.outputText }}"

Use the OpenAI's web-search tool to get a daily summary of local news via email.

yaml
id: fetch_local_news
namespace: company.team

inputs:
  - id: prompt
    type: STRING
    defaults: Summarize top 5 news from my region

tasks:
  - id: news
    type: io.kestra.plugin.openai.Responses
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4.1-mini
    input: "{{ inputs.prompt }}"
    toolChoice: REQUIRED
    tools:
      - type: web_search_preview
        search_context_size: low  # optional; low, medium, high
        user_location:
          type: approximate # OpenAI doesn't provide other types atm, and it cannot be omitted
          city: Berlin
          region: Berlin
          country: DE

  - id: mail
    type: io.kestra.plugin.notifications.mail.MailSend
    from: your_email
    to: your_email
    username: your_email
    host: mail.privateemail.com
    port: 465
    password: "{{ secret('EMAIL_PASSWORD') }}"
    sessionTimeout: 6000
    subject: Daily News Summary
    htmlTextContent: "{{ outputs.news.outputText }}"

triggers:
  - id: schedule
    type: io.kestra.plugin.core.trigger.Schedule
    cron: "0 9 * * *"

Use the OpenAI's function-calling tool to respond to a customer review and determine urgency of response.

yaml
id: responses_functions
namespace: company.team

inputs:
  - id: prompt
    type: STRING
    defaults: I love your product and would purchase it again!

tasks:
  - id: openai
    type: io.kestra.plugin.openai.Responses
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4.1-mini
    input: "{{ inputs.prompt }}"
    toolChoice: AUTO
    tools:
      - type: function
        name: respond_to_review
        description: >-
          Given the customer product review provided as input, determine how
          urgently a reply is required and then provide suggested response text.
        strict: true
        parameters:
          type: object
          required:
            - response_urgency
            - response_text
          properties:
            response_urgency:
              type: string
              description: >-
                How urgently this customer review needs a reply. Bad reviews must
                be addressed immediately before anyone sees them. Good reviews
                can wait until later.
              enum:
                - reply_immediately
                - reply_later
            response_text:
              type: string
              description: The text to post online in response to this review.
          additionalProperties: false

  - id: output
    type: io.kestra.plugin.core.output.OutputValues
    values:
      urgency: "{{ fromJson(outputs.openai.outputText).response_urgency }}"
      response: "{{ fromJson(outputs.openai.outputText).response_text }}"

Run a stateful chat with OpenAI using the Responses API.

yaml
id: stateful_chat
namespace: company.team

inputs:
  - id: user_input
    type: STRING
    defaults: How can I get started with Kestra as a microservice developer?

  - id: reset_conversation
    type: BOOL
    defaults: false

tasks:
  - id: maybe_reset_conversation
    runIf: "{{ inputs.reset_conversation }}"
    type: io.kestra.plugin.core.kv.Delete
    key: "RESPONSE_ID"

  - id: chat_request
    type: io.kestra.plugin.openai.Responses
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4.1
    previousResponseId: "{{ kv('RESPONSE_ID', errorOnMissing=false) }}"
    input:
      - role: user
        content:
          - type: input_text
            text: "{{ inputs.user_input }}"

  - id: store_response
    type: io.kestra.plugin.core.kv.Set
    key: "RESPONSE_ID"
    value: "{{ outputs.chat_request.responseId }}"

  - id: output_log
    type: io.kestra.plugin.core.log.Log
    message: "Response: {{ outputs.chat_request.outputText }}"

Return a structured output with nutritional information about a food item using OpenAI's Responses API.

yaml
id: structured_output_demo
namespace: company.team

inputs:
  - id: food
    type: STRING
    defaults: Avocado

tasks:
  - id: generate_structured_response
    type: io.kestra.plugin.openai.Responses
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4.1-mini
    input: "Fill in nutrients information for the following food: {{ inputs.food }}"
    text:
      format:
        type: json_schema
        name: food_macronutrients
        schema:
          type: object
          properties:
            food:
              type: string
              description: The name of the food or meal.
            macronutrients:
              type: object
              description: Macro-nutritional content of the food.
              properties:
                carbohydrates:
                  type: number
                  description: Amount of carbohydrates in grams.
                proteins:
                  type: number
                  description: Amount of proteins in grams.
                fats:
                  type: number
                  description: Amount of fats in grams.
              required:
                - carbohydrates
                - proteins
                - fats
              additionalProperties: false
            vitamins:
              type: object
              description: Specific vitamins present in the food.
              properties:
                vitamin_a:
                  type: number
                  description: Amount of Vitamin A in micrograms.
                vitamin_c:
                  type: number
                  description: Amount of Vitamin C in milligrams.
                vitamin_d:
                  type: number
                  description: Amount of Vitamin D in micrograms.
                vitamin_e:
                  type: number
                  description: Amount of Vitamin E in milligrams.
                vitamin_k:
                  type: number
                  description: Amount of Vitamin K in micrograms.
              required:
                - vitamin_a
                - vitamin_c
                - vitamin_d
                - vitamin_e
                - vitamin_k
              additionalProperties: false
          required:
            - food

OpenAI API key

Input to the prompt's context window

Model name to use (e.g., gpt-4o)

See the OpenAI model's documentation

Default 10

The maximum number of seconds to wait for a response.

Maximum tokens in the response

Allow parallel tool execution

ID of previous response to continue conversation

SubType string

Reasoning configuration

Configuration for model reasoning process

Default true

Whether to persist response and chat history

If true (default), persists in OpenAI's storage

Default 1.0

Sampling temperature (0-2)

Text response configuration

Configure the format of the model's text response

Possible Values

NONEAUTOREQUIRED

Controls which tool is called by the model

none: no tools, auto: model picks, required: must use tools

SubType

List of built-in tools to enable

e.g., web_search, file_search, function calling

Default 1.0

Nucleus sampling parameter (0-1)

A unique identifier representing your end-user.

The generated text output

Full API response for advanced use

ID of the persisted response

SubType string

List of sources (for web/file search)