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

Understand how a ModelConfig connects kagent to a LLM provider, and which configurations a Harness can run.

A ModelConfig is a Kubernetes custom resource that names one model at one provider, along with the credentials to reach it. An AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, system prompt, tools, skills, and plugins. It runs only once a Harness accepts it.Learn more references a ModelConfigModelConfigA Kubernetes custom resource naming one model at one provider, along with the credentials to reach it. An AgentTemplate references one by name, and every agent compiled from that template calls the model that it names.Learn more by name in its spec.modelConfig.name field, and every agent compiled from that template calls the model that the ModelConfig names.

The kagent installation creates a default-model-config ModelConfig from the provider API key that you supply at install time, so a first agent needs no extra setup. To use a different provider, a different model, or a different set of credentials, create additional ModelConfigs.

How a ModelConfig reaches an agent

Every ModelConfig shares the same three parts, regardless of the provider that it names.

Credentials come from a Kubernetes Secret in the same namespace as the ModelConfig. The apiKeySecret field names the Secret, and apiKeySecretKey names the key within that Secret. To forward the bearer token from the incoming request to the provider instead, set apiKeyPassthrough: true. A ModelConfig cannot set both apiKeyPassthrough and apiKeySecret. For every ModelConfig field, including its type, default, and validation rules, see the API reference.

How a credential reaches the provider

A credential never enters the agent. kagent compiles the Secret that a ModelConfig names into a destination-scoped binding, and the Agent SubstrateAgent SubstrateThe runtime that kagent runs agents on. It multiplexes many sandboxed Actors onto a smaller pool of pre-started Workers, suspending idle ones to snapshots.Learn more egress gateway fetches the Secret and writes the value into an outgoing HTTP header. Where an SDK requires an API key, the runtime receives the inert placeholder kagent-credential-injected. A compiled revisionRevisionThe compiled, immutable output of one Harness and AgentTemplate pairing, identified by a content digest. An AgentInstance runs the revision it was created from for its whole life, so editing either resource affects only instances created afterward. therefore records the Secret name, key, destination, and header, and never the credential itself.

To rotate a credential, update the Secret. The gateway refreshes its cache within five minutes, so neither a recompile nor a restart is needed.

Each provider carries its credential in the one header that the provider expects, and the destination is the endpoint that the ModelConfig resolves to.

Substrate matches a destination on the exact DNS hostname, without path, port, or scheme. Two credentials that target the same hostname and header are rejected, including a conflict between an agent’s model, a memory embedding model, and an MCP server. Give such origins distinct DNS names. A destination given as an IP address cannot carry an injected credential at all.

Credentials that do not compile

Header injection accepts one shape of credential: a static string. A credential that requires a local signature, a token exchange, or a file mounted into the agent cannot be injected, so kagent rejects the configuration instead of passing the credential to the runtime. The AgentTemplate reports the Compatible condition as False with the reason UnsupportedConfiguration, and kagent compiles no revision from that template. Any AgentInstance that already exists keeps running the last revision that compiled.

A rejected credential reports one of two messages. A credential that cannot be injected reports cannot use gateway header injection, and one that needs a mounted file reports ModelConfig requires volume mounts unsupported by Substrate ActorTemplate.

The Ollama provider is unaffected, because it authenticates with no credential.

The Harness runtime decides which providers are available

A ModelConfig is only half of the decision. The runtime that a HarnessHarnessA Kubernetes custom resource defining how an agent is allowed to run: its runtime, workload image, WorkerPool and snapshot storage, and which AgentTemplates it accepts.Learn more selects also constrains which providers an agent can use, because each runtime integrates a different set.

• The kagent runtime integrates every provider, and the byo runtime integrates the same set, because both compile through the same path.
• The codex runtime integrates only OpenAI and Bedrock.
• The claude runtime integrates only Anthropic and Bedrock.

Integration alone is not enough. A provider whose credential cannot be injected as a header is rejected on every runtime that integrates it, so AnthropicVertexAI, GeminiVertexAI, and SAPAICore run nowhere today. For the alternatives, see Credentials that do not compile.

Neither codex nor claude accepts a ModelConfig that sets defaultHeaders, tls, or apiKeyPassthrough, and each narrows the provider settings it takes. A pair that asks for a provider its runtime does not integrate fails to compile, and the AgentTemplate reports the Compatible condition as False with the reason UnsupportedConfiguration.

For the full matrix, including the per-combination restrictions, see Agent harness.

Use a ModelConfig

Reference the ModelConfig by name in an AgentTemplate. The ModelConfig must be in the same namespace as the AgentTemplate.

apiVersion: kagent.dev/v1alpha3
kind: AgentTemplate
metadata:
  name: my-agent
  namespace: kagent
spec:
  modelConfig:
    name: default-model-config
  systemPrompt: You are a concise, helpful assistant.

Editing a ModelConfig produces a new compiled revisionRevisionThe compiled, immutable output of one Harness and AgentTemplate pairing, identified by a content digest. An AgentInstance runs the revision it was created from for its whole life, so editing either resource affects only instances created afterward. for every AgentTemplate that references it. An AgentInstanceAgentInstanceA running, conversational pairing of a Harness and an AgentTemplate. Unlike the two, it is not a Kubernetes resource: kagent's gRPC API creates it and its database tracks it.Learn more keeps running the revision that it was created from, so create a new AgentInstance to pick up a changed model.