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 models served through an Azure AI Foundry deployment.

The Foundry provider calls a model deployment in an Azure AI Foundry resource. By default, the chat model must be reachable through Foundry’s OpenAI-compatible chat completions API. To call a Claude model, which Foundry serves over the Anthropic Messages API, set foundry.apiFormat to Anthropic. For more information, see Use a Claude model.

Create the ModelConfig

1. Save your Azure AI Foundry API key as an environment variable.

   export FOUNDRY_API_KEY=<your-foundry-api-key>

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

   kubectl create secret generic foundry-api-key -n kagent --from-literal api-key=$FOUNDRY_API_KEY

3. Create a ModelConfig for your Foundry deployment.

   kubectl apply -f - <<EOF
   apiVersion: api.kagent.dev/v1alpha3
   kind: ModelConfig
   metadata:
     name: foundry-model-config
     namespace: kagent
   spec:
     apiKeySecret: foundry-api-key
     apiKeySecretKey: api-key
     model: gpt-4.1-nano
     provider: Foundry
     foundry:
       endpoint: https://<account>.cognitiveservices.azure.com/
       deployment: gpt-4-1-nano
       apiVersion: "2024-10-21"
   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. For other ways to authenticate, see Authentication.
   model	The model that the deployment serves.
   provider	The provider to use, Foundry.
   foundry.endpoint	The endpoint of your Foundry account. To read it from a ConfigMap instead, see Read the endpoint from a ConfigMap.
   foundry.deployment	The name of the deployment within the account. This field is required.
   foundry.apiVersion	The Foundry API version to call. Defaults to 2024-10-21.

   For the other foundry settings, see Azure AI Foundry provider settings.

Azure AI Foundry provider settings

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

Read the endpoint from a ConfigMap

Set endpointFrom in place of endpoint to take the endpoint from a ConfigMap in the same namespace.

spec:
  provider: Foundry
  model: gpt-4.1-nano
  apiKeySecret: foundry-api-key
  apiKeySecretKey: api-key
  foundry:
    endpointFrom:
      name: foundry-endpoint
      key: endpoint
    deployment: gpt-4-1-nano

When the named ConfigMap or key does not exist, the 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 reports Accepted as False. Inspect it to find which reference failed.

kubectl describe modelconfig foundry-model-config -n kagent

Use a Claude model

Foundry serves Claude models over the Anthropic Messages API and not over the OpenAI-compatible API. Set foundry.apiFormat to Anthropic so that kagent calls the Messages API. The example reuses the Secret that Create the ModelConfig creates.

kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: ModelConfig
metadata:
  name: foundry-claude
  namespace: kagent
spec:
  apiKeySecret: foundry-api-key
  apiKeySecretKey: api-key
  model: claude-sonnet-4-5
  provider: Foundry
  foundry:
    endpoint: https://<account>.cognitiveservices.azure.com/
    deployment: claude-sonnet-4-5
    apiFormat: Anthropic
EOF

kagent sends each request to <endpoint>/anthropic/v1/messages and puts the deployment name in the request’s model field. The apiVersion field has no effect, because the Messages API takes its version from a request header instead. Authentication works as it does for any other Foundry deployment, as described in Authentication.

Authentication

Use the ModelConfig

Reference the ModelConfig by name from an AgentTemplate in the same namespace. To use the ModelConfig from another namespace, see Share a ModelConfig across namespaces.

spec:
  modelConfig:
    name: foundry-model-config

Memory embeddings

A Foundry deployment can also serve the embedding model behind long-term memory. Point a second ModelConfig at your embedding deployment, reusing the Secret that Create the ModelConfig creates, then name it from the Harness’s spec.kagent.memory.modelConfigRef.

kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: ModelConfig
metadata:
  name: foundry-embeddings
  namespace: kagent
spec:
  apiKeySecret: foundry-api-key
  apiKeySecretKey: api-key
  model: text-embedding-3-small
  provider: Foundry
  foundry:
    endpoint: https://<account>.cognitiveservices.azure.com/
    deployment: text-embedding-3-small
EOF

Troubleshooting

Next steps