For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Learn how to configure OpenAI models in kagent.

Configuring OpenAI

1. Create a Kubernetes Secret that stores the API key, replace <your_api_key> with an actual API key:

export OPENAI_API_KEY=<your_api_key>
kubectl create secret generic kagent-openai -n kagent --from-literal OPENAI_API_KEY=$OPENAI_API_KEY

2. Create a ModelConfig resource that references the secret and key name. For standard models such as GPT-4 and GPT-3.5, kagent automatically configures the appropriate model capabilities.

apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
  name: default-model-config
  namespace: kagent
spec:
  apiKeySecret: kagent-openai
  apiKeySecretKey: OPENAI_API_KEY
  model: gpt-4o-mini
  provider: OpenAI
  openAI: {}

3. Apply the resource to the cluster.

Once the resource is applied, you can select the model from the Model dropdown in the UI when creating or updating agents.

Reasoning effort

For OpenAI reasoning models (o-series, GPT-5), you can control how many reasoning tokens the model generates before producing a response with the openAI.reasoningEffort field. Valid values are none, minimal, low, medium, high, and xhigh.

For models that require reasoning to be explicitly disabled (such as some GPT-5 variants), set reasoningEffort: none. For standard models that do not support it, omit the field.

spec:
  provider: OpenAI
  model: o3
  openAI:
    reasoningEffort: medium

Max completion tokens

For OpenAI reasoning models (o-series, GPT-5), use openAI.maxCompletionTokens to cap the total number of tokens the model can generate in a response, including both visible output tokens and reasoning tokens.

Note: Do not use openAI.maxTokens for reasoning models. OpenAI deprecated max_tokens for the Chat Completions API, and reasoning models reject it outright with a 400 error. Use maxCompletionTokens instead.

spec:
  provider: OpenAI
  model: o3
  openAI:
    reasoningEffort: medium
    maxCompletionTokens: 16000

For standard (non-reasoning) models and OpenAI-compatible endpoints, openAI.maxTokens continues to work as before. The two fields are independent.

Responses API

By default, kagent uses the Chat Completions API. To switch to the OpenAI Responses API instead, set openAI.apiFormat: responses on the ModelConfig. This is also compatible with gateways such as AgentGateway that expose the Responses API.

spec:
  provider: OpenAI
  model: gpt-4o
  openAI:
    apiFormat: responses

Omit apiFormat (or set it to chatCompletions) to continue using Chat Completions. Native tool use and stateful Responses API chaining are not yet supported.