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

Configure kagent to use Anthropic Claude models by creating a ModelConfig for the Anthropic provider.

The Anthropic provider calls the Anthropic API directly.

Create the ModelConfig

1. Save your Anthropic API key as an environment variable.

   export ANTHROPIC_API_KEY=<your_api_key>

2. Create a Kubernetes Secret that stores the API key. Create it in the same namespace as the AgentTemplates that use it, such as kagent.

   kubectl create secret generic kagent-anthropic -n kagent --from-literal ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY

3. Create a ModelConfig that references the Secret.

   kubectl apply -f - <<EOF
   apiVersion: api.kagent.dev/v1alpha3
   kind: ModelConfig
   metadata:
     name: anthropic-model-config
     namespace: kagent
   spec:
     apiKeySecret: kagent-anthropic
     apiKeySecretKey: ANTHROPIC_API_KEY
     model: claude-sonnet-5
     provider: Anthropic
     anthropic: {}
   EOF

   Field	Description
   apiKeySecret	The name of the Kubernetes Secret that stores the API key, in the same namespace as this ModelConfig.
   apiKeySecretKey	The key within that Secret that holds the API key.
   model	The model to use. For the available models, see the Anthropic model docs.
   provider	The provider to use, Anthropic.
   anthropic	Settings that only the Anthropic provider takes. An empty block is valid.

Anthropic provider settings

The anthropic block takes the following optional settings. For every field, including its type, default, and validation rules, see the API reference.

Prompt caching

An agent that calls a model many times for one task resends the same prefix every time, including the tool definitions, the system prompt, and the turns already taken. When promptCaching is true, kagent marks that prefix with cache_control breakpoints, and Anthropic bills a later request that reuses it at a fraction of the normal input price. Because the conversation breakpoint moves with every turn, each call in an agent loop reads the whole previous history from the cache and writes only the new turn.

Enable the field wherever a tool-using agent makes many model calls per task against a stable system prompt and tool set. Without it, the full history is billed as fresh input on every call.

spec:
  anthropic:
    promptCaching: true
    cacheTTL: "5m"

Two properties of Anthropic’s pricing decide whether caching reduces cost. Neither one produces an error or a warning when caching ends up costing more.

• A cache write costs more than ordinary input. A prefix must be read at least once before the saving on reads exceeds the premium charged on the write, so caching a prompt that is used once costs more than not caching it.
• Each model sets a minimum cacheable prefix, between 1024 and 4096 tokens depending on the model. Under that minimum Anthropic ignores the breakpoints silently, so the request succeeds, the response is normal, and nothing is cached.

For the models that support caching, the current minimum prefix sizes, and the pricing, see the Anthropic prompt caching docs.

Prompt caching at install time

Setting providers.anthropic.config in the Helm chart writes these fields into the ModelConfig that the chart generates, which saves editing that resource after every install.

providers:
  anthropic:
    config:
      promptCaching: true
      cacheTTL: "5m"

The setting reaches only the generated ModelConfig. A ModelConfig that you create yourself, including the one in Create the ModelConfig, takes the fields in its own spec.anthropic block.

Use the ModelConfig

Reference the ModelConfig by name from an AgentTemplate in the same namespace.

spec:
  modelConfig:
    name: anthropic-model-config

Next steps