xAI

Configuration for the xAI model provider.

A provider block with kind = "xai" configures the xAI cloud provider, which serves the Grok family of models.

Fields

Field	Type	Required	runtime()	Default	Description
`kind`	`xai`	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 key used to connect to 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 XAI_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	xAI API key. Wrap in `secret(runtime(...))` to keep it out of build artifacts.
`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.
`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	Provider-specific parameters passed directly to the API.

note

top_k is not part of the OpenAI-compatible wire format that xAI uses. Setting it has no effect and it will be ignored.

Known model identifiers

Model	Identifier
Grok 4	`grok-4`
Grok 3	`grok-3`
Grok 3 Fast	`grok-3-fast`
Grok 3 Mini	`grok-3-mini`
Grok 3 Mini Fast	`grok-3-mini-fast`

Example

agent.acl

provider "xai" {
  kind = "xai"
  models = [
    "grok-3-mini",
    {
      name = "grok-4"
      params {
        max_tokens  = 16384
        temperature = 0.6
      }
    }
  ]

  config {
    api_key = secret(runtime("XAI_API_KEY"))
  }

  params {
    max_tokens  = 4096
    temperature = 0.5
  }
}

agent "assistant" {
  graph {
    type = "react"
  }

  model {
    provider = "xai"
    name     = "grok-3-mini"
  }
}

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

xai

yes

…

Provider kind.

models

array<string | ModelEntry>

unset

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

config

ProviderConfig

unset

API key used to connect to 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 XAI_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.

Field

Type

Required

runtime()

Default

Description

api_key

string

yes

unset

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

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.

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

Provider-specific parameters passed directly to the API.

note

top_k is not part of the OpenAI-compatible wire format that xAI uses. Setting it has no effect and it will be ignored.

Model

Identifier

Grok 4

grok-4

Grok 3

grok-3

Grok 3 Fast

grok-3-fast

Grok 3 Mini

grok-3-mini

Grok 3 Mini Fast

grok-3-mini-fast

Example

agent.acl

provider "xai" {
  kind = "xai"
  models = [
    "grok-3-mini",
    {
      name = "grok-4"
      params {
        max_tokens  = 16384
        temperature = 0.6
      }
    }
  ]

  config {
    api_key = secret(runtime("XAI_API_KEY"))
  }

  params {
    max_tokens  = 4096
    temperature = 0.5
  }
}

agent "assistant" {
  graph {
    type = "react"
  }

  model {
    provider = "xai"
    name     = "grok-3-mini"
  }
}

tip

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