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

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 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, 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.

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

// 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:

   gcloud auth application-default login

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

   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:

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 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, 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, which returns "<authenticated>" when ADC is properly configured.
• Provider implementation in 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}