openai_chat_completion

Generates responses to messages in a chat conversation, using the OpenAI API and external tools.

This processor sends a user prompt to the OpenAI API, where the specified large language model generates a response using all available context, including data supplied by external tools. By default the entire message payload is submitted as the prompt unless you customize the prompt field.

# Config fields, showing default values
processor:
  label: ""
  openai_chat_completion:
    server_address: https://api.openai.com/v1
    api_key: "" # No default (required)
    model: "" # No default (required)
    prompt: ""
    system_prompt: ""
    history: ""
    image: ""
    max_tokens: 0
    temperature: 0
    user: ""
    top_p: 0
    seed: 0
    stop: []
    presence_penalty: 0
    frequency_penalty: 0
    response_format: text
    json_schema:
      name: "" # No default (required)
      description: ""
      schema: "" # No default (required)
    schema_registry:
      url: "" # No default (required)
      subject: "" # No default (required)
      refresh_interval: ""
      name_prefix: schema_registry_id_
      basic_auth:
        enabled: false
        username: ""
        password: ""
      oauth:
        enabled: false
        consumer_key: ""
        consumer_secret: ""
        access_token: ""
        access_token_secret: ""
      jwt:
        enabled: false
        private_key_file: ""
        signing_method: ""
        claims: {}
        headers: {}
      tls:
        skip_cert_verify: false
        enable_renegotiation: false
        root_cas: ""
        root_cas_file: ""
        client_certs:
          - cert: ""
            cert_file: ""
            key: ""
            key_file: ""
            password: ""
    tools:
      - name: ""
        description: ""
        parameters:
          properties: {}
          required: []
        processors: []

Examples

Summarize each message
Structured JSON output

Send each message payload to a model with a system prompt and replace it with the generated summary.

processor:
  openai_chat_completion:
    server_address: https://api.openai.com/v1
    api_key: "${OPENAI_API_KEY}"
    model: gpt-4o
    system_prompt: "You are a helpful assistant that summarizes log data in one sentence."

Constrain the response to a JSON schema so the model returns a predictable structured object.

processor:
  openai_chat_completion:
    api_key: "${OPENAI_API_KEY}"
    model: gpt-4o-mini
    prompt: "${! content() }"
    response_format: json_schema
    json_schema:
      name: sentiment
      description: Classifies the sentiment of the input text.
      schema: |
        {
          "type": "object",
          "properties": {
            "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] }
          },
          "required": ["sentiment"]
        }

Fields

`server_address`

The OpenAI API endpoint that the processor sends requests to. Set this to target a different OpenAI-compatible service.

Type: string
Default: "https://api.openai.com/v1"

`api_key`

The API key for the OpenAI API. :::warning Secret This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info. :::

Type: string

`model`

The name of the OpenAI model to use, for example gpt-4o or gpt-4o-mini.

Type: string

`prompt`

The user prompt to generate a response for. By default the processor submits the entire message payload as a string. This field supports interpolation functions.

Type: string

`system_prompt`

The system prompt to submit along with the user prompt. This field supports interpolation functions.

Type: string

`history`

Includes messages from a prior conversation. Use a Bloblang query to create an array of objects in the form [{"role":"user","content":"<text>"},{"role":"assistant","content":"<text>"}], where role is the sender of each message (system, user, or assistant) and content is the message text.

Type: string

`image`

An optional image to submit along with the prompt. The result of the Bloblang mapping must be a byte array.

Type: string

`max_tokens`

The maximum number of tokens to generate for the chat completion.

Type: int

`temperature`

The sampling temperature, between 0 and 2. Higher values such as 0.8 make the output more random, while lower values such as 0.2 make it more focused and deterministic. Set a value for either this field or top_p, but not both.

Type: float

`user`

A unique identifier representing the end user generating the prompt, which can help OpenAI monitor and detect abuse of the platform. This field supports interpolation functions.

Type: string

`top_p`

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. For example, a value of 0.1 means only the tokens comprising the top 10% probability mass are considered. Set a value for either this field or temperature, but not both.

Type: float

`seed`

When set to a specific number, the processor attempts to generate consistent responses for requests that use the same prompt, seed, and parameters.

Type: int

`stop`

Up to four sequences where the model stops generating further tokens. When the model encounters a stop sequence it stops generating text and returns the response.

Type: array

`presence_penalty`

A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.

Type: float

`frequency_penalty`

A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.

Type: float

`response_format`

The output format for the configured model. Options are text, json, and json_schema. When set to json_schema, you must also configure a json_schema or schema_registry.

Type: string
Default: "text"

`json_schema`

The JSON schema the model uses when generating responses in json_schema format.

Type: object

`json_schema.name`

The name of the JSON schema.

Type: string

`json_schema.description`

An optional description that helps the model understand the purpose of the schema.

Type: string

`json_schema.schema`

The JSON schema for the model to use when generating the output.

Type: string

`schema_registry`

A schema registry to dynamically load schemas for model responses in json_schema format. Schemas must be in JSON format.

Type: object

`schema_registry.url`

The base URL of the schema registry service.

Type: string

`schema_registry.subject`

The subject name used to fetch the schema from the schema registry.

Type: string

`schema_registry.refresh_interval`

How frequently to poll the schema registry for updates. When not set, the schema does not refresh automatically.

Type: string

`schema_registry.name_prefix`

A prefix added to the schema registry name. The schema ID is appended as a suffix to form the complete name.

Type: string
Default: "schema_registry_id_"

`schema_registry.basic_auth`

Allows you to specify basic authentication.

Type: object

`schema_registry.basic_auth.enabled`

Whether to use basic authentication in requests.

Type: bool
Default: false

`schema_registry.basic_auth.username`

A username to authenticate as.

Type: string
Default: ""

`schema_registry.basic_auth.password`

A password to authenticate with. :::warning Secret This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info. :::

Type: string
Default: ""

`schema_registry.oauth`

Allows you to specify open authentication via OAuth version 1.

Type: object

`schema_registry.oauth.enabled`

Whether to use OAuth version 1 in requests.

Type: bool
Default: false

`schema_registry.oauth.consumer_key`

A value used to identify the client to the service provider.

Type: string
Default: ""

`schema_registry.oauth.consumer_secret`

A secret used to establish ownership of the consumer key. :::warning Secret This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info. :::

Type: string
Default: ""

`schema_registry.oauth.access_token`

A value used to gain access to the protected resources on behalf of the user.

Type: string
Default: ""

`schema_registry.oauth.access_token_secret`

A secret provided in order to establish ownership of a given access token. :::warning Secret This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info. :::

Type: string
Default: ""

`schema_registry.jwt`

Allows you to specify JWT authentication.

Type: object

`schema_registry.jwt.enabled`

Whether to use JWT authentication in requests.

Type: bool
Default: false

`schema_registry.jwt.private_key_file`

A file with the PEM encoded via PKCS1 or PKCS8 as private key.

Type: string
Default: ""

`schema_registry.jwt.signing_method`

A method used to sign the token such as RS256, RS384, RS512 or EdDSA.

Type: string
Default: ""

`schema_registry.jwt.claims`

A value used to identify the claims that issued the JWT.

Type: object
Default: {}

`schema_registry.jwt.headers`

Add optional key/value headers to the JWT.

Type: object
Default: {}

`schema_registry.tls`

Custom TLS settings can be used to override system defaults.

Type: object

`schema_registry.tls.skip_cert_verify`

Whether to skip server side certificate verification.

Type: bool
Default: false

`schema_registry.tls.enable_renegotiation`

Whether to allow the remote server to repeatedly request renegotiation. Enable this option if you're seeing the error message local error: tls: no renegotiation.

Type: bool
Default: false

`schema_registry.tls.root_cas`

An optional root certificate authority to use. This is a string, representing a certificate chain from the parent trusted root certificate, to possible intermediate signing certificates, to the host certificate. :::warning Secret This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info. :::

Type: string
Default: ""

`schema_registry.tls.root_cas_file`

An optional path of a root certificate authority file to use. This is a file, often with a .pem extension, containing a certificate chain from the parent trusted root certificate, to possible intermediate signing certificates, to the host certificate.

Type: string
Default: ""

`schema_registry.tls.client_certs`

A list of client certificates to use. For each certificate either the fields cert and key, or cert_file and key_file should be specified, but not both.

Type: array
Default: []

`schema_registry.tls.client_certs[].cert`

A plain text certificate to use.

Type: string
Default: ""

`schema_registry.tls.client_certs[].cert_file`

The path of a certificate to use.

Type: string
Default: ""

`schema_registry.tls.client_certs[].key`

A plain text certificate key to use. :::warning Secret This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info. :::

Type: string
Default: ""

`schema_registry.tls.client_certs[].key_file`

The path of a certificate key to use.

Type: string
Default: ""

`schema_registry.tls.client_certs[].password`

A plain text password for when the private key is password encrypted in PKCS#1 or PKCS#8 format. The obsolete pbeWithMD5AndDES-CBC algorithm is not supported for the PKCS#8 format. Warning: Since it does not authenticate the ciphertext, it is vulnerable to padding oracle attacks that can let an attacker recover the plaintext. :::warning Secret This field contains sensitive information that usually shouldn't be added to a config directly, read our secrets page for more info. :::

Type: string
Default: ""

`tools`

External tools the model can invoke, such as functions, APIs, or web browsing. Build a series of processors that define these tools, and the model chooses when to invoke them to help answer a prompt. To use no external tools, provide an empty array.

Type: array

`tools[].name`

The name of this tool.

Type: string

`tools[].description`

A description of this tool. The model uses this to decide whether the tool should be used.

Type: string

`tools[].parameters`

The parameters the model needs to provide in order to invoke this tool.

Type: object

`tools[].parameters.properties`

The properties for the tool's input data.

Type: object

`tools[].parameters.required`

The list of required parameters.

Type: array
Default: []

`tools[].processors`

The pipeline of processors to execute when the model uses this tool.

Type: array
Default: []

Examples
Fields

Examples​

Fields​

server_address​

api_key​

model​

prompt​

system_prompt​

history​

image​

max_tokens​

temperature​

user​

top_p​

seed​

stop​

presence_penalty​

frequency_penalty​

response_format​

json_schema​

json_schema.name​

json_schema.description​

json_schema.schema​

schema_registry​

schema_registry.url​

schema_registry.subject​

schema_registry.refresh_interval​

schema_registry.name_prefix​

schema_registry.basic_auth​

schema_registry.basic_auth.enabled​

schema_registry.basic_auth.username​

schema_registry.basic_auth.password​

schema_registry.oauth​

schema_registry.oauth.enabled​

schema_registry.oauth.consumer_key​

schema_registry.oauth.consumer_secret​

schema_registry.oauth.access_token​

schema_registry.oauth.access_token_secret​

schema_registry.jwt​

schema_registry.jwt.enabled​

schema_registry.jwt.private_key_file​

schema_registry.jwt.signing_method​

schema_registry.jwt.claims​

schema_registry.jwt.headers​

schema_registry.tls​

schema_registry.tls.skip_cert_verify​

schema_registry.tls.enable_renegotiation​

schema_registry.tls.root_cas​

schema_registry.tls.root_cas_file​

schema_registry.tls.client_certs​

schema_registry.tls.client_certs[].cert​

schema_registry.tls.client_certs[].cert_file​

schema_registry.tls.client_certs[].key​

schema_registry.tls.client_certs[].key_file​

schema_registry.tls.client_certs[].password​

tools​

tools[].name​

tools[].description​

tools[].parameters​

tools[].parameters.properties​

tools[].parameters.required​

tools[].processors​

Examples

Fields

`server_address`

`api_key`

`model`

`prompt`

`system_prompt`

`history`

`image`

`max_tokens`

`temperature`

`user`

`top_p`

`seed`

`stop`

`presence_penalty`

`frequency_penalty`

`response_format`

`json_schema`

`json_schema.name`

`json_schema.description`

`json_schema.schema`

`schema_registry`

`schema_registry.url`

`schema_registry.subject`

`schema_registry.refresh_interval`

`schema_registry.name_prefix`

`schema_registry.basic_auth`

`schema_registry.basic_auth.enabled`

`schema_registry.basic_auth.username`

`schema_registry.basic_auth.password`

`schema_registry.oauth`

`schema_registry.oauth.enabled`

`schema_registry.oauth.consumer_key`

`schema_registry.oauth.consumer_secret`

`schema_registry.oauth.access_token`

`schema_registry.oauth.access_token_secret`

`schema_registry.jwt`

`schema_registry.jwt.enabled`

`schema_registry.jwt.private_key_file`

`schema_registry.jwt.signing_method`

`schema_registry.jwt.claims`

`schema_registry.jwt.headers`

`schema_registry.tls`

`schema_registry.tls.skip_cert_verify`

`schema_registry.tls.enable_renegotiation`

`schema_registry.tls.root_cas`

`schema_registry.tls.root_cas_file`

`schema_registry.tls.client_certs`

`schema_registry.tls.client_certs[].cert`

`schema_registry.tls.client_certs[].cert_file`

`schema_registry.tls.client_certs[].key`

`schema_registry.tls.client_certs[].key_file`

`schema_registry.tls.client_certs[].password`

`tools`

`tools[].name`

`tools[].description`

`tools[].parameters`

`tools[].parameters.properties`

`tools[].parameters.required`

`tools[].processors`