# How to Use Vertex AI with Application Default Credentials in pi-ai

> Learn to use Vertex AI with Application Default Credentials in pi-ai. Configure project and location using environment variables for seamless authentication and access.

- Repository: [Mario Zechner/pi-mono](https://github.com/badlogic/pi-mono)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The pi-ai package automatically authenticates with Google Vertex AI using Application Default Credentials, requiring only environment variables for project and location configuration.**

The `pi-ai` package within the [badlogic/pi-mono](https://github.com/badlogic/pi-mono) repository treats Google Vertex AI as a first-class LLM provider. By leveraging **Application Default Credentials (ADC)**, you can authenticate securely without hardcoding API keys or service account tokens in your application code.

## How Application Default Credentials Work in pi-ai

The authentication system relies on two core mechanisms: credential detection from standard ADC paths and runtime resolution of project metadata.

### Credential Detection Mechanism

In [`packages/ai/src/env-api-keys.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/env-api-keys.ts), the system checks for ADC files at standard locations. The code inspects the `GOOGLE_APPLICATION_CREDENTIALS` environment variable and falls back to the default path at `$HOME/.config/gcloud/application_default_credentials.json`. When valid credentials are detected, the function returns the sentinel value `"<authenticated>"` rather than exposing the actual token.

```typescript
// From packages/ai/src/env-api-keys.ts (lines 63-73)
// Returns "<authenticated>" when ADC is properly configured
const result = getEnvApiKey("google-vertex");
// result === "<authenticated>"

```

### Project and Location Resolution

The Vertex AI provider implementation in [`packages/ai/src/providers/google-vertex.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/google-vertex.ts) enforces strict validation of environment variables. The code requires both `GOOGLE_CLOUD_PROJECT` (or the legacy `GCLOUD_PROJECT`) and `GOOGLE_CLOUD_LOCATION` to be set, throwing descriptive errors if either is missing.

```typescript
// From packages/ai/src/providers/google-vertex.ts (lines 41-48, 51-56)
// Throws if GOOGLE_CLOUD_PROJECT is not set
// Throws if GOOGLE_CLOUD_LOCATION is not set

```

## Configuring Your Environment for Vertex AI

Before using Vertex AI in your application, complete these one-time setup steps:

1. **Authenticate with gcloud** to generate Application Default Credentials:

   ```bash
   gcloud auth application-default login
   ```

2. **Set required environment variables** in your shell or `.env` file:

   ```bash
   export GOOGLE_CLOUD_PROJECT=your-gcp-project-id
   export GOOGLE_CLOUD_LOCATION=us-central1
   ```

3. **Verify the configuration** by checking that `$HOME/.config/gcloud/application_default_credentials.json` exists.

## Implementing Vertex AI in Your Code

Once your environment is configured, use the `getModel` function to obtain a Vertex AI model instance. The following example demonstrates the complete workflow:

```typescript
import { getModel } from "@pi/ai";

// Obtain a Vertex model - authentication happens automatically via ADC
const vertexModel = getModel("google-vertex", "gemini-3-flash-preview");

// Optional: Override project/location per request
const options = {
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
};

// Generate content using the model
const response = await vertexModel.generate({
  messages: [{ role: "user", content: "Explain ADC in one sentence." }],
  ...options,
});

```

The test suite in [`packages/ai/test/stream.test.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/test/stream.test.ts) demonstrates this same pattern, constructing `vertexOptions` from environment variables and passing them to helper functions that exercise the streaming implementation.

## Understanding the Authentication Flow

The Vertex AI provider registration occurs in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/register-builtins.ts), where the system adds the Google Vertex provider to the global registry. When you call `getModel("google-vertex", ...)`, the system:

1. Invokes `getEnvApiKey("google-vertex")` to verify ADC is configured
2. Resolves project and location from environment variables in `streamGoogleVertex`
3. Instantiates a `GoogleGenAI` client with `vertexai: true` and the resolved configuration
4. Streams responses using the generated request parameters

The sentinel value `"<authenticated>"` acts as a secure placeholder that satisfies the type system while ensuring no credentials are logged or transmitted unnecessarily.

## Summary

- **Application Default Credentials** eliminate the need for API keys in pi-ai by leveraging standard gcloud authentication files.
- **Environment variables** `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` are mandatory for Vertex AI operations.
- **Automatic detection** occurs in [`env-api-keys.ts`](https://github.com/badlogic/pi-mono/blob/main/env-api-keys.ts), which returns `"<authenticated>"` when ADC is properly configured.
- **Provider implementation** in [`google-vertex.ts`](https://github.com/badlogic/pi-mono/blob/main/google-vertex.ts) handles project resolution and API streaming with the `GoogleGenAI` client.

## Frequently Asked Questions

### What environment variables are required for Vertex AI authentication in pi-ai?

You must set `GOOGLE_CLOUD_PROJECT` (or the legacy `GCLOUD_PROJECT`) and `GOOGLE_CLOUD_LOCATION`. The code in [`packages/ai/src/providers/google-vertex.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/google-vertex.ts) throws explicit errors if either variable is missing, ensuring you know exactly which configuration is absent.

### How does pi-ai handle authentication without exposing API keys?

The system uses **Application Default Credentials** via the `getEnvApiKey` function in [`packages/ai/src/env-api-keys.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/env-api-keys.ts). When it detects a valid ADC file at the standard gcloud location or via `GOOGLE_APPLICATION_CREDENTIALS`, it returns the sentinel string `"<authenticated>"`. This placeholder satisfies the authentication check without ever loading the actual credential into application memory where it could be logged.

### Can I override project and location settings per request?

Yes. While the provider reads `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` by default, you can pass explicit `project` and `location` properties in the options object when calling `generate()` or other model methods. This allows you to target different GCP projects or regions for specific workloads without changing global environment variables.

### Where is the Vertex AI provider registered in the codebase?

The provider is registered in [`packages/ai/src/providers/register-builtins.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/register-builtins.ts) around lines 55-60. This file adds the Google Vertex provider to the internal registry under the key `"google-vertex"`, making it available when you call `getModel("google-vertex", modelName)` from the `@pi/ai` package.