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. The chat model must be reachable through Foundry’s OpenAI-compatible chat completions API.

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 it in the same namespace as the AgentTemplates that use it, 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: 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.
   model	The model that the deployment serves.
   provider	The provider to use, Foundry.
   foundry.endpoint	The endpoint of your Foundry account.
   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.

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

Authentication

Use the ModelConfig

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

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, then name it from the Harness’s spec.kagent.memory.modelConfigRef.

kubectl apply -f - <<EOF
apiVersion: 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