OpenAI

Configuration for the OpenAI model provider.

A provider block with kind = "openai" configures the OpenAI cloud provider. It also works with any OpenAI-compatible endpoint, such as Azure OpenAI or a local proxy, by setting config.base_url.

Fields

Field	Type	Required	runtime()	Default	Description
`kind`	`openai`	yes	no	…	Provider kind.
`models`	array<string \| ModelEntry>	no	no	unset	Models permitted for this provider, with optional model-specific inference settings.
`config`	ProviderConfig	no		unset	API credentials and endpoint settings for this provider.
`params`	InferenceParams	no		unset	Default inference settings for requests to this provider.

When config.api_key is unset, the key is read from the OPENAI_API_KEY environment variable. The agent fails to start when neither is set.

ModelEntry

Field	Type	Required	runtime()	Default	Description
`name`	string	yes	no	…	Model identifier.
`params`	InferenceParams	no		unset	Model-specific inference parameter overrides.

ProviderConfig

Field	Type	Required	runtime()	Default	Description
`api_key`	string	no	yes	unset	OpenAI API key. Wrap in `secret(runtime(...))` to keep it out of build artifacts.
`base_url`	string	no	yes	unset	API base URL. Override to point at a compatible endpoint such as Azure OpenAI or a local proxy.
`headers`	map<string, HeaderValue>	no	yes	`{}`	HTTP headers sent with every model request, keyed by header name. Header names are case insensitive.

HeaderValue

A header value is one of:

Form	Header value
a string	The string, unchanged.
`expression("source")`	The result of the CEL expression `source`, evaluated for each model request.

config {
  headers = {
    "X-Team"      = "platform"
    "X-Tenant-Id" = expression("ctx.tenant_id")
  }
}

For the values an expression can read and how evaluation fails, see Send custom headers.

InferenceParams

The params block sets inference parameter defaults for all models under this provider. All fields are optional and support runtime().

Field	Type	Required	runtime()	Default	Description
`max_tokens`	integer	no	yes	unset	Maximum number of tokens to generate.
`temperature`	number	no	yes	unset	Controls randomness when selecting the next token; higher values produce more varied output.
`top_p`	number	no	yes	unset	Selects tokens from the smallest group whose combined probability reaches this value.
`top_k`	integer	no	yes	unset	Limits the next-token choices to the K most likely tokens.
`stop_sequences`	array<string>	no	yes	unset	Sequences that stop generation.
`frequency_penalty`	number	no	yes	unset	Reduces repetition by penalizing tokens according to how often they have appeared.
`presence_penalty`	number	no	yes	unset	Penalizes tokens that have already appeared to reduce repetition.
`seed`	integer	no	yes	unset	Seed for deterministic sampling.
`provider_params`	object	no	yes	unset	Additional provider-specific inference options sent directly to the API.

Example

agent.acl

provider "openai" {
  kind = "openai"
  models = [
    "gpt-4o-mini",
    {
      name = "gpt-4o"
      params {
        max_tokens  = 8192
        temperature = 0.3
      }
    }
  ]

  config {
    api_key  = secret(runtime("OPENAI_API_KEY"))
    base_url = runtime("OPENAI_BASE_URL", "https://api.openai.com/v1")
  }

  params {
    max_tokens        = 2048
    temperature       = 0.5
    frequency_penalty = 0.1
  }
}

In this example, requests to gpt-4o-mini use the provider-level defaults. Requests to gpt-4o use its own model-level params for max_tokens and temperature, while still inheriting frequency_penalty from the provider-level defaults.

tip

Always wrap API keys in secret(runtime(...)). This prevents the key from appearing in build artifacts and the output of agentc inspect.

Fields

Field

Type

Required

runtime()

Default

Description

kind

openai

yes

…

Provider kind.

models

array<string | ModelEntry>

unset

Models permitted for this provider, with optional model-specific inference settings.

config

ProviderConfig

unset

API credentials and endpoint settings for this provider.

params

InferenceParams

unset

Default inference settings for requests to this provider.

When config.api_key is unset, the key is read from the OPENAI_API_KEY environment variable. The agent fails to start when neither is set.

Field

Type

Required

runtime()

Default

Description

name

string

yes

…

Model identifier.

params

InferenceParams

unset

Model-specific inference parameter overrides.

ProviderConfig

Field

Type

Required

runtime()

Default

Description

api_key

string

yes

unset

OpenAI API key. Wrap in secret(runtime(...)) to keep it out of build artifacts.

base_url

string

yes

unset

API base URL. Override to point at a compatible endpoint such as Azure OpenAI or a local proxy.

headers

map<string, HeaderValue>

yes

{}

HTTP headers sent with every model request, keyed by header name. Header names are case insensitive.

HeaderValue

A header value is one of:

Form

Header value

a string

The string, unchanged.

expression("source")

The result of the CEL expression source, evaluated for each model request.

config {
  headers = {
    "X-Team"      = "platform"
    "X-Tenant-Id" = expression("ctx.tenant_id")
  }
}

For the values an expression can read and how evaluation fails, see Send custom headers.

InferenceParams

The params block sets inference parameter defaults for all models under this provider. All fields are optional and support runtime().

Field

Type

Required

runtime()

Default

Description

max_tokens

integer

yes

unset

Maximum number of tokens to generate.

temperature

number

yes

unset

Controls randomness when selecting the next token; higher values produce more varied output.

top_p

number

yes

unset

Selects tokens from the smallest group whose combined probability reaches this value.

top_k

integer

yes

unset

Limits the next-token choices to the K most likely tokens.

stop_sequences

array<string>

yes

unset

Sequences that stop generation.

frequency_penalty

number

yes

unset

Reduces repetition by penalizing tokens according to how often they have appeared.

presence_penalty

number

yes

unset

Penalizes tokens that have already appeared to reduce repetition.

seed

integer

yes

unset

Seed for deterministic sampling.

provider_params

object

yes

unset

Additional provider-specific inference options sent directly to the API.

Example

agent.acl

provider "openai" {
  kind = "openai"
  models = [
    "gpt-4o-mini",
    {
      name = "gpt-4o"
      params {
        max_tokens  = 8192
        temperature = 0.3
      }
    }
  ]

  config {
    api_key  = secret(runtime("OPENAI_API_KEY"))
    base_url = runtime("OPENAI_BASE_URL", "https://api.openai.com/v1")
  }

  params {
    max_tokens        = 2048
    temperature       = 0.5
    frequency_penalty = 0.1
  }
}

tip

Always wrap API keys in secret(runtime(...)). This prevents the key from appearing in build artifacts and the output of agentc inspect.