OpenAI Responses

OpenAI Responses

Certified

Call OpenAI Responses with tools

Uses the Responses API for chat, tool calls, and structured text output. Supports web/file search and function tools, optional JSON Schema formatting, continuation via previousResponseId, and persistence enabled by default. See the Responses 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 }}"

Pass a list of messages with different roles as input instead of a single string. Each message holds a content list where every entry declares its type (e.g., input_text) and value.

yaml
id: openai_roles
namespace: company.team

tasks:
  - id: openai
    type: io.kestra.plugin.openai.Responses
    apiKey: "{{ secret('OPENAI_API_KEY') }}"
    model: gpt-4.1-mini
    input:
      - role: system
        content:
          - type: input_text
            text: "Only respond with a single sentence"
      - role: user
        content:
          - type: input_text
            text: "Explain what is Kestra"

  - id: log
    type: io.kestra.plugin.core.log.Log
    message: "{{ outputs.openai.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

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

Use a stored prompt template and MCP server with OpenAI's Responses API.

yaml
id: prompt_id_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-5-mini
    input: "Summarize the Pull Requests assigned to me for review."
    promptId: "pmpt_XYZ"
    promptVariables:
      repo: "kestra-io/kestra"
      username: "your.name"
    tools:
      - type: mcp
        server_label: GitHub_MCP
        server_description: GitHub MCP Server
        server_url: "https://api.githubcopilot.com/mcp/"
        require_approval: never
        authorization: "{{ secret('GITHUB_PERSONAL_ACCESS_TOKEN') }}"
        headers:
          X-MCP-Readonly: "true"
Properties

OpenAI API key

Input payload

The conversation input. Accepts two formats:

  • String: a single text prompt (input: "Explain what is Kestra"). The plugin sends it as one user message.
  • List: a list of message objects for multi-turn or multi-role conversations. Each item has a role (user, system, assistant, or developer) and a content list. Each content entry has a type (usually input_text) and the corresponding value (text).

Example list format: 

input: 
  - role: system
    content: 
      - type: input_text
        text: "Only respond with a single sentence"
  - role: user
    content: 
      - type: input_text
        text: "Explain what is Kestra"

See the Responses input docs.

Model ID

Required OpenAI model (e.g., gpt-4.1 or gpt-4o); see the model docs.

Default10

The maximum number of seconds to wait for a response

Max output tokens

Caps response tokens; leave unset to use OpenAI defaults.

Parallel tool calls

Whether tools may run in parallel; uses provider default when unset.

Reference (ref) of the pluginDefaults to apply to this task.

Previous response ID

Continue a conversation by supplying a prior response_id; requires prior persistence.

Enable prompt caching

When true, enables OpenAI prompt caching to reduce latency and cost for repeated prefixes. See the prompt caching docs.

Reference to a prompt stored in OpenAI Platform (optional)

If provided, the Platform-managed prompt will be used, with input added as a user input.

SubTypestring

Key-value pairs for substitution in the stored prompt (optional)

Ignored unless promptId is provided. Values will replace placeholders in the stored prompt.

Reasoning configuration

Optional reasoning options map passed to the API.

Defaulttrue

Persist response history

Defaults to true to store conversation in OpenAI; set false for ephemeral exchanges.

Default1.0

Sampling temperature (0-2)

Default 1.0; higher values increase randomness.

Text response config

Optional map for text output settings (e.g., json_schema formatted responses).

Possible Values
NONEAUTOREQUIRED

Tool choice

NONE disables tools, AUTO (default) lets the model decide, REQUIRED forces a tool call when tools are provided.

SubTypeobject

Enabled tools

List of tool objects (web_search, file_search, function, etc.) sent to the API.

Top-p nucleus sampling (0-1)

Lower values limit candidate tokens. Omit to let OpenAI apply its server-side default. Must be omitted for reasoning models (e.g., gpt-5.2+, gpt-5.4) which reject top_p.

A unique identifier representing your end-user

Generated text

Raw API response

Full response as a map for downstream processing.

Response ID

SubTypestring

Sources

URLs returned via web/file search annotations.

More Plugins in this Category

Weaviate
Weaviate

Tasks that manage and query vectors in Weaviate.

DataAI

4 tasks

2 blueprints

Timefold
Timefold

Timefold plugin for Kestra

DataAI

2 tasks