Vertex AI and Gemini Provider Configuration in Cynative

Run Cynative with Google Vertex AI or Gemini models. Uses Application Default Credentials. Configure project ID, region, and model selection.

Cynative supports two distinct Google AI providers:

• vertex — Google Cloud’s Vertex AI, authenticated via Application Default Credentials (ADC) or a service-account JSON. Requires a GCP project id and region. Best for workloads that run inside GCP or that need IAM-based access control.
• gemini — Google AI Studio (Gemini API), authenticated with a simple API key. No GCP project needed. Best for quick experimentation or environments outside GCP.

Both providers can run the same Gemini models; the difference is the API surface and auth mechanism you use.

---

Vertex AI

Quick start

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export CYNATIVE_LLM_PROVIDER=vertex
export CYNATIVE_LLM_MODEL=gemini-2.5-pro
export CYNATIVE_LLM_VERTEX_PROJECT_ID=my-gcp-project
export CYNATIVE_LLM_VERTEX_REGION=us-central1
cynative -p "list all Cloud Run services and their ingress settings"

No ~/.cynative/config.yaml file is required, but Vertex always needs project_id and region — there is no single-key fallback for Vertex. A bare CYNATIVE_LLM_API_KEY alone is not sufficient and fails at load with a clear error.

YAML configuration

Flat form (equivalent to the env-var quick start):

llm:
  provider: vertex
  model: gemini-2.5-pro
  vertex:
    project_id: my-gcp-project
    region: us-central1

Full keys[] form (for IAM-role auth, explicit service-account content, etc.):

llm:
  provider: vertex
  model: gemini-2.5-pro
  keys:
    - value: ""
      models: ["*"]
      weight: 1.0
      vertex_key_config:
        project_id: my-gcp-project
        region: us-central1
        auth_credentials: ""         # leave empty for ADC, or paste service-account JSON content

Authentication

Vertex authenticates via the vertex config block, not via a key value. Two credential modes:

• Application Default Credentials (ADC). Leave auth_credentials empty (or unset). The Google SDK resolves credentials automatically — from GOOGLE_APPLICATION_CREDENTIALS (path to a service-account JSON file), Workload Identity on GKE, or the gcloud CLI credentials. This is the recommended path for production and CI.
• Inline service-account JSON. Set auth_credentials to the content of the service-account JSON (not a file path). Useful when you need to embed credentials without filesystem access.

GOOGLE_APPLICATION_CREDENTIALS is read by the Google SDK at request time — Cynative does not treat it as a generic API-key fallback.

Environment variable reference

Environment variable	YAML equivalent	Description
CYNATIVE_LLM_PROVIDER	llm.provider	Must be vertex.
CYNATIVE_LLM_MODEL	llm.model	Gemini model id (e.g. gemini-2.5-pro, gemini-2.0-flash).
CYNATIVE_LLM_VERTEX_PROJECT_ID	llm.vertex.project_id	Required. GCP project id.
CYNATIVE_LLM_VERTEX_REGION	llm.vertex.region	Required. GCP region (e.g. us-central1).
GOOGLE_APPLICATION_CREDENTIALS	(Google SDK env var)	Path to a service-account JSON file. Read by the Google SDK, not by Cynative directly.
CYNATIVE_LLM_NETWORK_CONFIG_DEFAULT_REQUEST_TIMEOUT_IN_SECONDS	llm.network_config.default_request_timeout_in_seconds	Per-request timeout in seconds. Cynative default: 300.
CYNATIVE_LLM_NETWORK_CONFIG_MAX_RETRIES	llm.network_config.max_retries	Retry attempts on 429/5xx errors. Cynative default: 3.
CYNATIVE_LLM_REASONING_EFFORT	llm.reasoning_effort	Reasoning effort level: none, minimal, low, medium, high.
CYNATIVE_LLM_REASONING_MAX_TOKENS	llm.reasoning_max_tokens	Explicit reasoning token budget. Gemini validates this against a per-model range at request time.

---

Gemini (AI Studio)

Quick start

export GEMINI_API_KEY=...
export CYNATIVE_LLM_PROVIDER=gemini
export CYNATIVE_LLM_MODEL=gemini-2.5-pro
cynative -p "..."

No ~/.cynative/config.yaml file is required.

YAML configuration

llm:
  provider: gemini
  model: gemini-2.5-pro
  api_key: env.GEMINI_API_KEY       # optional — falls back to GEMINI_API_KEY env var

Authentication

Get a Gemini API key from aistudio.google.com/app/apikey. No GCP project or IAM configuration is required.

Cynative resolves the key from llm.api_key, CYNATIVE_LLM_API_KEY, or GEMINI_API_KEY, in that order.

This is the AI Studio–flavored Gemini API, separate from Vertex AI. Use the vertex provider above for Google Cloud / IAM-authenticated access to Gemini models.

Environment variable reference

Environment variable	YAML equivalent	Description
GEMINI_API_KEY	llm.api_key	Google AI Studio API key.
CYNATIVE_LLM_PROVIDER	llm.provider	Must be gemini.
CYNATIVE_LLM_MODEL	llm.model	Gemini model id (e.g. gemini-2.5-pro, gemini-2.0-flash).
CYNATIVE_LLM_API_KEY	llm.api_key	Generic key override (takes priority over GEMINI_API_KEY).
CYNATIVE_LLM_NETWORK_CONFIG_DEFAULT_REQUEST_TIMEOUT_IN_SECONDS	llm.network_config.default_request_timeout_in_seconds	Per-request timeout in seconds. Cynative default: 300.
CYNATIVE_LLM_NETWORK_CONFIG_MAX_RETRIES	llm.network_config.max_retries	Retry attempts on 429/5xx errors. Cynative default: 3.
CYNATIVE_LLM_REASONING_EFFORT	llm.reasoning_effort	Reasoning effort level: none, minimal, low, medium, high.
CYNATIVE_LLM_REASONING_MAX_TOKENS	llm.reasoning_max_tokens	Explicit reasoning token budget. Gemini validates this against a per-model range at request time.

---

Prompt caching

Claude models served through Vertex AI participate in Cynative’s automatic prompt-caching (cache breakpoints on tool schemas, system prompt, and recent turns). Native Gemini models on both vertex and gemini apply server-side caching automatically — Cynative’s cache markers are stripped or ignored by Bifrost’s Gemini converter. See the prompt caching section in the overview for full details.

Links

• Vertex AI documentation
• Gemini API documentation
• Bifrost Vertex provider source
• Bifrost Gemini provider source