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 revision records the Secret name and key rather than the value, so a rotation needs no recompile. The gateway caches what it fetches, so allow a short delay before the new value is in use.

When a request is made to a provider, the gateway puts the credential in the header that the provider expects. 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 when it points at a local daemon, which authenticates with no credential. An Ollama Cloud model reaches api.ollama.com with an API key, and that key is injected as a header like any other. For when a model routes to the cloud, see Ollama.

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.

A provider is available only when the runtime integrates it and the egress gateway can inject its credential as a header. The kagent and byo runtimes integrate AnthropicVertexAI, GeminiVertexAI, and SAPAICore, but the gateway cannot inject a Google service account key or a set of OAuth2 client credentials. kagent 1.0 rejects a ModelConfig that names any of the three, on every runtime, so no agent can reach these providers at all. 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.