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 Claude models through Google Cloud Vertex AI on a Claude harness.

Google Cloud Vertex AI serves both Gemini and Claude models, and 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 schema has a provider for each: GeminiVertexAI and AnthropicVertexAI. Which of them works depends on the runtime that your 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.

For the full provider matrix across all four runtimes, see Agent harness.

The difference is how each runtime receives the Google credentials. Vertex AI authenticates with a service account key, which is a JSON document rather than a single string. The claude runtime takes that document as an environment variable. The kagent runtime instead writes it to a file and mounts it, and an agent running on 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 cannot mount files.

Claude models on a Claude harness

1. Create a Google service account key with access to Vertex AI, and store the JSON in a Kubernetes Secret. Create it in the same namespace as the AgentTemplates that use it, such as kagent.

   kubectl create secret generic kagent-vertex -n kagent \
     --from-file=credentials.json=<path-to-your-service-account-key>.json

2. Create a ModelConfig that uses the AnthropicVertexAI provider.

   kubectl apply -f - <<EOF
   apiVersion: kagent.dev/v1alpha3
   kind: ModelConfig
   metadata:
     name: vertex-model-config
     namespace: kagent
   spec:
     apiKeySecret: kagent-vertex
     apiKeySecretKey: credentials.json
     model: claude-sonnet-4@20250514
     provider: AnthropicVertexAI
     anthropicVertexAI:
       projectID: my-gcp-project
       location: us-east5
   EOF

   Field	Description
   apiKeySecret	The name of the Kubernetes Secret that holds the service account key.
   apiKeySecretKey	The key within that Secret that holds the JSON document.
   model	The Vertex AI model ID, such as claude-sonnet-4@20250514.
   provider	The provider to use, AnthropicVertexAI.
   anthropicVertexAI.projectID	Your Google Cloud project ID. This field is required, and must match the project_id inside the service account key.
   anthropicVertexAI.location	The Vertex AI region, such as us-east5. This field is required.

   The claude runtime accepts no other settings in the anthropicVertexAI block yet, and rejects a ModelConfig that sets defaultHeaders, tls, or apiKeyPassthrough. For every field, including its type, default, and validation rules, see the API reference.

3. Pair the ModelConfig with a Harness that selects the claude runtime.

   spec:
     claude: {}
     workload:
       image: ghcr.io/kagent-dev/kagent/claude-harness@sha256:23b59459d66ce3162892239b035ba924cd1d64a6e3826db277599e9a98b2f36a

What kagent checks before it compiles

kagent validates the service account key at compile time rather than failing at run time, so a malformed credential surfaces on the AgentTemplate’s Compatible condition.

• The Secret key must hold valid JSON.
• The document must be a service_account key. Other credential types are not accepted yet.
• Its project_id must match anthropicVertexAI.projectID.
• Its token_uri must be https://oauth2.googleapis.com.

Gemini models on Vertex AI

The GeminiVertexAI provider does not compile on any runtime. On a kagent Harness it fails with ModelConfig requires volume mounts unsupported by Substrate ActorTemplate, and the claude runtime does not accept the provider at all.

To reach Gemini models, use the Gemini provider, which serves the same model family through the Google AI Studio API and authenticates with an ordinary API key.

Next steps