> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cynative.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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):

```yaml theme={null}
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.):

```yaml theme={null}
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

```bash theme={null}
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

```yaml theme={null}
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](https://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.

<Note>
  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.
</Note>

### 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](/providers/overview#prompt-caching) in the overview for full details.

## Links

* [Vertex AI documentation](https://cloud.google.com/vertex-ai/docs)
* [Gemini API documentation](https://ai.google.dev/gemini-api/docs)
* [Bifrost Vertex provider source](https://github.com/maximhq/bifrost/tree/main/core/providers/vertex)
* [Bifrost Gemini provider source](https://github.com/maximhq/bifrost/tree/main/core/providers/gemini)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.